# Analytics API

## Overview

The Enterprise Analytics API provides secure, read-only access to analytics data through a single GET endpoint, with response transformation controlled by a `format` query parameter. Developers can use it to retrieve a raw analytics overview, SCORM-structured JSON, or xAPI-formatted output for ingestion into an LMS, LRS, data warehouse, or AI automation pipeline.

This API is designed for teams that need to:

* Pull analytics into an LMS or LRS.
* Copy response data into another system for reporting or compliance.
* Feed activity records into automation tools like n8n or Make.
* Pass structured analytics into an AI agent pipeline for summarization, orchestration, or downstream decisioning.

### Access and setup <a href="#access-and-setup" id="access-and-setup"></a>

To test the API today, a customer can register a new account under the **XR Manager**, then be granted access to the **Enterprise features** inside **XR Manager**, where they can generate an API key for the public analytics API. The API uses Bearer authentication, which matches standard API authentication patterns.

Once the API key is created, the key can be used in any client that supports Bearer token authentication, including ReqBin, Postman, cURL, n8n, Make, and custom applications. ReqBin specifically supports testing API endpoints directly in the browser and validating returned JSON responses.

### Base endpoint <a href="#base-endpoint" id="base-endpoint"></a>

```
GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics
```

The requested output format is selected using the `format` query parameter:

```
GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=raw
GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=scorm
GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=xapi
```

You can also filter results with date parameters such as `start` and `end`, and additional filters may be supported as the endpoint evolves.&#x20;

### Working test example <a href="#working-test-example" id="working-test-example"></a>

A working test request is available now using the production endpoint below:

```
  GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=raw&start=2025-01-01&end=2026-03-01
```

To test it:

1. Be sure to have captured analytics data from interacting with an XR Module.
2. Generate an API key in XR Manager after Enterprise access has been enabled.
3. Open ReqBin or another API client.
4. Paste the endpoint URL.
5. Set the method to `GET`.
6. Add the API key as a Bearer token in the `Authorization` header.
7. Send the request and inspect the JSON response. ReqBin supports this workflow directly in the browser and is suitable for quick validation.

**NOTE:** If utilizing Whitelisted IP Addresses, the request must come from the IP setup in the **XR Manager**.&#x20;

### Authentication <a href="#authentication" id="authentication"></a>

All API requests must include the API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer <API_KEY>
```

Bearer authentication should only be used over HTTPS, and the production analytics endpoint is already served over HTTPS.&#x20;

### Supported formats <a href="#supported-formats" id="supported-formats"></a>

The `format` query parameter supports the following values:

| Format  | Purpose                                                                                          |
| ------- | ------------------------------------------------------------------------------------------------ |
| `raw`   | Returns the original analytics payload for ETL, AI workflows, and custom processing.             |
| `scorm` | Returns analytics mapped into a SCORM-structured JSON response.                                  |
| `xapi`  | Returns analytics mapped into xAPI-style structured data for LRS and interoperability workflows. |

This format-driven design lets a single endpoint serve multiple integration targets without requiring separate APIs for each consumer type.

### Date filtering <a href="#date-filtering" id="date-filtering"></a>

The endpoint currently supports date-range filtering through the `start` and `end` query parameters, as shown in the live test example. This allows consumers to limit the returned analytics window for sync jobs, LMS imports, backfills, and agent workflows.

\
Example:

```
GET https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=xapi&start=2025-01-01&end=2026-04-01
```

### Example requests <a href="#example-requests" id="example-requests"></a>

#### Raw output <a href="#raw-output" id="raw-output"></a>

```
curl --request GET \
  --url 'https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=raw&start=2025-01-01&end=2026-04-01' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Accept: application/json'
```

#### SCORM JSON output <a href="#scorm-json-output" id="scorm-json-output"></a>

```
curl --request GET \
  --url 'https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=scorm&start=2025-01-01&end=2026-04-01' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Accept: application/json'
```

#### xAPI output <a href="#xapi-output" id="xapi-output"></a>

```
curl --request GET \
  --url 'https://prod-xrmanager-us.elitexr.net/api/v3/analytics?format=xapi&start=2025-01-01&end=2026-04-01' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Accept: application/vnd.xapi+json'
