Analytics

Programmatic access to the organization-wide cost, usage, and activity data shown on the admin Members, Workflows, and Projects dashboards. These endpoints exist so you can pull the same columns you would otherwise export by hand from the admin UI.

All analytics endpoints require the admin:analytics:read scope — the API key owner must be an organization admin. Keys with the broad admin scope are also accepted.

Experimental

These endpoints are experimental and may change without notice while we stabilize the analytics surface.

List organization agent sessions

GET /analytics/agents

Use an API key with admin:analytics:read to list agent sessions across every member of the organization. This is the organization-wide list surface for agent/session analytics; GET /agents lists only the authenticated user's sessions.

The response has the same shape as List agents. Use the returned id, or an assistantSessionId from usage events, with these read-only Agent API endpoints:

Those Agent API read endpoints accept admin:analytics:read and can read sessions owned by any user in the key owner's organization. Mutating routes such as follow-up, stop, and delete still require agent-owner developer access.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Default	Description
`limit`	number	20	Number of sessions to return (max 100).
`cursor`	string	—	Pagination cursor from previous response.
`status`	string	—	Filter by status.
`workflowId`	string	—	Filter by workflow ID. Pass `null` to exclude agents launched from a workflow.

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/agents?limit=100" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List user analytics

GET /analytics/users

Per-user cost and usage, matching the admin Members page: AI usage, spend cap, spend status, organization role, and last-active time.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Max results per page (default 100, max 1000).
`cursor`	string	No	Pagination cursor from a previous response's `nextCursor`.
`email`	string	No	Filter by partial, case-insensitive email match.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "disabled": false,
      "role": "admin",
      "joinedAt": "2026-01-15T09:30:00.000Z",
      "lastActiveAt": "2026-04-01T12:00:00.000Z",
      "aiUsageCents": 1200,
      "spendCapCents": 2000,
      "spendStatus": "within_limit"
    }
  ],
  "spendLimitsEnabled": true,
  "defaultSpendCapCents": 5000,
  "nextCursor": null,
  "totalCount": 42
}

Field	Type	Description
`role`	string or null	Organization role slug (e.g. `admin`, `member`). Null when it cannot be resolved.
`joinedAt`	string (ISO 8601)	When the account was created.
`lastActiveAt`	string (ISO 8601) or null	Start of the user's most recent assistant session, or null.
`aiUsageCents`	number	Cumulative AI spend attributed to the user, in US cents.
`spendCapCents`	number or null	Effective per-user cap (custom, else org default), in US cents. Null when spend limits are off.
`spendStatus`	`unlimited` \| `within_limit` \| `over_limit`	`unlimited` when limits are off; otherwise whether usage meets or exceeds the cap.
`spendLimitsEnabled`	boolean	Whether per-user spend limits are enabled for the organization.
`defaultSpendCapCents`	number or null	Organization default per-user spend cap, in US cents.

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/users?limit=100" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List workflow analytics

GET /analytics/workflows

Org-wide workflow run and spend stats, matching the admin Workflows page: owner, visibility, project, run count, last run, and average spend per run.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Max results per page (default 20, max 100).
`cursor`	string	No	Pagination cursor from a previous response's `nextCursor`.
`search`	string	No	Filter by workflow name or owner name/email (partial match).
`sort`	string	No	One of `recent` (default), `runs`, `spend`, `last-run`, `name`.
`period`	string	No	Time window shortcut: `1d`, `7d`, `30d`, or `all` (default). Ignored when `startDate`/`endDate` are set.
`startDate`	string	No	Start of the window (inclusive). See Time windows.
`endDate`	string	No	End of the window (inclusive). See Time windows.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "name": "Weekly Report",
      "description": "Generate the weekly report",
      "owner": {
        "id": "019abc12-3456-7890-abcd-ef1234567891",
        "name": "Alice Johnson",
        "email": "alice@example.com"
      },
      "projectId": "019abc12-3456-7890-abcd-ef1234567892",
      "projectName": "Operations",
      "projectNumber": "2024-0142",
      "visibility": "public",
      "runCount": 12,
      "lastRunAt": "2026-04-01T08:00:00.000Z",
      "avgSpendCents": 83
    }
  ],
  "nextCursor": null,
  "totalCount": 7
}

avgSpendCents is the average spend per run in US cents (may be fractional), includes sub-agent spend rolled into each run, and is null when a workflow has no spend in the selected window.

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/workflows?sort=spend&period=30d" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List project analytics

GET /analytics/projects

