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

# Query

> Run organization-scoped analytics queries

`POST /api/v1/analytics/query` runs a query against a versioned analytics
catalog model.

## Request

The request body is strict JSON:

```json theme={null}
{
  "model": "agent_runs",
  "metrics": ["run_count"],
  "dimensions": [],
  "filters": [],
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC"
  },
  "order": [],
  "limit": 100
}
```

| Field        | Type      | Rules                                                                                                                                                    |
| ------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`      | string    | Catalog model name. Version 1 supports `agent_runs` and `agent_user_activity`.                                                                           |
| `metrics`    | string\[] | One to 16 unique catalog metric names.                                                                                                                   |
| `dimensions` | string\[] | Optional; up to eight unique catalog dimensions. Defaults to `[]`.                                                                                       |
| `filters`    | object\[] | Optional; up to eight dimension filters. Each is `eq` with one `value`, or `in` with 1 to 50 `values`. Values are 1 to 200 characters. Defaults to `[]`. |
| `range`      | object    | Required `{ start, end, timezone }`; valid inclusive local dates covering at most 366 days. `start` must not follow `end`.                               |
| `order`      | object\[] | Optional; up to eight unique `{ member, direction }` terms. Valid only when at least one dimension is selected. Defaults to `[]`.                        |
| `limit`      | integer   | Optional 1–500; defaults to 100.                                                                                                                         |
| `cursor`     | string    | Optional opaque continuation cursor, at most 2048 characters. It cannot be sent on totals or metric-ordered queries.                                     |

Member names are 1 to 64 characters. A member may appear once per list: a
repeat inside `metrics`, `dimensions`, or `order` returns `invalid_query`.

`start` and `end` are inclusive local calendar dates in the requested IANA
timezone. Filters apply to dimensions only. Order terms must reference
selected metrics or dimensions. A totals query with no dimensions returns a
single row and rejects `order` with `invalid_query`.

For both analytics models, the `agent_id` filter accepts either the agent's UUID
or its optional slug.

Slug resolution is point-in-time: a slug filter matches whichever agent currently
holds that slug, not the agent it identified when the filter was written. Because
`agent_id` always returns the agent UUID, pin the UUID instead of the slug for
filters that must stay stable across renames.

The response is a columnar table. `columns` describes each position in every
row. A selected dimension is followed by its companion fields, then selected
metrics. The catalog lists all valid members and companion behavior.

| Response field   | Meaning                                                                           |
| ---------------- | --------------------------------------------------------------------------------- |
| `queryId`        | Unique identifier for this execution.                                             |
| `catalogVersion` | Catalog version used by the engine; response metadata only.                       |
| `asOf`           | Inclusion boundary used for this response and any cursor continuation.            |
| `range`          | The requested range plus its compiled `startUtc` and `endUtc`.                    |
| `columns`        | Ordered column descriptors with `name`, `type`, and catalog `member`.             |
| `rows`           | Values in the same order as `columns`; values may be strings, numbers, or `null`. |
| `cursor`         | Signed continuation cursor or `null` when there is no next page.                  |
| `warnings`       | Non-fatal semantic notices, including `non_additive_metric`.                      |

The `agent_runs` grain is one agent run. Excluded sub-agents are not counted
separately. Its event clock is `createdAt`. This is a run view, not an
interaction view. It does not count individual messages, tool calls, or other
activity inside a run.

The `agent_user_activity` grain is one attribution record for an identified
person and an agent run. Its event clock is `occurredAt`, so the range
describes when a person started, was associated with, or interacted with a run.
Run-count metrics count unique person-and-run combinations. `interaction_count`
counts every recorded interaction. The [catalog](/api/catalog) defines these
terms.

Totals queries with no dimensions always return one row and never paginate. A
grouped query ordered by dimensions may return an opaque `cursor`. A grouped
query ordered by a metric is a single-page top-N result and returns
`cursor: null`.

Non-additive metrics such as `run_success_rate` and `unique_initiator_count` add a
warning when selected. `run_success_rate` is completed divided by completed plus
failed, and is `null` when that denominator is zero. `unique_initiator_count`
ignores null identifiers. An automated starter counts when it has an identifier.

## Examples

The examples below use the deterministic development dataset. `queryId`,
`asOf`, and opaque cursor values vary on each request.

### Totals

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_runs","metrics":["run_count","completed_run_count","failed_run_count","cancelled_run_count","active_run_count","run_success_rate","unique_initiator_count"],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440000",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    { "name": "run_count", "type": "number", "member": "run_count" },
    {
      "name": "completed_run_count",
      "type": "number",
      "member": "completed_run_count"
    },
    {
      "name": "failed_run_count",
      "type": "number",
      "member": "failed_run_count"
    },
    {
      "name": "cancelled_run_count",
      "type": "number",
      "member": "cancelled_run_count"
    },
    {
      "name": "active_run_count",
      "type": "number",
      "member": "active_run_count"
    },
    {
      "name": "run_success_rate",
      "type": "number",
      "member": "run_success_rate"
    },
    {
      "name": "unique_initiator_count",
      "type": "number",
      "member": "unique_initiator_count"
    }
  ],
  "rows": [[25, 17, 4, 1, 3, 0.8095238095238095, 5]],
  "cursor": null,
  "warnings": [
    {
      "code": "non_additive_metric",
      "member": "run_success_rate",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "unique_initiator_count",
      "message": "This metric is non-additive across groups."
    }
  ]
}
```

