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

# Get the analytics catalog

> Returns the versioned catalog of models, metrics, and dimensions accepted by the query endpoint. Use it to discover valid member names before building a query.



## OpenAPI

````yaml /openapi.json get /api/v1/analytics/catalog
openapi: 3.0.3
info:
  title: Burt Analytics API
  version: 1.0.0
  description: >-
    Organization-scoped analytics over agent runs and the attribution records
    that connect people to those runs. Authenticate with an organization API key
    (`Authorization: Bearer burt_sk_...`) that includes the `analytics:read`
    scope.
servers:
  - url: https://api.burthq.com
security:
  - bearerAuth: []
paths:
  /api/v1/analytics/catalog:
    get:
      summary: Get the analytics catalog
      description: >-
        Returns the versioned catalog of models, metrics, and dimensions
        accepted by the query endpoint. Use it to discover valid member names
        before building a query.
      operationId: getAnalyticsCatalog
      parameters:
        - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: The published catalog.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
              example:
                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
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    RequestId:
      name: x-request-id
      in: header
      required: false
      description: >-
        Optional caller-supplied request ID. Values must contain 1–64 ASCII
        letters, digits, or `._:/=-`; invalid values are replaced with a
        generated UUID.
      schema:
        type: string
        minLength: 1
        maxLength: 64
        pattern: ^[A-Za-z0-9._:/=-]+$
  headers:
    RequestId:
      description: Request identifier. On errors this matches `error.request_id`.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
        maximum: 60
  schemas:
    CatalogResponse:
      type: object
      additionalProperties: false
      required:
        - catalogVersion
        - models
      properties:
        catalogVersion:
          type: string
          description: Version of the published member set.
        models:
          type: array
          items:
            $ref: '#/components/schemas/CatalogModel'
    CatalogModel:
      type: object
      additionalProperties: false
      required:
        - name
        - description
        - grain
        - eventClock
        - metrics
        - dimensions
      properties:
        name:
          type: string
          description: Model name sent as `model` in query requests.
        description:
          type: string
          description: Authoritative description of what the model counts.
        grain:
          type: string
          description: What one row of the model represents.
        eventClock:
          type: string
          description: Timestamp used to bucket rows into date ranges.
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/CatalogMetric'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/CatalogDimension'
    UnauthorizedErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - unauthorized
            message:
              type: string
              enum:
                - Invalid API key
            request_id:
              type: string
    InsufficientScopeErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - insufficient_scope
            message:
              type: string
              enum:
                - API key does not have the required scope
            request_id:
              type: string
    RateLimitedErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - rate_limited
            message:
              type: string
            request_id:
              type: string
    InternalErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - internal_error
            message:
              type: string
              enum:
                - An internal error occurred
            request_id:
              type: string
    CatalogMetric:
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - description
        - additive
        - deprecated
      properties:
        name:
          type: string
          description: Metric name for the `metrics` array in query requests.
        type:
          type: string
          enum:
            - number
        description:
          type: string
        additive:
          type: boolean
          description: Whether values can be summed across groups.
        deprecated:
          $ref: '#/components/schemas/DeprecatedInfo'
    CatalogDimension:
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - description
        - companions
        - deprecated
      properties:
        name:
          type: string
          description: Dimension name for the `dimensions` and `filters` arrays.
        type:
          type: string
          enum:
            - string
            - date
        description:
          type: string
        companions:
          type: array
          items:
            $ref: '#/components/schemas/CatalogCompanion'
          description: Fields returned automatically when this dimension is selected.
        deprecated:
          $ref: '#/components/schemas/DeprecatedInfo'
    DeprecatedInfo:
      type: object
      additionalProperties: false
      nullable: true
      description: >-
        Deprecation metadata for a metric or dimension when set, otherwise
        `null`. Deprecated members remain queryable and do not automatically add
        a warning.
      properties:
        since:
          type: string
          description: Catalog version since which the member was deprecated.
        note:
          type: string
          description: Guidance on what to use instead.
      required:
        - since
        - note
    CatalogCompanion:
      type: object
      additionalProperties: false
      required:
        - name
        - type
        - description
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - string
        description:
          type: string
  responses:
    Unauthorized:
      description: >-
        A missing or malformed key returns this response without spending an
        admission limit. A well-formed unknown or revoked key normally returns
        the same response, but can return 429 while the global
        credential-verification budget is exhausted.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedErrorEnvelope'
          examples:
            unauthorized:
              summary: Invalid API key
              value:
                error:
                  code: unauthorized
                  message: Invalid API key
                  request_id: 550e8400-e29b-41d4-a716-446655440000
    InsufficientScope:
      description: The key is valid but does not include `analytics:read`.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InsufficientScopeErrorEnvelope'
          examples:
            insufficientScope:
              summary: Missing analytics scope
              value:
                error:
                  code: insufficient_scope
                  message: API key does not have the required scope
                  request_id: 550e8400-e29b-41d4-a716-446655440000
    RateLimited:
      description: >-
        A per-key rate limit, the global unknown-credential verification budget,
        or an analytics concurrency limit was exceeded. Read `Retry-After`.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitedErrorEnvelope'
          examples:
            rateLimited:
              summary: Rate limit exceeded
              value:
                error:
                  code: rate_limited
                  message: Too many requests
                  request_id: 550e8400-e29b-41d4-a716-446655440000
            concurrencyLimited:
              summary: Analytics concurrency limit exceeded
              value:
                error:
                  code: rate_limited
                  message: Too many concurrent requests
                  request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalError:
      description: An unexpected application or infrastructure failure occurred.
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalErrorEnvelope'
          examples:
            internalError:
              summary: Unexpected server failure
              value:
                error:
                  code: internal_error
                  message: An internal error occurred
                  request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization API key with the `analytics:read` scope.

````