Catalog

This page explains the analytics model and the members accepted by the query endpoint.

Terms

Term	Meaning
Agent run	The main execution of an agent for a task.
Excluded sub-agents	Sub-agent, browser, phone, and platform runs that belong to an agent run. They are not counted as extra agent runs.
Attribution record	A record that connects an identified person to an agent run because that person started it, was associated with it when it started, or interacted with it later.
Automated starter	A schedule or integration that starts an agent run without a person starting it. `unique_initiator_count` includes that starter only when it has an identifier.
Unique person-and-run combination	One identified person together with one agent run. Run-count metrics count that pair once even when several attribution records connect the same person to the same run.

Models

Model	Grain	Event clock	What it counts
`agent_runs`	`one agent run; sub-agent and supporting runs are not counted separately`	`createdAt`	One row for each agent run.
`agent_user_activity`	`one attribution record for an identified person and an agent run`	`occurredAt`	One row each time a person is recorded as starting, being associated with, or interacting with an agent run.

Grain says what one row represents. For agent_runs, each row is one agent run. Excluded sub-agents belong to that agent run and are not counted separately. Individual messages and tool calls inside a run are not rows either. Event clock is the timestamp that decides which range bucket a row falls into. agent_runs uses the moment the run was created, so date filters and the day dimension group runs by when they started. For agent_user_activity, each row is one attribution record. The person is named by a normalized email address or an E.164 phone number. Its occurredAt event clock uses the time of the attribution record. A person who joins an older run appears in the period when they joined, not when the run started.

Which channels produce attribution records

A channel produces an attribution record only when it supplies an address the API can group by. manual, outlook_email, front_email, front_mention, agent_email, phone_inbound, and text_message_inbound produce records. slack_mention produces an initiated record only, and only when the mention resolved to the author’s email address. Script-launched runs use the script trigger source and are automated, so they produce no person attribution records. Teams, Twilio, and self-serve webhook triggers likewise produce no attribution records at all, so runs from those channels are absent from agent_user_activity while still being counted in agent_runs.

Metrics

All metrics return numbers. Additive metrics can be summed across groups (for example, weekly totals from daily groups). Non-additive metrics cannot be summed; selecting one adds a non_additive_metric warning to the response. No metric or dimension is currently deprecated. See Versioning and deprecation.

`agent_runs` metrics

Metric	Type	Additive	Description
`run_count`	number	Yes	Agent runs in the selected range, whatever their status.
`completed_run_count`	number	Yes	Agent runs that completed successfully (`COMPLETED`).
`failed_run_count`	number	Yes	Agent runs that failed (`FAILED`).
`cancelled_run_count`	number	Yes	Agent runs that were cancelled (`CANCELLED`).
`active_run_count`	number	Yes	Agent runs still working or waiting at query time: queued, running, waiting for capacity, cancelling, awaiting a reply, sleeping, pausing, or paused.
`run_success_rate`	number	No	Share of finished runs that completed: completed divided by completed plus failed. Cancelled and active runs are excluded from both sides. Returns `null` when no run has finished.
`unique_initiator_count`	number	No	Distinct identified starters. A starter may be a person or an automated starter. Starters without identifiers are excluded.

Notes:

The four status count metrics partition the same rows by outcome, so within one result completed_run_count + failed_run_count + cancelled_run_count + active_run_count equals run_count.
run_success_rate is computed per group after grouping. Do not average or sum it across groups; re-query the groups you need instead.

`agent_user_activity` metrics

Every count below is over the attribution records that the query’s range and filters selected.

Metric	Type	Additive	Description
`attributed_run_count`	number	No	Unique person-and-run combinations with at least one attribution record.
`initiated_run_count`	number	No	Unique person-and-run combinations in which the person started the run.
`associated_run_count`	number	No	`associated_run_count = attributed_run_count - initiated_run_count`. See the calculation below before reading it as “runs this person did not start”.
`interacted_run_count`	number	No	Unique person-and-run combinations with at least one recorded interaction.
`interaction_count`	number	Yes	Recorded interactions. Unlike the run metrics above, every interaction counts.
`completed_attributed_run_count`	number	No	Person-and-run combinations whose run is currently `COMPLETED`.
`failed_attributed_run_count`	number	No	Person-and-run combinations whose run is currently `FAILED`.
`cancelled_attributed_run_count`	number	No	Person-and-run combinations whose run is currently `CANCELLED`.
`active_attributed_run_count`	number	No	Person-and-run combinations whose run currently has a non-terminal status.

