Analytics API

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:

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.

Get an Analytics API token

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:

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

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:

{
  "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:

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:

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:

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:

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:

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

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:

{
  "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:

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:

{
  "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.

Get started

Core concepts

Complex workflows

Monitor and debug

Project tools

Customize

Integrations

Automation

CLI

Reference

API

Get an Analytics API token

Make your first request

Endpoints

Organization overview

Users

Teams

Sessions

Shared usage fields

Authorization and errors

Get an Analytics API token

​Make your first request

​Endpoints

​Organization overview

​Users

​Teams

​Sessions

​Shared usage fields

​Authorization and errors

Make your first request

Endpoints

Organization overview

Users

Teams

Sessions

Shared usage fields

Authorization and errors