---
title: "POST /projects/{projectId}/trace-payload"
method: POST
path: "/projects/{projectId}/trace-payload"
---

# POST /projects/{projectId}/trace-payload

`POST /projects/{projectId}/trace-payload`

## Request

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

POST /api/v1/projects/{projectId}/trace-payload on the Caveman Cloud control plane. Requires the payload:read scope. Exposed to autonomous agents as the payload 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.

## Request body

- object
  - `from` string, date-time, required: Explicit UTC start of a window spanning at most 90 days.
  - `to` string, date-time, required: Explicit UTC end, after from and at most 90 days later.
  - `trace_id` string, required
  - `request_id` string, uuid, required
  - `kind` 'request' | 'response' | 'request_compressed', required
  - `section` integer: Read one part of the body by its outline index. A body over 64 KiB answers with status captured_outline: its parts with sizes and tool names, no text.
  - `offset` integer: Byte offset into the section; pass the previous answer's next_offset to read on.

## Response `2XX`

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

## Other responses

- `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)