> ## 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.

# Ingest Observability

> Ingest canonical observability traces, observations, events, and links

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.