Skip to main content
POST
List traces

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

startedAfter
string
required

Include traces whose first execution started after this timestamp (ISO string). Required.

workflowUuid
string<uuid>

When set, restrict traces to this workflow. Omit to search across workflows in the workspace.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
chatUuid
string<uuid>

When set, restrict traces to the one holding this AI chat. Every action an agent takes in a chat shares a single trace.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
agentUuid
string<uuid>

When set, restrict traces to those an AI agent started from a chat.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
workerUuid
string<uuid>

When set, restrict traces to those this hosted worker opened (cron or inbound HTTP).

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
statuses
enum<string>[]

Filter traces by their derived status (pending if any span anywhere in the trace is still pending, error if a failure stopped the trace, degraded if the trace ran to completion despite a span failing — because the failed node fell back — otherwise success).

Available options:
pending,
error,
degraded,
success
startedBefore
string

Include traces whose first execution started on or before this timestamp (ISO string).

limit
number

Maximum number of traces to return.

offset
number

Number of traces to skip.

Response

List traces

traces
Traces · object[]
required

Traces matching the filter.

count
number
required

Total count of matching traces.