---
title: "List traces"
method: GET
path: "/traces"
---

# List traces

`GET /traces`

## Request

- Base URL: `https://api.caveman.so/api/v1`
- URL: `https://api.caveman.so/api/v1/traces`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/api/v1/oauth/authorize`
    - Token URL: `/api/v1/oauth/token` scopes: `trace:read_metadata`
  - HTTP bearer
  - API key in cookie `cave_access`
  - API key in cookie `__Secure-cave_identity.session_token`

GET /api/v1/traces on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the list action of the caveman_traces tool (read access). Search and inspect LLM requests and whole tasks as metadata, span trees and steps, with the judgments on any of them. Captured content needs the connection's explicit payload grant. Scores carry each trace's latest Judgment per criterion, and search filters by a criterion's verdict.

## Query parameters

- `cursor` string
- `filter` union[]
  - union
    - object
      - `field` string, required
      - `op` 'is' | 'is_not' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'regex' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'not_exists'
      - `rule` string: Older name of op; matches_regex means regex. Send op or rule, never both.
      - `value` union
        - string
        - number
        - string[]
    - object
      - `all` union[], required
        - union
          - object
            - `field` string, required
            - `op` 'is' | 'is_not' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'regex' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'not_exists'
            - `rule` string: Older name of op; matches_regex means regex. Send op or rule, never both.
            - `value` union
              - …
          - object
            - `all` union[], required
              - …
          - object
            - `any` union[], required
              - …
    - object
      - `any` union[], required
        - union
          - object
            - `field` string, required
            - `op` 'is' | 'is_not' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'regex' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'not_exists'
            - `rule` string: Older name of op; matches_regex means regex. Send op or rule, never both.
            - `value` union
              - …
          - object
            - `all` union[], required
              - …
          - object
            - `any` union[], required
              - …
- `from` string, date-time
- `limit` integer
- `member_user_id` string
- `sample_data` boolean
- `to` string, date-time
- `window` string
- `workflow` string

## Response `200`

Trace page

## Other responses

- `2XX`: Successful response. Exact status depends on synchronous or durable delivery outcome.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)