---
title: "Ingest traces (OTLP)"
method: POST
path: "/api/v2/traces"
tags: ["Traces"]
---

# Ingest traces (OTLP)

`POST /api/v2/traces`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/v2/traces`
- Auth: HTTP bearer

Accepts [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/) JSON or protobuf. The span fields accepted by `POST /api/request-logs/` are not valid here. The `Sample two-span trace` example creates a workflow root span and one chat child span. Before rerunning it, replace `traceId` and `spanId` with new 32-hex and 16-hex IDs to create a separate trace.

For SDK setup, see the [Tracing quickstart](/docs/documentation/features/tracing/quickstart) or the [OpenTelemetry integration](/docs/integrations/opentelemetry), which configures the exporter automatically.

## Request body

- object
  - `resourceSpans` object[], required: Array of resource spans. Each element represents spans from a single resource (service).
    - `resource` object: Resource metadata. Set `service.name` attribute to identify your application.
      - `attributes` object[]: Key-value attributes identifying the resource.
        - `key` string
        - `value` object: OTLP typed value. Use `stringValue`, `intValue`, `doubleValue`, `boolValue`, `arrayValue`, or `kvlistValue`.
    - `scopeSpans` object[]: Array of instrumentation scope spans.
      - `scope` object: Instrumentation scope (library name and version).
        - `name` string
        - `version` string
      - `spans` object[]: Array of span objects.
        - `traceId` string, required: Hex-encoded trace ID (32 hex chars).
        - `spanId` string, required: Hex-encoded span ID (16 hex chars).
        - `parentSpanId` string: Parent span ID. Empty for root spans.
        - `name` string, required: Span operation name.
        - `startTimeUnixNano` string, required: Start time as nanoseconds since Unix epoch.
        - `endTimeUnixNano` string, required: End time as nanoseconds since Unix epoch.
        - `status` object: Span status.
          - `code` 1 | 2: `1` = OK, `2` = ERROR.
          - `message` string: Error description (when code=2).
        - `attributes` object[]: Span attributes as OTLP key-value pairs. Values use OTLP typed wrappers: `stringValue`, `intValue`, `doubleValue`, `boolValue`, `arrayValue`, or `kvlistValue`. **Trace shape:** use `traceloop.span.kind` (`workflow`, `task`, `tool`, `chat`, etc.) to classify spans, and `traceloop.workflow.name` to make the workflow name searchable. For chat/completion child spans, include `llm.request.type` (`chat` or `completion`) so model, messages, and token fields are promoted. **LLM fields:** `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens`, `gen_ai.usage.total_tokens`, `gen_ai.prompt.{N}.role`, `gen_ai.prompt.{N}.content`, `gen_ai.completion.{N}.role`, `gen_ai.completion.{N}.content`. **Respan fields:** `respan.customer_params.customer_identifier`, `respan.customer_params.email`, `respan.customer_params.name`, `respan.threads.thread_identifier`, `respan.trace.trace_group_identifier`, and `respan.metadata.<key>` for custom metadata. All other attributes are stored in metadata and queryable via metadata filters.
          - `key` string
          - `value` object
        - `events` object[]: Span events (e.g. exceptions). Each has `name`, `timeUnixNano`, and `attributes`.

## Response `200`

Spans accepted.

- object
  - `partialSuccess` object
    - `rejectedSpans` integer: Number of spans that failed to ingest.
    - `errorMessage` string: Error description (empty on success).

## Other responses

- `400`: The payload isn't valid OTLP JSON.
- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 4 breaking, 5 info
  - request body became required
  - removed the enum value `1` of the request property `resourceSpans/items/scopeSpans/items/spans/items/status/code`
  - removed the enum value `2` of the request property `resourceSpans/items/scopeSpans/items/spans/items/status/code`
  - the `resourceSpans/items/scopeSpans/items/spans/items/status/code` request property type changed from `string` to `integer`
  - …5 more
- **2026-10-02** `b830b79cfd52`: 1 warning, 3 info
  - removed the optional property `error` from the response with the `400` status
  - added the non-success response with the status `403`
  - removed the non-success response with the status `401`
  - added the required property `detail` to the response with the `400` status
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-trace` removed and replaced with `traces_createTrace`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/v2/traces/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)