Org-wide project activity, matching the admin Projects page: owners, members, attached files, workflow/session counts, and AI session spend. This data is not available anywhere else in the API.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Max results per page (default 50, max 100).
`cursor`	string	No	Pagination cursor from a previous response's `nextCursor`.
`search`	string	No	Filter by project name, project number, or owner name/email (partial match).
`sort`	string	No	One of `spend` (default), `members`, `workflows`, `workflow_runs`, `assistant_sessions`, `files`, `recent`, `name`.
`period`	string	No	Time window shortcut: `1d`, `7d`, `30d`, or `all` (default). Ignored when `startDate`/`endDate` are set.
`startDate`	string	No	Start of the window (inclusive). See Time windows.
`endDate`	string	No	End of the window (inclusive). See Time windows.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567892",
      "name": "Operations",
      "projectNumber": "2024-0142",
      "createdAt": "2026-01-10T09:30:00.000Z",
      "owners": [{ "name": "Alice Johnson", "email": "alice@example.com" }],
      "memberCount": 8,
      "attachedFileCount": 120,
      "workflowCount": 3,
      "workflowRunCount": 40,
      "assistantSessionCount": 15,
      "aiSessionSpendCents": 1247
    }
  ],
  "nextCursor": null,
  "totalCount": 3
}

aiSessionSpendCents is the project's total AI session spend for the window in US cents (may be fractional).

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/projects?sort=spend&period=7d" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List usage events

GET /analytics/usage-events

The granular, per-event spend feed that every aggregate above rolls up. Use it to reconcile costs to the cent and build custom rollups. Defaults to the last 30 days when no range is given. Events are returned newest first. All money is in US cents.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Required	Description
`limit`	number	No	Max results per page (default 100, max 1000).
`cursor`	string	No	Pagination cursor from a previous response's `nextCursor`.
`startDate`	string	No	Start of the window (inclusive). Defaults to 30 days ago. See Time windows.
`endDate`	string	No	End of the window (inclusive). See Time windows.
`userId`	string	No	Filter to a specific user (uuid).
`projectId`	string	No	Filter to a specific project (uuid).
`workflowId`	string	No	Filter to a specific workflow (uuid).
`model`	string	No	Filter to a specific model name.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567899",
      "occurredAt": "2026-04-01T08:00:00.000Z",
      "userId": "019abc12-3456-7890-abcd-ef1234567890",
      "model": "claude-4.5-sonnet",
      "costCents": 21.36,
      "source": "assistant",
      "projectId": "019abc12-3456-7890-abcd-ef1234567892",
      "projectNumber": "2024-0142",
      "workflowId": null,
      "assistantSessionId": "019abc12-3456-7890-abcd-ef123456789a",
      "inputTokens": 126,
      "outputTokens": 450,
      "cacheCreationTokens": 6112,
      "cacheReadTokens": 11964
    }
  ],
  "nextCursor": "019abc12-3456-7890-abcd-ef1234567899",
  "totalCount": 113
}

source is assistant (agent/chat spend), parse (document parsing), or other. Sum costCents across events to reconcile against the aggregates. projectNumber is the attributed project's job or project number, or null if the project does not have one.

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/usage-events?startDate=30d&model=claude-4.5-sonnet" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Get daily spend

GET /analytics/daily-spend

AI spend bucketed by UTC day over a date range, optionally split by a dimension. Defaults to the last 30 days when no range is given. All money is in US cents.

Scope: admin:analytics:read · Rate limit: Analytics (30 req / min)

Query parameters

Parameter	Type	Required	Description
`startDate`	string	No	Start of the window (inclusive). Defaults to 30 days ago. See Time windows.
`endDate`	string	No	End of the window (inclusive). See Time windows.
`by`	string	No	Split each day by `none` (default), `user`, `project`, `workflow`, or `model`.

Response

{
  "data": [
    {
      "date": "2026-03-18",
      "groupKey": "gpt-5",
      "spendCents": 1240.5,
      "eventCount": 42
    },
    {
      "date": "2026-03-19",
      "groupKey": "gpt-5",
      "spendCents": 980,
      "eventCount": 31
    }
  ],
  "startDate": "2026-03-01T00:00:00.000Z",
  "endDate": null
}

groupKey carries the dimension value (user/project/workflow id, or model name) or is null when by=none.

Example

curl "https://<your-domain>.nomic.ai/api/v0/analytics/daily-spend?startDate=30d&by=project" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Time windows

The workflow, project, usage-event, and daily-spend endpoints accept a flexible time window via startDate and endDate (each optional and inclusive). When either is set it overrides the period shortcut. Both accept:

Relative shortcuts: now, today, yesterday, 7d, 24h, 30m, 300s (the N<unit> forms mean "N units ago").
ISO 8601: 2026-01-15T12:00:00Z.
Calendar day: 2026-01-15 (interpreted as UTC midnight).
Unix timestamp: seconds (1705315200) or milliseconds (1705315200000).

Example — a precise calendar month:

curl "https://<your-domain>.nomic.ai/api/v0/analytics/workflows?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List organization agent sessions​

Query parameters​

Example​

List user analytics​

Query parameters​

Response​

Example​

List workflow analytics​

Query parameters​

Response​

Example​

List project analytics​

Query parameters​

Response​

Example​

List usage events​

Query parameters​

Response​

Example​

Get daily spend​

Query parameters​

Response​

Example​

Time windows​

List organization agent sessions

Query parameters

Example

List user analytics

Query parameters

Response

Example

List workflow analytics

Query parameters

Response

Example

List project analytics

Query parameters

Response

Example

List usage events

Query parameters

Response

Example

Get daily spend

Query parameters

Response

Example

Time windows