[email protected] starts one run and later sends three messages. attributed_run_count, initiated_run_count, and interacted_run_count are each 1. interaction_count is 3.

How `associated_run_count` is calculated

associated_run_count is arithmetic, not a stored category:

associated_run_count = attributed_run_count - initiated_run_count

Both values come from the records selected by the query’s date range and filters. [email protected] starts a run on Monday and sends a message on Tuesday. A Tuesday-only query sees one attributed run and no initiated run, so associated_run_count is 1. A query covering both days returns 1 - 1 = 0. This metric is calculated from the selected records. It is not a count of rows whose activity_type is associated.

Dimensions

Dimensions group results. Selecting a dimension produces one row per distinct value inside the range. Filters accept these names too (see Filtering and ordering).

`agent_runs` dimensions

Dimension	Type	Description	Companion fields
`agent_id`	string	Identifier of the agent for the agent run. Filters accept either the agent UUID or its optional slug. Runs of deleted agents still appear, grouped under the id they had.	`agent_name`
`user_identifier`	string	Identifier for the person or automated starter that started the run, such as a normalized email address or phone number. Runs without an identifier form a `null` group.	`user_name`
`user_type`	string	Class of the starter: `internal`, `external`, `automated`, `unknown`, or `null` when absent. `automated` marks an automated starter, which is a schedule or integration rather than a person.	None
`day`	date	Day the run started, in the requested IANA timezone, formatted `YYYY-MM-DD`. Only days with data appear; empty days are not filled in.	None

`agent_user_activity` dimensions

agent_id, user_identifier, and day are named the same as on agent_runs and carry the same companion fields, but day groups by occurredAt rather than by when the run started. There is no user_type dimension on this model. run_initiation_type classifies the run, not the person.

Dimension	Type	Description	Companion fields
`agent_id`	string	Identifier of the agent for the attributed agent run. Filters accept either the agent UUID or its optional slug.	`agent_name`
`user_identifier`	string	Normalized email address or E.164 phone number of the attributed person. Never `null`. A sender the API cannot identify produces no row.	`user_name`
`user_domain`	string	Email domain of the person, lowercased. `null` when the person is identified by a phone number.	None
`activity_type`	string	`initiated`, `associated`, or `interacted`.	None
`run_initiation_type`	string	How the agent run itself started: `human`, `automated`, or `unknown`. `automated` means an automated starter began it. The value is frozen when the attribution record is written.	None
`source`	string	Channel that produced the attribution record, such as `outlook_email`. See which channels produce attribution records.	None
`day`	date	Day of the attribution record, in the requested IANA timezone, formatted `YYYY-MM-DD`. Only days with data appear.	None

Companion fields

Companion fields enrich a dimension and are returned automatically whenever their dimension is selected. You cannot request them on their own. Each one appears immediately after its dimension in columns:

agent_name: current display name from the joined task-agent record. Soft-deleted agents remain joinable, but renaming an agent changes the name shown for historical runs.
user_name: lexicographically greatest non-null display name in the user_identifier group.

Companions are plain output columns: they cannot be filtered or ordered by name, and they do not count toward the eight-dimension limit.

Filtering and ordering

