Data API overview

The Data API exposes the analytics Moda computes over your ingested traces as HTTP endpoints. A trace is one full agent run, identified by its conversation_id (the trace ID); endpoint paths and JSON fields keep the conversation / conversation_id names for backwards compatibility. It serves the same data as the dashboard, so you can use it from CI jobs, coding agents, and scripts. The Moda CLI is built on this API.

Base URL

https://moda.dev/api/v1/data

Authentication

Every endpoint requires an API key (called an ingestion key in the dashboard) in the x-api-key header:

x-api-key: moda_sk_...

Keys are created at Settings → Ingestion keys and are shown once at creation. A key is bound to one tenant; every response is scoped to that tenant. See Authentication for key management.

The Data API and the Ingestion API accept the same moda_sk_ keys but read different headers. The Data API reads x-api-key; the Ingestion API reads Authorization: Bearer. A key sent in the wrong header returns 401. CLI session tokens are not valid here.

A missing key returns 401 with "message": "API key is required"; an invalid or revoked key returns:

{
  "message": "Invalid or revoked API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Make your first request

curl "https://moda.dev/api/v1/data/overview?days_back=7" \
  -H "x-api-key: YOUR_MODA_API_KEY"

{
  "period": { "days": 7 },
  "conversations": { "total": 1284, "trend_pct": 12.5 },
  "frustrations": { "total_analyzed": 1102, "frustrated": 43, "at_risk": 18, "rate_pct": 3.9 },
  "tool_failures": { "total": 67, "conversations": 51, "tools": 6 },
  "top_clusters": [
    { "node_id": "node_3", "label": "Billing and refunds", "summary": "Users ask about invoices, plan changes, and refunds.", "keywords": ["refund", "invoice", "billing"], "segment_count": 214 }
  ],
  "recent_activity": [
    { "conversation_id": "conv_9f2c41d08ab37e51", "summary": "User asks how to request a refund for an annual plan; agent explains the policy and opens a ticket.", "timestamp": "2026-08-14T09:42:11" }
  ]
}

The full /overview reference is on the Analytics page.

Common query parameters

Most endpoints accept a subset of these parameters:

Parameter	Type	Values	Notes
`days_back`	integer	1–90	How far back to aggregate. Values above 90 are clamped to 90.
`time_range`	string	`all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`	Used by search and list endpoints instead of `days_back`.
`environment`	string	`all`, `development`, `staging`, `production`	`/conversations` only.
`limit`	integer	1 up to a per-endpoint cap	See the limits table below.
`offset`	integer	0–10,000	Values above 10,000 are clamped.

Two validation rules apply everywhere:

Numeric parameters must be non-negative integers (window must be positive); anything else (limit=abc, offset=-1, window=0) returns 400. Values outside the allowed range are clamped to the nearest bound, not rejected.
Enum parameters (mode, time_range, environment, outcome, kind, family, …) return 400 for values outside the documented set:

{
  "message": ["mode must be one of the following values: keyword, semantic, hybrid"],
  "error": "Bad Request",
  "statusCode": 400
}

Limits

Limit	Value
`days_back` maximum	90
`limit` maximum (default)	100
`limit` maximum on `/frustrations`, `/emotions`, `/hallucinations`, `/tool-failures/:toolName`	20
`limit` maximum on `/problems`	25
`limit` maximum on `/problems/:id/reports`, `/problems/:id/conversations`, `/problems/:id/evidence`	50
`offset` maximum	10,000
Context `window` maximum	5 messages each side

Pagination

Three patterns are in use:

limit + offset — most list endpoints. Responses carry a pagination object; keep incrementing offset by limit while has_more is true:
{ "pagination": { "limit": 20, "offset": 0, "total": 57, "has_more": true } }
limit only — /search has no offset. Its pagination object reports limit, returned, and has_more; narrow the query or time range instead of paging deeper.
Keyset cursors — the problem sub-resources (/reports, /conversations, /evidence) return pagination.next_cursor; pass it back as cursor to fetch the next page.

Endpoints

Endpoint	Description	Reference
`GET /overview`	Headline KPIs, top clusters, recent activity	Analytics
`GET /clusters`	Use-case cluster hierarchy from the latest clustering run	Analytics
`GET /clusters/:nodeId/conversations`	Traces in one cluster	Analytics
`GET /task-clusters/search`	Search cluster nodes by name or meaning	Analytics
`GET /search`	Message-grain keyword / semantic / hybrid search	Search
`GET /conversations`	List and filter traces	Traces
`GET /conversations/:id/context`	Windowed message context around one message	Traces
`GET /conversations/:id/step-scores`	Per-segment step scores and blended rollup	Traces
`GET /conversations/:id/world-state` (+ `/replay`, `/snapshot`)	World state: slots, threads, state events	Traces
`GET /frustrations`	Frustration detections with evidence	Signals
`GET /emotions`	Multi-family emotion detections	Signals
`GET /tool-failures` (+ `/:toolName`)	Tool failure KPIs and per-tool examples	Signals
`GET /hallucinations`	Grounding results: contradictions and verified claims	Signals
`GET /problems` (+ `/:id`, `/:id/reports`, `/:id/conversations`, `/:id/evidence`)	Ranked root-cause problems and their evidence	Problems
`GET`/`POST /problems/:id/feedback`	Problem feedback (mark fixed, dismiss, flag, rename)	Problems
`POST /feedback`	General data-quality feedback	Problems

Errors

Status	Meaning
`400`	Validation failure: malformed numeric parameter, unknown enum value, missing required parameter or body field.
`401`	Missing, invalid, or revoked API key.
`404`	Referenced sub-resource does not exist (for example, an `attribution_id` that does not belong to the problem).
`500`	Internal error. The body never contains internal details.

Error bodies follow one shape; message is a string or an array of validation messages:

{
  "statusCode": 500,
  "message": "An internal error occurred while processing your request.",
  "error": "Internal Server Error"
}

Lookups of unknown IDs generally do not return 404. GET /clusters/:nodeId/conversations returns 200 with cluster: null, and GET /problems/:id returns 200 with found: false. Check those fields instead of relying on the status code.

Next steps

Search — find the exact message where something happened, then jump to its context.
Signals — read frustration, emotion, tool-failure, and hallucination detections.
Problems — read the ranked problem list and send feedback.
CLI overview — the same data from the terminal, with agent-friendly JSON output.
Connect the MCP server — the same data as MCP tools for Claude Code, Cursor, and other MCP clients.

​Base URL

​Authentication

​Make your first request

​Common query parameters

​Limits

​Pagination

​Endpoints

​Errors

​Next steps

Base URL

Authentication

Make your first request

Common query parameters

Limits

Pagination

Endpoints

Errors

Next steps