Skip to main content
POST
Count 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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
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}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
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).

Response

Count traces

count
number
required

Number of traces matching the filter.