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

# List traces

> Every model call without a thread, every thread and every managed session with activity in the window, newest activity first, keyset paged with `after` = the previous page's `next_cursor`. A managed session lists once, as a session: the thread its model calls carry is not a row of its own. Eval calls are excluded. Listing is free; only stored bodies are billed.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/traces
openapi: 3.1.0
info:
  title: Veri API
  description: >-
    REST API for the Veri RL post-training platform. All requests require a
    Bearer API key (`vk_` prefix).
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.veri.studio
    description: Production
security: []
tags:
  - name: Training jobs
    description: Create, monitor, and manage training jobs.
  - name: Datasets
    description: Upload and connect training datasets.
  - name: Deployments
    description: Serve trained models and run inference.
  - name: Volumes
    description: Persistent file storage mounted into jobs.
  - name: Models
    description: Custom model registry deployments serve from.
  - name: Regions
    description: Discover available launch regions.
  - name: GPU
    description: Live GPU availability by provider and region.
  - name: Code artifacts
    description: Upload custom training script bundles.
  - name: Billing
    description: Credit balance and transaction history.
  - name: API keys
    description: Create and revoke API keys.
  - name: Account
    description: The authenticated caller's identity.
  - name: Settings
    description: Account-level integrations (Weights & Biases).
  - name: Metrics
    description: Prometheus metrics export for your own observability stack.
  - name: Evaluators
    description: 'Evaluators: versioned scoring rules (LLM judge, code, human).'
  - name: Experiments
    description: >-
      Experiments: offline runs of a pinned dataset snapshot through a target,
      scored by pinned evaluators.
  - name: Annotation queues
    description: >-
      Human review: queue traces, threads and experiment items, reserve one at a
      time, score them and feed corrections back into datasets.
  - name: Monitors
    description: >-
      Monitors: evaluators scoring a sampled share of a deployment's live
      traffic.
  - name: Observability
    description: Agent conversations, agents and their traffic.
  - name: Ask AI
    description: 'The in-app helper agent: chat, ratings and versions.'
  - name: Public runs
    description: Unauthenticated reads of runs their owners published to Explore.