### Per-user

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_runs","metrics":["run_count"],"dimensions":["user_identifier"],"order":[{"member":"user_identifier","direction":"asc"}],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440001",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    {
      "name": "user_identifier",
      "type": "string",
      "member": "user_identifier"
    },
    {
      "name": "user_name",
      "type": "string",
      "member": "user_identifier"
    },
    { "name": "run_count", "type": "number", "member": "run_count" }
  ],
  "rows": [
    ["ana@example.com", "Ana", 8],
    ["ben@example.com", "Ben", 6],
    ["chris@example.com", "Chris", 4],
    ["cron:daily-digest", "Daily Scheduler", 3],
    ["dana@example.com", "Dana", 3],
    [null, null, 1]
  ],
  "cursor": null,
  "warnings": []
}
```

### Attribution totals

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_user_activity","metrics":["attributed_run_count","initiated_run_count","associated_run_count","interacted_run_count","interaction_count"],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440005",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    {
      "name": "attributed_run_count",
      "type": "number",
      "member": "attributed_run_count"
    },
    {
      "name": "initiated_run_count",
      "type": "number",
      "member": "initiated_run_count"
    },
    {
      "name": "associated_run_count",
      "type": "number",
      "member": "associated_run_count"
    },
    {
      "name": "interacted_run_count",
      "type": "number",
      "member": "interacted_run_count"
    },
    {
      "name": "interaction_count",
      "type": "number",
      "member": "interaction_count"
    }
  ],
  "rows": [[20, 17, 3, 2, 2]],
  "cursor": null,
  "warnings": [
    {
      "code": "non_additive_metric",
      "member": "attributed_run_count",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "initiated_run_count",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "associated_run_count",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "interacted_run_count",
      "message": "This metric is non-additive across groups."
    }
  ]
}
```

