> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Data API overview

> Read traces, signals, clusters, and problems over HTTP with an API key — the same data the dashboard shows.

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](https://docs.moda.dev/cli/overview.md) 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](https://docs.moda.dev/administration/authentication.md) for key management.

> [!WARNING]
>
> The Data API and the [Ingestion API](https://docs.moda.dev/ingestion/http-api.md) 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:

```json theme={"dark"}
{
  "message": "Invalid or revoked API key",
  "error": "Unauthorized",
  "statusCode": 401
}
```

To check a key without reading any analytics, call `GET /whoami`. It returns the tenant the key acts on and the key's kind and scope:

```json theme={"dark"}
{
  "tenant_id": "6f1c2d9e-...",
  "tenant_name": "Acme",
  "tenant_slug": "acme",
  "api_key_id": "2b7e...",
  "key_kind": "tenant",
  "scope": "full",
  "read_only": false
}
```

## Make your first request

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/overview?days_back=7" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "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](https://docs.moda.dev/data-api/analytics.md) 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; anything else (`limit=abc`, `offset=-1`) 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:

```json theme={"dark"}
{
  "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 `/tools` | 200 |
| `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:

1. **`limit` + `offset`** — most list endpoints. Responses carry a `pagination` object; keep incrementing `offset` by `limit` while `has_more` is `true`:

   ```json theme={"dark"}
   { "pagination": { "limit": 20, "offset": 0, "total": 57, "has_more": true } }
   ```

2. **`limit` only** — [`/search`](https://docs.moda.dev/data-api/search) has no `offset`. Its `pagination` object reports `limit`, `returned`, and `has_more`; narrow the query or time range instead of paging deeper.

3. **Keyset cursors** — the [problem sub-resources](https://docs.moda.dev/data-api/problems.md) (`/reports`, `/conversations`, `/evidence`) return `pagination.next_cursor`; pass it back as `cursor` to fetch the next page.

## Endpoints

| Endpoint | Description | Reference |
| - | - | - |
| `GET /whoami` | The tenant, kind and scope of the calling key | [Authentication](#authentication) |
| `GET /overview` | Headline KPIs, top clusters, recent activity | [Analytics](https://docs.moda.dev/data-api/analytics.md) |
| `GET /trends` | Dashboard KPIs for a window against the previous window of equal length, with optional series | [Analytics](https://docs.moda.dev/data-api/analytics.md) |
| `GET /clusters` | Use-case cluster hierarchy from the latest clustering run | [Analytics](https://docs.moda.dev/data-api/analytics.md) |
| `GET /clusters/:nodeId/conversations` | Traces in one cluster | [Analytics](https://docs.moda.dev/data-api/analytics.md) |
| `GET /task-clusters/search` | Search cluster nodes by name or meaning | [Analytics](https://docs.moda.dev/data-api/analytics.md) |
| `GET /search` | Message-grain keyword / semantic / hybrid search | [Search](https://docs.moda.dev/data-api/search.md) |
| `GET /conversations` | List and filter traces | [Traces](https://docs.moda.dev/data-api/traces.md) |
| `GET /conversations/:id/context` | Windowed message context around one message | [Traces](https://docs.moda.dev/data-api/traces.md) |
| `GET /conversations/:id/world-state` (`/replay` and `/snapshot` are retired: `410`) | World state: a trace's tasks and facts | [Traces](https://docs.moda.dev/data-api/traces.md) |
| `GET /frustrations` | Frustration detections with evidence | [Signals](https://docs.moda.dev/data-api/signals.md) |
| `GET /emotions` | Multi-family emotion detections | [Signals](https://docs.moda.dev/data-api/signals.md) |
| `GET /tool-failures` (+ `/:toolName`) | Tool failure KPIs and per-tool examples | [Signals](https://docs.moda.dev/data-api/signals.md) |
| `GET /tools` (+ `/:name`) | Tool catalog: every tool's calls and success rate; one tool's schema, usage, and failure categories | [Signals](https://docs.moda.dev/data-api/signals.md) |
| `GET /hallucinations` | Grounding results: contradictions and verified claims | [Signals](https://docs.moda.dev/data-api/signals.md) |
| `GET /problems` (+ `/:id`, `/:id/reports`, `/:id/conversations`, `/:id/evidence`) | Ranked root-cause problems and their evidence | [Problems](https://docs.moda.dev/data-api/problems.md) |
| `GET`/`POST /problems/:id/feedback` | Problem feedback (mark fixed, dismiss, flag, rename) | [Problems](https://docs.moda.dev/data-api/problems.md) |
| `GET /problems/:id/history` | One problem's incidents and users per day, with a comparison | [Problems](https://docs.moda.dev/data-api/problems.md) |
| `POST /feedback` | General data-quality feedback | [Problems](https://docs.moda.dev/data-api/problems.md) |

## 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:

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

> [!NOTE]
>
> 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](https://docs.moda.dev/data-api/search.md) — find the exact message where something happened, then jump to its context.
* [Signals](https://docs.moda.dev/data-api/signals.md) — read frustration, emotion, tool-failure, and hallucination detections.
* [Problems](https://docs.moda.dev/data-api/problems.md) — read the ranked problem list and send feedback.
* [CLI overview](https://docs.moda.dev/cli/overview.md) — the same data from the terminal, with agent-friendly JSON output.
* [Connect the MCP server](https://docs.moda.dev/mcp/overview.md) — the same data as MCP tools for Claude Code, Cursor, and other MCP clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.