paths:
  /v1/traces:
    get:
      tags:
        - Observability
      summary: List traces
      description: >-
        Every model call without a thread, every thread and every managed
        session with activity in the window, newest activity first, keyset paged
        with `after` = the previous page's `next_cursor`. A managed session
        lists once, as a session: the thread its model calls carry is not a row
        of its own. Eval calls are excluded. Listing is free; only stored bodies
        are billed.
      operationId: traces
      parameters:
        - name: from
          in: query
          description: 'Window start (RFC 3339). Default: `to` minus 24 hours.'
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: 'Window end (RFC 3339). Default: now. At most 30 days after `from`.'
          required: false
          schema:
            type: string
            format: date-time
        - name: deployment_id
          in: query
          required: false
          schema:
            type: string
        - name: agent
          in: query
          description: Only this agent (its `key`).
          required: false
          schema:
            type: string
        - name: kind
          in: query
          description: call | thread | session
          required: false
          schema:
            type: string
        - name: errors_only
          in: query
          description: Only traces with errors.
          required: false
          schema:
            type: boolean
        - name: active
          in: query
          description: Only threads and sessions live now. Single calls are never active.
          required: false
          schema:
            type: boolean
        - name: q
          in: query
          description: |-
            Case-insensitive substring of a request id (a thread or session
            matches on any of its calls in the window), thread id, session id,
            title or preview.
          required: false
          schema:
            type: string
        - name: tool
          in: query
          description: >-
            Only traces that used this tool in the window (a call or thread
            request

            carrying its result, a session's `agent.tool_use`). Exact name, as
            the

            overview's `top_tools` lists it.
          required: false
          schema:
            type: string
        - name: model
          in: query
          description: >-
            Only traces with a model call on this model in the window (a
            request's

            adapter alias or deployment model, a session's model). Exact name,
            as

            the overview's `top_models` lists it.
          required: false
          schema:
            type: string
        - name: session_id
          in: query
          description: >-
            One managed session: its row, and one `call` row per model call it
            made

            in the window. With `kind=call`, only those calls. On an id that is
            not

            a session of this workspace, an empty list.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Page size, 1..=500 (default 50).
          required: false
          schema:
            type: integer
            format: int64
        - name: after
          in: query
          description: >-
            `next_cursor` of the previous page. It pins the window end `to` of
            the

            page it came from, so omit `to` (or repeat the same value) on the

            following pages; another `to` is a 400.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceList'
        '400':
          description: Bad window, filter or cursor, or observability disabled
      security:
        - bearerAuth: []
components:
  schemas:
    TraceList:
      type: object
      required:
        - object
        - total
        - counts
        - has_more
        - data
      properties:
        object:
          type: string
          description: Always "list".
        total:
          type: integer
          format: int64
          description: Traces matching the filters across all pages.
        counts:
          $ref: '#/components/schemas/TraceCounts'
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - 'null'
          description: Pass as `after` for the next page; null on the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
    TraceCounts:
      type: object
      description: What the whole filtered list holds, across all pages.
      required:
        - calls
        - single_calls
        - threads
        - sessions
        - active_threads
        - active_sessions
      properties:
        calls:
          type: integer
          format: int64
          description: Every model call, the ones inside threads and sessions included.
        single_calls:
          type: integer
          format: int64
          description: '`call` rows.'
        threads:
          type: integer
          format: int64
          description: '`thread` rows.'
        sessions:
          type: integer
          format: int64
          description: '`session` rows.'
        active_threads:
          type: integer
          format: int64
        active_sessions:
          type: integer
          format: int64
    Trace:
      type: object
      description: 'One row of the Traces list: a single model call, a thread or a session.'
      required:
        - id
        - kind
        - status
        - turns
        - llm_calls
        - tool_calls
        - tool_errors
        - errors
        - prompt_tokens
        - cached_prompt_tokens
        - completion_tokens
        - started_at
        - last_activity_at
        - span_strip
        - scores
      properties:
        id:
          type: string
          description: >-
            call: the request id. thread: `{deployment_id}:{thread_id}`.
            session:

            the session id.
        kind:
          type: string
          description: call | thread | session
        title:
          type:
            - string
            - 'null'
          description: Sessions only.
        preview:
          type:
            - string
            - 'null'
          description: |-
            The first user message (200 chars). Stored calls only; null once the
            body has expired.
        request_id:
          type:
            - string
            - 'null'
          description: Calls only.
        agent:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AgentRef'
              description: Null on a single call sent without an `X-Veri-Agent` header.
        deployment_id:
          type:
            - string
            - 'null'
        deployment_name:
          type:
            - string
            - 'null'
        model:
          type:
            - string
            - 'null'
          description: The model of the newest call in the window.
        thread_id:
          type:
            - string
            - 'null'
          description: A thread's id. On a call, only with the `session_id` filter.
        session_id:
          type:
            - string
            - 'null'
          description: A session's id. On a call, only with the `session_id` filter.
        environment_id:
          type:
            - string
            - 'null'
        environment_version:
          type:
            - integer
            - 'null'
          format: int32
          description: 'Sessions only: the environment version the session runs.'
        status:
          type: string
          description: |-
            call: ok | error. thread: active | idle. session: active | paused |
            ended | failed.
        status_code:
          type:
            - integer
            - 'null'
          format: int32
          description: Calls only.
        latency_ms:
          type:
            - integer
            - 'null'
          format: int64
          description: Calls only.
        error_category:
          type:
            - string
            - 'null'
          description: Calls only.
        error_message:
          type:
            - string
            - 'null'
          description: Calls only.
        body_state:
          type:
            - string
            - 'null'
          description: >-
            Calls only: stored | off | expired | dropped_cap | dropped_other |

            too_large | not_covered | unavailable | unknown. A failed call with

            capture on reads stored: status_code and the error fields tell the
            rest.
        turns:
          type: integer
          format: int64
        llm_calls:
          type: integer
          format: int64
        tool_calls:
          type: integer
          format: int64
        tool_errors:
          type: integer
          format: int64
        errors:
          type: integer
          format: int64
        prompt_tokens:
          type: integer
          format: int64
        cached_prompt_tokens:
          type: integer
          format: int64
        completion_tokens:
          type: integer
          format: int64
        cost_usd:
          type:
            - number
            - 'null'
          format: double
          description: 'Sessions: charged so far. Otherwise null.'
        started_at:
          type: string
          format: date-time
        last_activity_at:
          type: string
          format: date-time
        span_strip:
          type: array
          items:
            $ref: '#/components/schemas/Span'
          description: Ordered, the most recent 60.
        scores:
          $ref: '#/components/schemas/ScoreSummary'
    AgentRef:
      type: object
      description: Who a conversation belongs to.
      required:
        - key
        - name
        - kind
      properties:
        key:
          type: string
          description: |-
            `env:<environment_id>` (managed), `agent:<X-Veri-Agent>`, or
            `deployment:<deployment_id>` for threads sent without an agent name.
        name:
          type: string
        kind:
          type: string
          description: managed | external
    Span:
      type: object
      description: 'One timeline segment: a model call or the tool work between two calls.'
      required:
        - kind
        - ms
      properties:
        kind:
          type: string
          description: llm | tool
        ms:
          type: integer
          format: int64
        error:
          type: boolean
          description: true on a failed call or a failed tool call; left out otherwise.
    ScoreSummary:
      type: object
      required:
        - total
        - failed
        - evaluators
      properties:
        total:
          type: integer
          format: int64
        failed:
          type: integer
          format: int64
          description: Scores with passed = false.
        evaluators:
          type: array
          items:
            type: string
          description: Distinct evaluator names (at most 5).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: API key with the `vk_` prefix. Create one from the dashboard.

````

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