> ## 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 OTLP Traces

> Ingest OpenTelemetry OTLP trace payloads directly into TraceLM observability v2

Accepts OTLP JSON trace payloads (`resourceSpans`) and maps them to canonical `obs_*` tables.

## Auth

* `Authorization: Bearer <jwt>` or project/service-account `X-API-Key` with `observability:write`

## Headers

* `Content-Type: application/json`
* `X-Idempotency-Key: <stable-key>` (optional; auto-derived from payload if omitted)

## Query Params

* `project_id` (optional if API key can access a single project)

## Request Body

```json theme={null}
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "planner-service"}}
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "trace-abc",
              "spanId": "span-root",
              "name": "agent.run",
              "startTimeUnixNano": "1710000000000000000",
              "endTimeUnixNano": "1710000001000000000"
            }
          ]
        }
      ]
    }
  ]
}
```

## Response

```json theme={null}
{
  "ingest_request_id": "33333333-3333-3333-3333-333333333333",
  "schema_version": "2026-02-23",
  "status": "succeeded",
  "replayed": false,
  "accepted_traces": 1,
  "accepted_spans": 1,
  "accepted_events": 1,
  "accepted_links": 0
}
```