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

# Get trace overview

> **Auth:** organization API key (`read` scope or higher) or a signed-in user.

Verdict, evaluation, token and latency totals per `interval` (`hour`, `six_hours` or `day`), plus activity per agent. Filter with `agent_id`, `from` and `to`.



## OpenAPI

````yaml https://cp.xenovia.io/openapi.json get /api/v1/traces/overview
openapi: 3.1.0
info:
  title: Xenovia Control Plane API
  version: 1.0.0
  description: >-
    Management API for agents, providers, policies, telemetry, alerts and
    organization settings.
servers:
  - url: https://cp.xenovia.io
    description: Production
security:
  - BearerAuth: []
paths:
  /api/v1/traces/overview:
    get:
      tags:
        - sessions
      summary: Get trace overview
      description: >-
        **Auth:** organization API key (`read` scope or higher) or a signed-in
        user.


        Verdict, evaluation, token and latency totals per `interval` (`hour`,
        `six_hours` or `day`), plus activity per agent. Filter with `agent_id`,
        `from` and `to`.
      operationId: trace_overview_api_v1_traces_overview_get
      parameters:
        - name: interval
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/TraceOverviewInterval'
            default: hour
        - name: agent_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Agent Id
        - name: from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: From
        - name: to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            title: To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceOverviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TraceOverviewInterval:
      type: string
      enum:
        - hour
        - six_hours
        - day
      title: TraceOverviewInterval
    TraceOverviewResponse:
      properties:
        interval:
          $ref: '#/components/schemas/TraceOverviewInterval'
        buckets:
          items:
            $ref: '#/components/schemas/TraceOverviewBucket'
          type: array
          title: Buckets
        governance_latency_ms_p50:
          anyOf:
            - type: integer
            - type: 'null'
          title: Governance Latency Ms P50
        governance_latency_ms_p95:
          anyOf:
            - type: integer
            - type: 'null'
          title: Governance Latency Ms P95
        agents:
          items:
            $ref: '#/components/schemas/TraceOverviewAgent'
          type: array
          title: Agents
      type: object
      required:
        - interval
        - buckets
        - agents
      title: TraceOverviewResponse
      description: |-
        Aggregates over every telemetry row in the window, so a dashboard never
        has to page raw rows (and sample them) to draw its tiles.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TraceOverviewBucket:
      properties:
        bucket_start:
          type: string
          format: date-time
          title: Bucket Start
        allowed:
          type: integer
          title: Allowed
          default: 0
        blocked:
          type: integer
          title: Blocked
          default: 0
        redacted:
          type: integer
          title: Redacted
          default: 0
        escalated:
          type: integer
          title: Escalated
          default: 0
        failed:
          type: integer
          title: Failed
          default: 0
        evaluations:
          type: integer
          title: Evaluations
          default: 0
        input_tokens:
          type: integer
          title: Input Tokens
          default: 0
        output_tokens:
          type: integer
          title: Output Tokens
          default: 0
        requests:
          type: integer
          title: Requests
          default: 0
        request_latency_ms_sum:
          type: integer
          title: Request Latency Ms Sum
          default: 0
        governed_requests:
          type: integer
          title: Governed Requests
          default: 0
        governance_latency_ms_sum:
          type: integer
          title: Governance Latency Ms Sum
          default: 0
      type: object
      required:
        - bucket_start
      title: TraceOverviewBucket
      description: >-
        One UTC interval of the overview. Verdict counts use the request-verdict

        rules the console applies to every telemetry row; ``evaluations`` counts

        policy and guardrail runs; tokens count model calls only; latency covers

        completed requests (request_finished rows). Governance latency is the

        wall-clock time a request spent in policy (OPA) and guardrail (SLM
        check)

        runs, overlapping runs counted once, over the requests that ran any.
    TraceOverviewAgent:
      properties:
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        records:
          type: integer
          title: Records
        successful_records:
          type: integer
          title: Successful Records
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        last_observed_at:
          type: string
          format: date-time
          title: Last Observed At
      type: object
      required:
        - agent_id
        - records
        - successful_records
        - input_tokens
        - output_tokens
        - last_observed_at
      title: TraceOverviewAgent
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token: an organization API key (`ak_…`) created under Settings →
        API Keys, or a dashboard user session token. Agent keys (`xe_…`) are not
        accepted here. Endpoints marked as user-only in their description reject
        organization keys with `403`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.