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

# Query trace statistics for an agent



## OpenAPI

````yaml /public-openapi.json post /agent/v1/agents/{agent_id}/traces/stats/query
openapi: 3.1.0
info:
  title: Atlan public API
  version: current
  description: >-
    Public HTTP API reference for Registry, Skills, Agents, outputs, files, MCP
    servers and tools, and OTLP telemetry ingestion.
servers:
  - url: https://agentgateway.atlan.engineering
    description: Atlan API base URL
security:
  - bearer: []
tags:
  - name: Core
  - name: Skill
  - name: Agent
  - name: Files
  - name: MCP
  - name: Observability
paths:
  /agent/v1/agents/{agent_id}/traces/stats/query:
    post:
      tags:
        - Agent
      summary: Query trace statistics for an agent
      operationId: agent.queryAgentTraceStats
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: start_time_unix_seconds
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: end_time_unix_seconds
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: sort
          in: query
          required: false
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          schema:
            type: string
        - name: session_status
          in: query
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/agent-gateway-TraceStatsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agent-gateway-TraceStatsEnvelope'
          description: HTTP 200 response.
        '400':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_json
                          - invalid_query
          description: HTTP 400 response.
        '401':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - alg_mismatch
                          - alg_not_allowed
                          - audience_mismatch
                          - invalid_api_key
                          - missing_identity
                          - missing_org
                          - missing_user
                          - signature_invalid
                          - token_expired
                          - token_malformed
                          - token_missing
                          - token_not_yet_valid
                          - token_rejected
                          - token_service_account_unbound
                          - unknown_account
                          - unknown_key
                          - untrusted_issuer
          description: HTTP 401 response.
        '403':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - access_denied
                          - account_suspended
          description: HTTP 403 response.
        '404':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
          description: HTTP 404 response.
        '415':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - unsupported_content_type
          description: HTTP 415 response.
        '422':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - validation_failed
          description: HTTP 422 response.
        '500':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - internal_error
          description: HTTP 500 response.
        '503':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - auth_unavailable
                          - service_overloaded
          description: HTTP 503 response.
        '504':
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/agent-ProblemDetails'
                  - type: object
                    required:
                      - code
                    properties:
                      code:
                        type: string
                        enum:
                          - request_timeout
          description: HTTP 504 response.
      security:
        - bearer: []
