Trace Ingest

POST /v1/traces/ingest

Batch endpoint for ingesting traces. Accepts up to 100 traces per request.

Most users won't need this endpoint directly — the Python SDK handles trace submission automatically. Use this for custom integrations or non-Python clients.

Key behaviors

ID is optional — omit it and the server generates a UUID. Provide your own for idempotent retries.
Upsert semantics — sending the same id again merges fields. Only non-null fields overwrite. This lets you create a trace with just input, then update it later with output.
Async writes — a 202 Accepted response means the traces passed validation and will be written shortly.

Request

{
  "traces": [
    {
      "name": "customer-support-agent",
      "input": {
        "messages": [
          {"role": "user", "content": "How do I reset my password?"}
        ]
      },
      "output": {
        "message": {
          "role": "assistant",
          "content": "Go to Settings > Security > Reset Password."
        }
      },
      "metadata": {
        "model": "gpt-4",
        "total_tokens": 192
      },
      "tags": ["production", "v2"],
      "status": "success"
    }
  ]
}

Trace fields

Field	Type	Required	Description
`id`	`uuid`	No	Your own UUID for idempotent upserts
`name`	`string`	No	Trace name
`input`	`any`	No	Arbitrary JSON — the input to your operation
`output`	`any`	No	Arbitrary JSON — the output
`metadata`	`object`	No	Key-value metadata (model, tokens, etc.)
`tags`	`string[]`	No	Tags for filtering
`status`	`string`	No	Defaults to `"running"` on create
`started_at`	`datetime`	No	ISO 8601. Defaults to now.
`ended_at`	`datetime`	No	ISO 8601.

Response

202 Accepted

{
  "traces": [
    {"id": "550e8400-e29b-41d4-a716-446655440000"}
  ],
  "errors": []
}

Example

curl -X POST https://api.carrotlabs.ai/v1/traces/ingest \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [{
      "name": "my-agent",
      "input": {"messages": [{"role": "user", "content": "Hello"}]},
      "output": {"message": {"role": "assistant", "content": "Hi!"}},
      "status": "success"
    }]
  }'

Errors

Status	Description
`400`	Empty traces array, too many traces (max 100), or invalid JSON
`401`	Invalid or missing API key