> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Analytics API
> Read organization usage, session activity, user data, and team analytics over HTTPS with an Embedder bearer token scoped to analytics:read.
The Analytics API exposes organization usage data over HTTPS. Access requires an organization with Analytics enabled and a token with the `analytics:read` scope.
The production API base is:
```text theme={"system"}
https://backend-service-prod.embedder.com/api/v1
```
Some organizations use a dedicated tenant URL. Use the API URL provided for that tenant instead of the production host.
Create a scoped token in the Embedder web app and find your organization ID.
## Make your first request
Send the token in the `Authorization` header. The example below reads a seven-day organization overview:
```bash theme={"system"}
export EMBEDDER_ANALYTICS_TOKEN="your-token"
export EMBEDDER_ORGANIZATION_ID="your-organization-id"
curl --get \
"https://backend-service-prod.embedder.com/api/v1/organizations/$EMBEDDER_ORGANIZATION_ID/analytics/overview" \
-H "Authorization: Bearer $EMBEDDER_ANALYTICS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode "from=2026-08-01T00:00:00.000Z" \
--data-urlencode "to=2026-08-08T00:00:00.000Z"
```
Use ISO 8601 timestamps for `from` and `to`. URL-encode query values rather than concatenating untrusted input into the request URL.
Keep the token in a secret store or process environment. Do not put it in a
URL, source file, repository, or command that will be saved to shell history.
## Endpoints
All endpoint paths below are relative to the production API base.
### Organization overview
```text theme={"system"}
GET /organizations/{organizationId}/analytics/overview
```
Required query parameters:
* `from`: beginning of the reporting window as an ISO 8601 timestamp
* `to`: end of the reporting window as an ISO 8601 timestamp
The response contains totals for the requested window, a comparison aggregate, and daily values:
```json theme={"system"}
{
"from": "2026-08-01T00:00:00.000Z",
"to": "2026-08-08T00:00:00.000Z",
"totals": {
"sessions": 42,
"activeSeconds": 18420,
"wallSeconds": 27180,
"inputTokens": 390000,
"outputTokens": 87000,
"cacheReadTokens": 125000,
"cacheWriteTokens": 24000,
"totalTokens": 626000,
"credits": 31.4,
"turns": 196,
"toolCalls": 733,
"activeUsers": 8,
"activeTeams": 3
},
"previous": null,
"days": [
{
"date": "2026-08-01",
"sessions": 6,
"activeSeconds": 2380,
"wallSeconds": 3610,
"inputTokens": 51000,
"outputTokens": 12000,
"cacheReadTokens": 17000,
"cacheWriteTokens": 3000,
"totalTokens": 83000,
"credits": 4.2,
"turns": 27,
"toolCalls": 104
}
]
}
```
`totals` and `previous` can be `null` when no aggregate is available.
### Users
List users:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/users?from={timestamp}&to={timestamp}
```
The response is an object with a `users` array. Each user includes the shared usage metrics plus:
* `userId`
* `name`
* `email`
* `lastActiveAt`
Read one user:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/users/{userId}?from={timestamp}&to={timestamp}
```
The detail response includes `totals`, daily usage in `days`, usage grouped by client in `byClient`, and usage grouped by project in `byProject`.
### Teams
List teams:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/teams?from={timestamp}&to={timestamp}
```
The response is an object with a `teams` array. Each team includes the shared usage metrics plus:
* `teamId`
* `name`
* `members`
* `lastActiveAt`
Read one team:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/teams/{teamId}?from={timestamp}&to={timestamp}
```
The detail response includes `totals`, daily usage in `days`, and the team's analytics rows in `members`.
### Sessions
List sessions:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/sessions
```
Query parameters:
* `from` and `to`: ISO 8601 reporting window
* `limit`: number of rows requested
* `cursor`: opaque value returned as `nextCursor` by the previous response
* `userId`: return sessions for one user
* `teamId`: return sessions for one team
* `outcome`: `success`, `partial`, `failure`, `abandoned`, or `unknown`
* `client`: return sessions from one client
```bash theme={"system"}
curl --get \
"https://backend-service-prod.embedder.com/api/v1/organizations/$EMBEDDER_ORGANIZATION_ID/analytics/sessions" \
-H "Authorization: Bearer $EMBEDDER_ANALYTICS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode "from=2026-08-01T00:00:00.000Z" \
--data-urlencode "to=2026-08-08T00:00:00.000Z" \
--data-urlencode "outcome=success" \
--data-urlencode "limit=25"
```
The list response contains session rows and the cursor for the next page:
```json theme={"system"}
{
"sessions": [
{
"sessionId": "session_123",
"startedAt": "2026-08-07T18:21:10.000Z",
"endedAt": "2026-08-07T18:34:42.000Z",
"lastEventAt": "2026-08-07T18:34:42.000Z",
"activeSeconds": 612,
"wallSeconds": 812,
"totalTokens": 18420,
"credits": 0.92,
"turns": 9,
"promptCount": 3,
"toolCalls": 27,
"toolFailures": 1,
"mcpToolCalls": 4,
"client": "vscode",
"models": ["example-model"],
"goal": "Investigate a firmware regression",
"outcome": "success",
"userId": "user_123",
"userName": "Ada Lovelace",
"userEmail": "ada@example.com",
"teamId": "team_123",
"teamName": "Firmware",
"projectName": "sensor-hub"
}
],
"nextCursor": "opaque-next-page-cursor"
}
```
Pass `nextCursor` back unchanged as the next request's `cursor`. A `null` value means there is no next page.
Read one session:
```text theme={"system"}
GET /organizations/{organizationId}/analytics/sessions/{sessionId}
```
The detail response adds input, output, cache-read, and cache-write token counts; tool call and failure durations in `toolBreakdown`; files written; error count; app version; outcome confidence; and any generated summary.
## Shared usage fields
Aggregate user, team, overview, and daily rows use these fields:
| Field | Description |
| ------------------ | ----------------------------------------- |
| `sessions` | Session count |
| `activeSeconds` | Time spent actively processing work |
| `wallSeconds` | Elapsed session time |
| `inputTokens` | Model input tokens |
| `outputTokens` | Model output tokens |
| `cacheReadTokens` | Tokens read from cache |
| `cacheWriteTokens` | Tokens written to cache |
| `totalTokens` | Total token usage reported by the service |
| `credits` | Embedder credits consumed |
| `turns` | Agent turn count |
| `toolCalls` | Tool call count |
Counts and durations are numbers. Timestamps are ISO 8601 strings. Identity fields can be `null` where activity is no longer associated with an available user, team, or project.
## Authorization and errors
The token owner's organization membership, role, and enabled features still limit the data returned. The `analytics:read` scope does not grant access to another organization.
Error responses can include:
```json theme={"system"}
{
"error": "The request could not be completed",
"code": "machine_readable_code",
"correlationId": "req_7f3a"
}
```
* `401`: the token is missing, invalid, expired, or revoked
* `403`: the token lacks `analytics:read`, the organization is unavailable to the token owner, or Analytics is not enabled
* `429`: wait for the duration in `Retry-After` before retrying
* `5xx`: the service could not complete the request
Include `correlationId` when contacting Embedder support. Retry only idempotent `GET` requests, and apply backoff for `429` and transient server failures.