Query

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

Request

The request body is strict JSON:

{
  "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 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

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"}}'

{
  "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

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"}}'

{
  "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": [
    ["[email protected]", "Ana", 8],
    ["[email protected]", "Ben", 6],
    ["[email protected]", "Chris", 4],
    ["cron:daily-digest", "Daily Scheduler", 3],
    ["[email protected]", "Dana", 3],
    [null, null, 1]
  ],
  "cursor": null,
  "warnings": []
}

Attribution totals

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"}}'

{
  "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

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"}}'

{
  "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": [
    ["[email protected]", "Ana", 8, 8, 0],
    ["[email protected]", "Ben", 7, 6, 1],
    ["[email protected]", "Dana", 3, 3, 0],
    ["[email protected]", "Erin", 1, 0, 1],
    ["[email protected]", "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

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"}}'

{
  "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

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"}}'

{
  "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

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"}}'

{
  "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": [
    ["[email protected]", "Ana", 8],
    ["[email protected]", "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.

Getting Started

API Guides

Analytics

Request

Examples

Totals

Per-user

Attribution totals

Attribution records by person

Per-agent grouped

Filtered

Paginated

​Request

​Examples

​Totals

​Per-user

​Attribution totals

​Attribution records by person

​Per-agent grouped

​Filtered

​Paginated

Request

Examples

Totals

Per-user

Attribution totals

Attribution records by person

Per-agent grouped

Filtered

Paginated