Skip to main content
POST
/
api
/
v2
/
observability
/
ingest
Ingest Observability
curl --request POST \
  --url https://api.tracelm.ai/api/v2/observability/ingest

Documentation Index

Fetch the complete documentation index at: https://docs.tracelm.ai/llms.txt

Use this file to discover all available pages before exploring further.

Ingests observability v2 payloads into canonical obs_* tables.

​
Auth

  • Authorization: Bearer <jwt> or project-scoped X-API-Key.

​
Headers

  • Content-Type: application/json
  • X-TraceLM-Schema-Version: 2026-02-23 (recommended)
  • X-Idempotency-Key: <uuid-or-stable-key> (recommended, full replay semantics in Phase 2)

​
Request Body

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_version": "2026-02-23",
  "traces": [
    {
      "trace_id": "11111111-1111-1111-1111-111111111111",
      "source_trace_id": null,
      "root_name": "agent.run",
      "status": "success",
      "environment": "prod",
      "session_id": "sess_123",
      "started_at": "2026-02-23T10:00:00Z",
      "ended_at": "2026-02-23T10:00:02Z",
      "metadata": {"tenant": "acme"},
      "observations": [
        {
          "observation_id": "22222222-2222-2222-2222-222222222222",
          "kind": "generation",
          "name": "planner",
          "status": "success",
          "start_ts": "2026-02-23T10:00:00Z",
          "end_ts": "2026-02-23T10:00:01Z",
          "provider": "openai",
          "model": "gpt-4o-mini"
        }
      ],
      "events": [
        {
          "event_type": "trace.created",
          "event_ts": "2026-02-23T10:00:00Z",
          "payload": {"source": "sdk"}
        }
      ],
      "links": []
    }
  ]
}

​
Response

{
  "ingest_request_id": "33333333-3333-3333-3333-333333333333",
  "schema_version": "2026-02-23",
  "status": "succeeded",
  "replayed": false,
  "created_traces": 1,
  "created_observations": 1,
  "created_events": 1,
  "created_links": 0
}

​
Notes

  • project_id is required for JWTs with access to multiple projects.
  • X-Idempotency-Key is required for batched requests (traces.length > 1).
  • If X-Idempotency-Key is omitted for single-trace payloads, TraceLM uses trace:<trace_id> fallback.