Ingest

Ingest a batch of traces

Validates the payload, resolves the API key, prices each span, and buffers the rows for a flush to ClickHouse. Fire-and-forget: a 202 means the batch was accepted, not yet durably written.

post/ingest

Request body

version'v1' required

Wire contract version.

Example request

{
  "version": "v1",
  "traces": [
    {
      "traceId": "0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f",
      "traceName": "classify-email",
      "agentName": "summarizer",
      "workflowName": "deploy-digest",
      "workflowRunId": "run_2024_05_24",
      "sessionId": "session_abc123",
      "customer": {
        "id": "cus_acme",
        "name": "Acme Inc",
        "imageUrl": "https://logo.clearbit.com/acme.com"
      },
      "metadata": {
        "environment": "production",
        "region": "us-east-1"
      },
      "spans": [
        {
          "spanId": "span_1",
          "parentSpanId": "span_0",
          "spanType": "llm",
          "name": "generateText",
          "startTime": 1716566400000,
          "endTime": 1716566401200,
          "status": "ok",
          "provider": "openai",
          "modelId": "gpt-4o",
          "usage": {
            "inputTokens": 1200,
            "outputTokens": 350,
            "totalTokens": 1550
          },
          "ttftMs": 320,
          "metadata": {
            "environment": "production",
            "region": "us-east-1"
          }
        }
      ]
    }
  ]
}

Response

Batch accepted into the write buffer.

acceptedinteger required

Number of span rows accepted.

Example response

{
  "accepted": 3
}

Changes

Changed in 3 of the 4 revisions of this API.2216

Jun 21, 202604549fe6ab0a1See the full diff
- ○
  added the new optional request property traces/items/customer
  new-optional-request-property
Jun 13, 2026da37470dccd52214See the full diff
- ▲
  added 'propertyNames' constraint to the request property traces/items/metadata
  request-property-property-names-added
- ▲
  added 'propertyNames' constraint to the request property traces/items/spans/items/metadata
  request-property-property-names-added
- ●
  the traces/items/metadata/additionalProperties/ request property's maxLength was set to 1024
  request-property-max-length-set
- ●
  the traces/items/spans/items/metadata/additionalProperties/ request property's maxLength was set to 1024
  request-property-max-length-set
- ○
  added the new optional request property traces/items/spans/items/chunkOffsets
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/chunkTokens
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/modelCallMs
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/rateLimit
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/reasoningChunkTokens
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/reasoningDurationMs
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/reasoningOffsets
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/safetyMetadata
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/sources
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/systemFingerprint
  new-optional-request-property
- ○
  added the new optional request property traces/items/spans/items/toolCatalog
  new-optional-request-property
- ○
  the traces/items/spans/items/ttftMs request property type/format was generalized from integer/ to number/
  request-property-type-generalized
- ○
  added the non-success response with the status 413
  response-non-success-status-added
- ○
  added the non-success response with the status 503
  response-non-success-status-added
May 31, 2026509775c21a871See the full diff
- ○
  added the new optional request property traces/items/traceName
  new-optional-request-property

Full history