CAcaveman

POST /traces/search

POST /api/v1/traces/search on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Exposed to autonomous agents as the search 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.

post/traces/search

Request

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

Request body

fromstring date-time

UTC start of a window spanning at most 90 days. Left out, it is 24 hours before to.

tostring date-time

UTC end, after from and at most 90 days later. Left out, it is now.

filtersobject

Closed filter keys; an unknown key is refused with the supported list. criterion: {criterion_id, verdict} keeps traces whose latest Judgment on that criterion reads the verdict (passed, failed, not_applicable, inconclusive, error).

group_bystring
page_sizeinteger
sortobject
cursorobject

Response

Successful response. Exact status depends on synchronous or durable delivery outcome.

Changes

No recorded changes to this operation across all 1 revision of this API.