### Attribution records by person

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_user_activity","metrics":["attributed_run_count","initiated_run_count","associated_run_count"],"dimensions":["user_identifier"],"order":[{"member":"user_identifier","direction":"asc"}],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440006",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    {
      "name": "user_identifier",
      "type": "string",
      "member": "user_identifier"
    },
    {
      "name": "user_name",
      "type": "string",
      "member": "user_identifier"
    },
    {
      "name": "attributed_run_count",
      "type": "number",
      "member": "attributed_run_count"
    },
    {
      "name": "initiated_run_count",
      "type": "number",
      "member": "initiated_run_count"
    },
    {
      "name": "associated_run_count",
      "type": "number",
      "member": "associated_run_count"
    }
  ],
  "rows": [
    ["ana@example.com", "Ana", 8, 8, 0],
    ["ben@example.com", "Ben", 7, 6, 1],
    ["dana@example.com", "Dana", 3, 3, 0],
    ["erin@example.com", "Erin", 1, 0, 1],
    ["faye@example.com", "Faye", 1, 0, 1]
  ],
  "cursor": null,
  "warnings": [
    {
      "code": "non_additive_metric",
      "member": "attributed_run_count",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "initiated_run_count",
      "message": "This metric is non-additive across groups."
    },
    {
      "code": "non_additive_metric",
      "member": "associated_run_count",
      "message": "This metric is non-additive across groups."
    }
  ]
}
```

### Per-agent grouped

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_runs","metrics":["run_count","completed_run_count"],"dimensions":["agent_id"],"order":[{"member":"agent_id","direction":"asc"}],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440002",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    { "name": "agent_id", "type": "string", "member": "agent_id" },
    { "name": "agent_name", "type": "string", "member": "agent_id" },
    { "name": "run_count", "type": "number", "member": "run_count" },
    {
      "name": "completed_run_count",
      "type": "number",
      "member": "completed_run_count"
    }
  ],
  "rows": [
    ["8d4d7f1b-7a6c-4d1e-9f2b-0c6a4b8e1d30", "Inbox Triage", 8, 5],
    ["9e5e8f2c-8b7d-4e2f-a03c-1d7b5c9f2e41", "Invoice Follow-Up", 8, 6],
    ["af6f9a3d-9c8e-4f30-b14d-2e8c6da03f52", "Meeting Scheduler", 9, 6]
  ],
  "cursor": null,
  "warnings": []
}
```

### Filtered

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_runs","metrics":["run_count","run_success_rate"],"dimensions":["day"],"filters":[{"member":"user_type","op":"eq","value":"internal"}],"order":[{"member":"day","direction":"asc"}],"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440003",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    { "name": "day", "type": "date", "member": "day" },
    { "name": "run_count", "type": "number", "member": "run_count" },
    {
      "name": "run_success_rate",
      "type": "number",
      "member": "run_success_rate"
    }
  ],
  "rows": [
    ["2026-08-01", 1, 1],
    ["2026-08-02", 1, 1],
    ["2026-08-03", 2, 1],
    ["2026-08-04", 2, 0.5],
    ["2026-08-05", 1, 1],
    ["2026-08-08", 1, 1],
    ["2026-08-11", 1, null],
    ["2026-08-13", 1, null],
    ["2026-08-14", 1, null]
  ],
  "cursor": null,
  "warnings": [
    {
      "code": "non_additive_metric",
      "member": "run_success_rate",
      "message": "This metric is non-additive across groups."
    }
  ]
}
```

### Paginated

```bash theme={null}
curl -sS -X POST https://api.burthq.com/api/v1/analytics/query \
  -H "Authorization: Bearer $BURT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_runs","metrics":["run_count"],"dimensions":["user_identifier"],"order":[{"member":"user_identifier","direction":"asc"}],"limit":2,"range":{"start":"2026-08-01","end":"2026-08-14","timezone":"UTC"}}'
```

```json theme={null}
{
  "queryId": "550e8400-e29b-41d4-a716-446655440004",
  "catalogVersion": "2026-08-24.2",
  "asOf": "2026-08-21T00:00:00.000Z",
  "range": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timezone": "UTC",
    "startUtc": "2026-08-01T00:00:00.000Z",
    "endUtc": "2026-08-15T00:00:00.000Z"
  },
  "columns": [
    {
      "name": "user_identifier",
      "type": "string",
      "member": "user_identifier"
    },
    {
      "name": "user_name",
      "type": "string",
      "member": "user_identifier"
    },
    { "name": "run_count", "type": "number", "member": "run_count" }
  ],
  "rows": [
    ["ana@example.com", "Ana", 8],
    ["ben@example.com", "Ben", 6]
  ],
  "cursor": "opaque-cursor-from-this-response",
  "warnings": []
}
```

For the next page, send the same request body with the returned `cursor`.
Keep the other fields unchanged; cursors are signed to the organization and
the canonical query.