```

### Response behavior <a href="#response-behavior" id="response-behavior"></a>

The API returns analytics in the requested format and should include response headers that indicate the transformation applied. For SCORM and raw JSON, the response should use `Content-Type: application/json`, while xAPI responses should use `Content-Type: application/vnd.xapi+json`.

**Recommended response headers:**

```
Content-Type: application/json
X-Transformation-Version: SCORM-1.2
```

or

```
Content-Type: application/vnd.xapi+json
X-Transformation-Version: xAPI-2.0
```

Including a transformation version header improves traceability for LMS, LRS, and automation consumers that need to audit schema behavior over time.

### Important implementation note <a href="#important-implementation-note" id="important-implementation-note"></a>

This API does **not** provide a packaged SCORM course or a SCORM upload bundle. Instead, when `format=scorm` is requested, the endpoint returns **JSON structured to conform to the SCORM schema**, which can then be mapped, synced, or imported into an LMS or another downstream system as needed.

Likewise, there is no separate validation SCORM package required just to verify connectivity. The response format itself is the validation path: request `scorm`, `xapi`, or `raw`, inspect the returned JSON, and then import or map that data into the destination system if the platform supports it.

### LMS, LRS, and AI pipeline usage <a href="#lms-lrs-and-ai-pipeline-usage" id="lms-lrs-and-ai-pipeline-usage"></a>

#### LMS workflows <a href="#lms-workflows" id="lms-workflows"></a>

If your LMS expects structured completion, score, or interaction data, request `format=scorm` and map the returned JSON into the LMS import or synchronization layer. Because the payload is JSON rather than a SCORM package, this is best suited for platforms that support API-driven import or middleware-based mapping.

#### LRS workflows <a href="#lrs-workflows" id="lrs-workflows"></a>

If your target is an LRS, request `format=xapi` and forward the returned statements or mapped event objects into the record store. xAPI is designed for interoperable activity data exchange, which makes it the most natural output for LRS pipelines.

#### AI and automation workflows <a href="#ai-and-automation-workflows" id="ai-and-automation-workflows"></a>

For n8n, Make, or agentic pipelines, `format=raw` is usually the best starting point because it preserves the source event structure for summarization, enrichment, clustering, or downstream decision logic. Use `xapi` when you want a more semantically normalized event format for automation.

### Security and key lifecycle <a href="#security-and-key-lifecycle" id="security-and-key-lifecycle"></a>

Enterprise API keys should be treated as sensitive credentials and managed through the **XR Manager**. The intended security model includes cryptographically strong key generation, hashed key storage, optional IP restrictions, default 90-day expiration dates, revocation, rotation, and default per-key rate limiting.

A practical operational note for testing is that **API keys cannot be deleted once made and used which will show a Usage Count of more than 0 in the XR Manager.** They are retained for compliance purposes. After testing is complete, the key can be revoked at any time to terminate access.

### Key management capabilities <a href="#key-management-capabilities" id="key-management-capabilities"></a>

Enterprise customers should be able to manage keys in **XR Manager** by:

* Generating new API keys.
* Labeling keys for operational clarity.
* Rotating or revoking keys.
* Expiration dates: default target lifecycle of 90 days.
* Reviewing usage metrics.

### Error handling <a href="#error-handling" id="error-handling"></a>

The API should return standard HTTP errors for invalid requests and authorization failures:

| Status                  | Meaning                                                  |
| ----------------------- | -------------------------------------------------------- |
| `400 Bad Request`       | Missing `format`, invalid `format`, or unsupported value |
| `401 Unauthorized`      | Missing or invalid API key                               |
| `403 Forbidden`         | Key does not have permission for the requested format    |
| `429 Too Many Requests` | Rate limit exceeded                                      |

Example error response:

```
{
  "error": "format_not_supported",
  "message": "Supported formats: scorm, xapi, raw"
}
```

### Testing tools <a href="#testing-tools" id="testing-tools"></a>

Any API client that supports Bearer token authentication can be used to call the endpoint and retrieve the JSON response directly.

Recommended testing tools:

* ReqBin for quick browser-based testing.
* Postman for saved collections and team workflows.
* cURL for terminal validation and CI scripts.
* n8n or Make for automation pipeline prototyping.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://elite-xr.gitbook.io/elite-xr-developer/analytics-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.