Filters apply to dimensions only. A filter on a metric or companion name is rejected as unknown_member.
Each filter is either "eq" with one value, or "in" with a values array of 1–50 non-empty strings. At most eight filters apply per query.
Use YYYY-MM-DD local dates in the range timezone for day filters. Filter strings are not independently date-validated; an unmatched value returns no rows.
Filter values are strings; there is no equality test for null. To see the unattributed group, do not filter on that dimension. It appears as null rows.
Up to eight unique order terms ({ member, direction }) may reference selected metrics or dimensions. Totals queries cannot specify ordering. Ordering by anything else is rejected as invalid_query.
Without an explicit order, results sort ascending by every selected dimension. Explicit terms apply first, then remaining dimensions ascend. Ascending sorts place null values last; descending sorts place them first.
Ordering by a metric produces a single-page top-N result and never returns a cursor. Dimension-ordered grouped queries paginate. See Pagination.

Versioning and deprecation

catalogVersion identifies the published metric and dimension set and its semantics. It is response metadata only: requests cannot pin a version, and a request body containing catalogVersion is rejected. When the catalog changes, the version changes too, and any outstanding pagination cursor stops working with invalid_cursor; restart the walk from a fresh request. Every metric and dimension carries a deprecated field; models and companion fields do not. It is currently null for every metric and dimension. When set, the object contains since (the catalog version that introduced the deprecation) and note (migration guidance). Deprecated members remain queryable and do not automatically add a query warning, so clients should inspect this metadata.

Example

curl -sS https://api.burthq.com/api/v1/analytics/catalog \
  -H "Authorization: Bearer $BURT_API_KEY"

Example response

