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

# Traces

> GET /conversations for filtered lists of traces, /context for windowed messages, and /world-state for a trace's tasks and facts.

These are the Traces endpoints. They read individual [traces](https://docs.moda.dev/concepts/data-model.md#trace): list and filter them, pull a window of messages around a specific turn, and inspect a trace's [world state](https://docs.moda.dev/concepts/analysis.md#world-state). Endpoint paths and field names keep `conversation` / `conversation_id` for backwards compatibility; a `conversation_id` value is the trace ID.

## GET /conversations

Lists traces, newest first, with optional text search and structured filters.

### Query parameters

**search** `string`

Free-text search over trace summaries and message bodies. When `search` is the only filter, results may be relevance-ranked (see `search_mode` below).

**cluster\_id** `string`

Restrict to traces assigned to one use-case cluster node (see [Analytics](https://docs.moda.dev/data-api/analytics.md)).

**user\_id** `string`

Restrict to traces from one end user.

**time\_range** `string` (default: all)

One of `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. Filters on the trace's last activity.

**since** `string`

Absolute start, inclusive: an ISO 8601 date or datetime, UTC unless an offset is given. With `since` or `until` set, a trace is listed when it was active during the range: its first message is before the end and its last activity is at or after the start (intersected with `time_range`). With `search`, a trace is listed when a matching message falls inside the range.

**until** `string`

Absolute end, inclusive; a date-only value covers that whole UTC day. Must not precede `since`; at most 366 days apart.

**environment** `string` (default: all)

One of `all`, `development`, `staging`, `production`.

**world\_state** `string`

Keyword(s) matched case-insensitively against the trace's world state: the goals and summaries of its tasks and, for a trace the task engine owns, its facts and the user's profile. Comma-separated terms are ANDed. Free text, not `key=value`. Maximum 200 characters.

**outcome** `string` (default: any)

`any`, `positive`, or `negative`, based on frustration detection. `negative` returns traces with a detected user frustration (detections whose every quote is marked a false positive are excluded); `positive` returns traces with none, including traces the frustration detector has not analyzed yet.

**cohort** `string`

`builtin:<key>` or a saved cohort id: only traces of the cohort's current members, with the dashboard trace list's own cohort scope. With `search`, the keyword path runs (no hybrid ranking). The cohort's membership snapshot is refreshed first when it is missing or stale, as the dashboard does; an unknown saved cohort id returns `404`, and the response echoes `cohort`.

**limit** `integer` (default: 20)

1–100.

**offset** `integer` (default: 0)

0–10,000.

### Response fields

**conversations** `array`

One row per trace. Each row has `conversation_id` (the trace ID), `summary` (its latest task's goal, else its stored summary from before summaries were retired), `message_count`, `first_timestamp`, `last_timestamp`, `duration_ms`, `cluster_id` and `cluster_name` (or `null`), `environment`, `latest_task`, and `task_count`. `latest_task` is the trace's most recent open task, else its most recently updated task (or `null`): `thread_id`, `goal`, `status` (`active`, `resolved`, `cancelled`, or `stale` for idle), `latest_step`, `last_evidence_at`, `first_message_index`, and `last_message_index`. With `search_mode: hybrid`, rows the semantic leg ranked by a task also carry `matched_task` (`segment_id`, `thread_id`, `goal`, `status`, `similarity`). `duration_ms` is the time from the first to the last message. It is `null` when the first or last timestamp is unknown: some imported traces store `1970-01-01T00:00:00`, and replayed history stores placeholder timestamps before 2022 (such as `2020-01-01T00:00:00`). `sort_by=slowest` orders by `duration_ms` and puts rows with unknown durations last.

**search\_mode** `string`

`keyword` or `hybrid`. `hybrid` runs only when `search` is set with no structured filters and semantic search is available; otherwise the deterministic keyword path serves the request.

**pagination** `object`

`limit`, `offset`, `total`, `has_more`.

> [!NOTE]
>
> When `search_mode` is `hybrid`, `pagination.total` is the size of the relevance-ranked candidate pool, not an exact corpus count. Branch on `search_mode` before treating `total` as an exact figure — in `keyword` mode it is exact.

### Example

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/conversations?time_range=7d&environment=production&outcome=negative&limit=2" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "conversations": [
    {
      "conversation_id": "conv_9f2c41d08ab37e51",
      "summary": "User asks how to request a refund for an annual plan; agent explains the policy and opens a ticket.",
      "message_count": 18,
      "first_timestamp": "2026-08-14T09:12:03",
      "last_timestamp": "2026-08-14T09:41:47",
      "duration_ms": 1784000,
      "cluster_id": "node_3",
      "cluster_name": "Billing and refunds",
      "environment": "production"
    },
    {
      "conversation_id": "conv_5d1a7be2c90f4438",
      "summary": "User cannot connect a calendar integration; agent retries the OAuth flow twice without success.",
      "message_count": 31,
      "first_timestamp": "2026-08-13T17:55:20",
      "last_timestamp": "2026-08-13T18:20:44",
      "duration_ms": 1524000,
      "cluster_id": "node_17",
      "cluster_name": "Integrations setup",
      "environment": "production"
    }
  ],
  "search_mode": "keyword",
  "pagination": { "limit": 2, "offset": 0, "total": 57, "has_more": true }
}
```

## GET /conversations/:id/context

Returns a window of parsed messages centered on one message index. Use it to read the turns around a [search](https://docs.moda.dev/data-api/search.md) hit or a signal's key turn.

### Query parameters

**msg\_index** `integer`

Zero-based index of the center message. Defaults to the middle of the trace. Out-of-range values are clamped to the last message.

**window** `integer` (default: 2)

Messages to include on each side of the center, 0–5 (larger values are clamped to 5). `0` returns only the center message, plus `summary` and `total_messages`.

**metadata\_only** `string`

`1` (or `true`) returns only `summary` and `total_messages`, with an empty `context.messages` and `metadata_only: true`, without reading any message.

### Response fields

**conversation\_id** `string`

**total\_messages** `integer`

Total messages stored for the trace.

**summary** `string`

One-line description of the trace: the goal of its latest task, else its stored summary from before conversation summaries were retired (they are no longer generated). Empty string when the trace has neither yet.

**latest\_task** `object | null`

The trace's most recent open task, else its most recently updated task. Same shape as one entry of `tasks`.

**task\_count** `integer`

How many tasks the trace has.

**tasks** `array`

The trace's tasks (world-state threads: one per thing the user asked for), open first, then most recently updated, up to 50. Each has `thread_id`, `goal`, `status` (`active`, `resolved`, `cancelled`, or `stale` for idle), `latest_step` (the newest timeline entry), `last_evidence_at`, `first_message_index`, and `last_message_index`.

**context** `object`

`center_index`, `from_index`, `to_index`, and `messages[]`. Each message has `index`, `role`, `content`, `tool_calls[]` (`id`, `name`, `input` — input is a truncated string), `tool_results[]` (`tool_use_id`, `content` — truncated, `is_error`), and `timestamp`.

### Example

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/conversations/conv_9f2c41d08ab37e51/context?msg_index=6&window=1" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "conversation_id": "conv_9f2c41d08ab37e51",
  "total_messages": 18,
  "summary": "User asks how to request a refund for an annual plan; agent explains the policy and opens a ticket.",
  "context": {
    "center_index": 6,
    "from_index": 5,
    "to_index": 7,
    "messages": [
      {
        "index": 5,
        "role": "assistant",
        "content": "You can request a refund from the billing page. Would you like me to open a ticket?",
        "tool_calls": [],
        "tool_results": [],
        "timestamp": "2026-08-14T09:28:10"
      },
      {
        "index": 6,
        "role": "user",
        "content": "I already asked about the refund policy twice and the bot keeps linking the same page.",
        "tool_calls": [],
        "tool_results": [],
        "timestamp": "2026-08-14T09:31:22"
      },
      {
        "index": 7,
        "role": "assistant",
        "content": "",
        "tool_calls": [
          { "id": "toolu_01Xk2m", "name": "create_ticket", "input": "{\"topic\":\"refund\",\"plan\":\"annual\"}" }
        ],
        "tool_results": [],
        "timestamp": "2026-08-14T09:31:40"
      }
    ]
  }
}
```

## GET /conversations/:id/world-state

Returns the trace's world state as it is now: its tasks (open and finished, each with a timeline; a subtask names its parent task), the facts recorded for it, and the end user's durable cross-trace profile. This is the same data as the World State view on the trace detail page. There is no history of state changes.

Tasks and facts come from the task engine for a trace it owns (the response then carries `source: "task_engine"`), and from the task tracker otherwise. Task-tracker traces carry facts only where your workspace's task records state them.

> [!NOTE]
>
> The world-state endpoints return camelCase field names (`hasData`, `segmentIndex`, ...), unlike the snake\_case used by the rest of the Data API.

### Query parameters

**summary\_only** `string`

Set to `1` to return `segments` as an empty array and add `segmentSummaries` — per-segment fact summaries (`segmentIndex`, `durableCount`, `topSlots`). Cheaper for a quick existence check.

**event\_limit** `integer`

Retired with the world-state event log: still accepted, and ignored.

### Response fields

**hasData** `boolean`

`false` when no tasks or facts have been tracked for the trace yet. The response keeps its full shape (empty `segments`); an unknown trace ID answers the same way.

**userId** `string | null`

The end user the trace belongs to, when known.

**userDurableProfile** `object | null`

The user's current cross-trace profile: `slots` (map of slot key to `{value, source, ...}`), `updatedAt`, `slotCount`.

**conversationWarmstart** `object | null`

The durable facts the trace started with, for a trace the task engine owns; `null` otherwise.

**source** `string`

`task_engine` when the task engine owns the trace; absent otherwise.

**segments** `array`

The trace's tasks and facts: `segmentIndex`, `segmentId`, `startMsgIdx`, `endMsgIdx`, `slots` (facts), `carryIn`, `openThreads[]` (one per task, every status: `id`, `status` — `open` / `resolved` / `cancelled` / `stale` for idle, `summary`, `goal`, `timeline[]`, `subgoals[]`, and `parent_id` on a subtask), and `slotCounts` (`durable`, `segmentLocal`, `total`).

**summary** `object`

`segmentCount`, and `lastUpdatedAt`: the latest task-engine pass, or the latest task update.

### Example

```bash theme={"dark"}
curl "https://moda.dev/api/v1/data/conversations/conv_9f2c41d08ab37e51/world-state" \
  -H "x-api-key: YOUR_MODA_API_KEY"
```

```json theme={"dark"}
{
  "hasData": true,
  "userId": "user_4821",
  "userDurableProfile": {
    "slots": {
      "user.plan": { "value": "annual", "source": "user", "msg_index": 2 }
    },
    "updatedAt": "2026-08-14T09:41:50",
    "slotCount": 1
  },
  "conversationWarmstart": null,
  "segments": [
    {
      "segmentIndex": 0,
      "segmentId": "",
      "startMsgIdx": 0,
      "endMsgIdx": 11,
      "slots": {},
      "carryIn": {},
      "openThreads": [
        {
          "id": "refund_ticket",
          "status": "resolved",
          "summary": "Open a refund ticket for the annual plan",
          "timeline": [
            { "text": "Ticket created", "msg_index": 7, "tool_name": "create_ticket" }
          ],
          "subgoals": []
        }
      ],
      "slotCounts": { "durable": 0, "segmentLocal": 0, "total": 0 }
    }
  ],
  "summary": { "segmentCount": 1, "lastUpdatedAt": "2026-08-14T09:41:50" }
}
```

### GET /conversations/:id/world-state/replay and /snapshot (retired)

Both are retired: they folded the world-state event log, which Moda no longer writes. Every request answers `410 Gone` with a JSON body naming what replaces them:

```json theme={"dark"}
{
  "statusCode": 410,
  "error": "Gone",
  "code": "world_state_snapshot_retired",
  "message": "World-state snapshots were retired with the world-state v1 event log they were folded from, which Moda no longer writes. Use GET /api/v1/data/conversations/:conversationId/world-state for the trace's current tasks and facts, and GET /api/v1/data/conversations/:conversationId/context?msg_index=N to read the messages at a turn."
}
```

Replay answers the same with `code: "world_state_replay_retired"`. Read the trace's current tasks and facts with `GET /conversations/:id/world-state`, and what happened at a turn with [`GET /conversations/:id/context`](https://docs.moda.dev/data-api/traces#get-conversationsidcontext).

## Next steps

* [Search](https://docs.moda.dev/data-api/search.md) — find the message index to center a context window on.
* [Data model](https://docs.moda.dev/concepts/data-model.md) — what traces, segments, slots, and threads mean.
* [Dashboard: Traces](https://docs.moda.dev/dashboard/traces.md) — the same data in the Timeline and World State views.


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