components:
  schemas:
    agent-gateway-TraceStatsRequest:
      type: object
      required:
        - start_time_unix_seconds
        - end_time_unix_seconds
        - request_type
        - queries
      properties:
        bucket:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/agent-gateway-TraceStatsBucket'
        compare:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/agent-gateway-TraceStatsCompareMode'
        end_time_unix_seconds:
          type: integer
          format: int64
        queries:
          type: array
          items:
            $ref: '#/components/schemas/agent-gateway-TraceStatsPanelQuery'
        request_type:
          $ref: '#/components/schemas/agent-gateway-TraceStatsRequestType'
        start_time_unix_seconds:
          type: integer
          format: int64
        workspace_id:
          type:
            - string
            - 'null'
    agent-gateway-TraceStatsEnvelope:
      type: object
      required:
        - data
        - meta
      properties:
        comparison:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/agent-gateway-TraceStatsComparison'
        data:
          $ref: '#/components/schemas/agent-gateway-TraceStatsData'
        meta:
          $ref: '#/components/schemas/agent-gateway-TraceStatsMeta'
    agent-ProblemDetails:
      type: object
      required:
        - title
        - status
        - detail
        - code
      properties:
        code:
          type: string
        detail:
          type: string
        status:
          type: integer
          format: int32
          minimum: 0
        title:
          type: string
        trace_id:
          type:
            - string
            - 'null'
    agent-gateway-TraceStatsBucket:
      type: string
      enum:
        - day
        - week
    agent-gateway-TraceStatsCompareMode:
      type: string
      enum:
        - none
        - previous_period
    agent-gateway-TraceStatsPanelQuery:
      type: object
      required:
        - name
        - measure
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/agent-gateway-TraceStatsFilter'
        group_by:
          type: array
          items:
            $ref: '#/components/schemas/agent-gateway-TraceStatsGroupBy'
        limit:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
        measure:
          $ref: '#/components/schemas/agent-gateway-TraceStatsMeasure'
        name:
          type: string
        order:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/agent-gateway-TraceStatsOrder'
    agent-gateway-TraceStatsRequestType:
      type: string
      enum:
        - scalar
        - table
        - time_series
    agent-gateway-TraceStatsComparison:
      type: object
      required:
        - start_time_unix_seconds
        - end_time_unix_seconds
        - data
      properties:
        data:
          $ref: '#/components/schemas/agent-gateway-TraceStatsData'
        end_time_unix_seconds:
          type: integer
          format: int64
        start_time_unix_seconds:
          type: integer
          format: int64
    agent-gateway-TraceStatsData:
      oneOf:
        - type: object
          required:
            - results
            - request_type
          properties:
            request_type:
              type: string
              enum:
                - scalar
            results:
              type: array
              items:
                $ref: '#/components/schemas/agent-gateway-TraceStatsScalarResult'
        - type: object
          required:
            - columns
            - rows
            - request_type
          properties:
            columns:
              type: array
              items:
                $ref: '#/components/schemas/agent-gateway-TraceStatsTableColumn'
            request_type:
              type: string
              enum:
                - table
            rows:
              type: array
              items:
                $ref: '#/components/schemas/agent-gateway-TraceStatsTableRow'
        - type: object
          required:
            - series
            - request_type
          properties:
            request_type:
              type: string
              enum:
                - time_series
            series:
              type: array
              items:
                $ref: '#/components/schemas/agent-gateway-TraceStatsSeries'
    agent-gateway-TraceStatsMeta:
      type: object
      properties:
        warnings:
          type: array
          items:
            type: string
    agent-gateway-TraceStatsFilter:
      type: object
      required:
        - key
        - op
      properties:
        key:
          $ref: '#/components/schemas/agent-gateway-TraceStatsGroupBy'
        op:
          $ref: '#/components/schemas/agent-gateway-TraceStatsFilterOperator'
        value:
          $ref: '#/components/schemas/agent-gateway-TraceStatsFilterValue'
    agent-gateway-TraceStatsGroupBy:
      type: string
      enum:
        - harness
        - skill
        - skill_version
        - command
        - mcp
        - tool
        - model
        - user
    agent-gateway-TraceStatsMeasure:
      type: string
      enum:
        - sessions
        - traces
        - spans
        - skill_invocations
        - tool_calls
        - tokens
        - active_users
        - error_rate
        - success_rate
        - tokens_per_trace
        - cost
        - latency_p50
        - latency_p90
        - latency_p99
    agent-gateway-TraceStatsOrder:
      type: object
      required:
        - by
        - direction
      properties:
        by:
          $ref: '#/components/schemas/agent-gateway-TraceStatsOrderBy'
        direction:
          $ref: '#/components/schemas/agent-gateway-TraceStatsOrderDirection'
    agent-gateway-TraceStatsScalarResult:
      type: object
      required:
        - query_name
        - measure
      properties:
        measure:
          $ref: '#/components/schemas/agent-gateway-TraceStatsMeasure'
        query_name:
          type: string
        unit:
          type:
            - string
            - 'null'
        value:
          type:
            - number
            - 'null'
          format: double
    agent-gateway-TraceStatsTableColumn:
      type: object
      required:
        - name
        - column_type
      properties:
        column_type:
          $ref: '#/components/schemas/agent-gateway-TraceStatsTableColumnType'
        name:
          type: string
        unit:
          type:
            - string
            - 'null'
    agent-gateway-TraceStatsTableRow:
      type: object
      required:
        - groups
        - values
      properties:
        groups: {}
        values: {}
    agent-gateway-TraceStatsSeries:
      type: object
      required:
        - query_name
        - measure
        - points
      properties:
        measure:
          $ref: '#/components/schemas/agent-gateway-TraceStatsMeasure'
        points:
          type: array
          items:
            $ref: '#/components/schemas/agent-gateway-TraceStatsSeriesPoint'
        query_name:
          type: string
        unit:
          type:
            - string
            - 'null'
    agent-gateway-TraceStatsFilterOperator:
      type: string
      enum:
        - eq
        - neq
        - in
        - exists
        - not_exists
    agent-gateway-TraceStatsFilterValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
        - type: array
          items:
            type: string
        - type: array
          items:
            type: number
            format: double
        - type: array
          items:
            type: boolean
    agent-gateway-TraceStatsOrderBy:
      type: string
      enum:
        - value
        - name
    agent-gateway-TraceStatsOrderDirection:
      type: string
      enum:
        - asc
        - desc
    agent-gateway-TraceStatsTableColumnType:
      type: string
      enum:
        - group
        - measure
    agent-gateway-TraceStatsSeriesPoint:
      type: object
      required:
        - timestamp_unix_seconds
      properties:
        timestamp_unix_seconds:
          type: integer
          format: int64
        value:
          type:
            - number
            - 'null'
          format: double
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````