{
  "catalogVersion": "2026-08-24.2",
  "models": [
    {
      "name": "agent_runs",
      "description": "One row for each agent run. Sub-agent work and the supporting browser, phone, inbound-phone, and platform runs it starts are not counted separately. The date range filters on createdAt.",
      "grain": "one agent run; sub-agent and supporting runs are not counted separately",
      "eventClock": "createdAt",
      "metrics": [
        {
          "name": "run_count",
          "type": "number",
          "description": "Agent runs, whatever their status.",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "completed_run_count",
          "type": "number",
          "description": "Agent runs that completed successfully (COMPLETED).",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "failed_run_count",
          "type": "number",
          "description": "Agent runs that failed (FAILED).",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "cancelled_run_count",
          "type": "number",
          "description": "Agent runs that were cancelled (CANCELLED).",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "active_run_count",
          "type": "number",
          "description": "Agent runs still working or waiting: PENDING, RUNNING, WAITING_FOR_SLOT, CANCELLING, AWAITING_REPLY, SLEEPING, PAUSING, or PAUSED.",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "run_success_rate",
          "type": "number",
          "description": "Completed agent runs divided by the sum of completed and failed runs. Cancelled and active runs are excluded from both sides. The result is null when the denominator is zero.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "unique_initiator_count",
          "type": "number",
          "description": "Distinct identified starters. A starter may be a person or an automated starter. Starters without identifiers are excluded.",
          "additive": false,
          "deprecated": null
        }
      ],
      "dimensions": [
        {
          "name": "agent_id",
          "type": "string",
          "description": "Task-agent identifier for the agent run. Filters accept either the agent UUID or its optional slug. Rows for soft-deleted agents are still returned. The agent_name companion comes from the current joined task-agent record, so renames affect historical results. 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.",
          "companions": [
            {
              "name": "agent_name",
              "type": "string",
              "description": "Current display name from the joined task-agent record. Soft-deleted agents remain joinable, but renames affect historical results."
            }
          ],
          "deprecated": null
        },
        {
          "name": "user_identifier",
          "type": "string",
          "description": "Identifier for the person or automated starter that started the run, such as a normalized email address or phone number. Rows without an identifier group together and return null.",
          "companions": [
            {
              "name": "user_name",
              "type": "string",
              "description": "Lexicographically greatest non-null display name in the user-identifier group."
            }
          ],
          "deprecated": null
        },
        {
          "name": "user_type",
          "type": "string",
          "description": "Class of the starter: internal, external, automated, unknown, or null when absent. The automated value marks an automated starter, which is a schedule or integration rather than a person.",
          "companions": [],
          "deprecated": null
        },
        {
          "name": "day",
          "type": "date",
          "description": "Creation day in the requested IANA timezone, formatted YYYY-MM-DD. Filters take the same format. Only days with data are returned; the series is not gap-filled.",
          "companions": [],
          "deprecated": null
        }
      ]
    },
    {
      "name": "agent_user_activity",
      "description": "One row each time a person is recorded as starting, being associated with, or interacting with an agent run. The date range filters on occurredAt.",
      "grain": "one attribution record for an identified person and an agent run",
      "eventClock": "occurredAt",
      "metrics": [
        {
          "name": "attributed_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations with at least one attribution record.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "initiated_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations in which the person started the run.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "associated_run_count",
          "type": "number",
          "description": "associated_run_count = attributed_run_count - initiated_run_count. Both values come from the attribution records selected by the query's date range and filters.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "interacted_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations with at least one recorded interaction.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "interaction_count",
          "type": "number",
          "description": "Recorded interactions. Unlike the run metrics above, every interaction counts.",
          "additive": true,
          "deprecated": null
        },
        {
          "name": "completed_attributed_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations whose run is currently COMPLETED.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "failed_attributed_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations whose run is currently FAILED.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "cancelled_attributed_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations whose run is currently CANCELLED.",
          "additive": false,
          "deprecated": null
        },
        {
          "name": "active_attributed_run_count",
          "type": "number",
          "description": "Unique person-and-run combinations whose run currently has a non-terminal status.",
          "additive": false,
          "deprecated": null
        }
      ],
      "dimensions": [
        {
          "name": "agent_id",
          "type": "string",
          "description": "Task-agent identifier for the attributed agent run. Filters accept either the agent UUID or its optional slug. The agent_name companion comes from the current joined task-agent record. 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.",
          "companions": [
            {
              "name": "agent_name",
              "type": "string",
              "description": "Current display name from the joined task-agent record."
            }
          ],
          "deprecated": null
        },
        {
          "name": "user_identifier",
          "type": "string",
          "description": "Normalized email address or E.164 phone number for the attributed person.",
          "companions": [
            {
              "name": "user_name",
              "type": "string",
              "description": "Lexicographically greatest non-null captured display name in the user-identifier group."
            }
          ],
          "deprecated": null
        },
        {
          "name": "user_domain",
          "type": "string",
          "description": "Lowercased email domain when the person is identified by an email address. Null when the person is identified by a phone number.",
          "companions": [],
          "deprecated": null
        },
        {
          "name": "activity_type",
          "type": "string",
          "description": "Attribution activity: initiated, associated, or interacted.",
          "companions": [],
          "deprecated": null
        },
        {
          "name": "run_initiation_type",
          "type": "string",
          "description": "How the agent run started: human, automated when an automated starter began it, or unknown. The value is frozen when the attribution record is written.",
          "companions": [],
          "deprecated": null
        },
        {
          "name": "source",
          "type": "string",
          "description": "Channel that produced the attribution record.",
          "companions": [],
          "deprecated": null
        },
        {
          "name": "day",
          "type": "date",
          "description": "Day of the attribution record in the requested IANA timezone, formatted YYYY-MM-DD. Filters use the same format.",
          "companions": [],
          "deprecated": null
        }
      ]
    }
  ]
}

Getting Started

API Guides

Analytics

Terms

Models

Which channels produce attribution records

Metrics

`agent_runs` metrics

`agent_user_activity` metrics

How `associated_run_count` is calculated

Dimensions

`agent_runs` dimensions

`agent_user_activity` dimensions

Companion fields

Filtering and ordering

Versioning and deprecation

Example

​Terms

​Models

​Which channels produce attribution records

​Metrics

​agent_runs metrics

​agent_user_activity metrics

​How associated_run_count is calculated

​Dimensions

​agent_runs dimensions

​agent_user_activity dimensions

​Companion fields

​Filtering and ordering

​Versioning and deprecation

​Example

Terms

Models

Which channels produce attribution records

Metrics

`agent_runs` metrics

`agent_user_activity` metrics

How `associated_run_count` is calculated

Dimensions

`agent_runs` dimensions

`agent_user_activity` dimensions

Companion fields

Filtering and ordering

Versioning and deprecation

Example