Ingest traces (OTLP) | Respan Docs

curl -X POST https://api.respan.ai/api/v2/traces \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "respan-docs-api-reference"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "scope": {
            "name": "manual-api-reference",
            "version": "1.0.0"
          },
          "spans": [
            {
              "traceId": "11111111111111111111111111111111",
              "spanId": "2222222222222222",
              "name": "sample_trace",
              "startTimeUnixNano": "1780000000000000000",
              "endTimeUnixNano": "1780000001000000000",
              "status": {
                "code": 1
              },
              "attributes": [
                {
                  "key": "traceloop.span.kind",
                  "value": {
                    "stringValue": "workflow"
                  }
                },
                {
                  "key": "traceloop.workflow.name",
                  "value": {
                    "stringValue": "api-reference-sample-trace"
                  }
                },
                {
                  "key": "respan.trace.trace_group_identifier",
                  "value": {
                    "stringValue": "api-reference-sample-trace"
                  }
                },
                {
                  "key": "respan.customer_params.customer_identifier",
                  "value": {
                    "stringValue": "docs-sample-user"
                  }
                },
                {
                  "key": "respan.metadata.source",
                  "value": {
                    "stringValue": "api-reference-create-trace"
                  }
                }
              ]
            },
            {
              "traceId": "11111111111111111111111111111111",
              "spanId": "3333333333333333",
              "name": "sample_llm_call",
              "startTimeUnixNano": "1780000000100000000",
              "endTimeUnixNano": "1780000000900000000",
              "parentSpanId": "2222222222222222",
              "status": {
                "code": 1
              },
              "attributes": [
                {
                  "key": "traceloop.span.kind",
                  "value": {
                    "stringValue": "chat"
                  }
                },
                {
                  "key": "llm.request.type",
                  "value": {
                    "stringValue": "chat"
                  }
                },
                {
                  "key": "traceloop.workflow.name",
                  "value": {
                    "stringValue": "api-reference-sample-trace"
                  }
                },
                {
                  "key": "respan.trace.trace_group_identifier",
                  "value": {
                    "stringValue": "api-reference-sample-trace"
                  }
                },
                {
                  "key": "respan.customer_params.customer_identifier",
                  "value": {
                    "stringValue": "docs-sample-user"
                  }
                },
                {
                  "key": "gen_ai.system",
                  "value": {
                    "stringValue": "openai"
                  }
                },
                {
                  "key": "gen_ai.request.model",
                  "value": {
                    "stringValue": "gpt-4o-mini"
                  }
                },
                {
                  "key": "gen_ai.response.model",
                  "value": {
                    "stringValue": "gpt-4o-mini"
                  }
                },
                {
                  "key": "gen_ai.prompt.0.role",
                  "value": {
                    "stringValue": "user"
                  }
                },
                {
                  "key": "gen_ai.prompt.0.content",
                  "value": {
                    "stringValue": "Hello from the Create a trace API reference."
                  }
                },
                {
                  "key": "gen_ai.completion.0.role",
                  "value": {
                    "stringValue": "assistant"
                  }
                },
                {
                  "key": "gen_ai.completion.0.content",
                  "value": {
                    "stringValue": "Hello! This is a sample trace."
                  }
                },
                {
                  "key": "gen_ai.usage.prompt_tokens",
                  "value": {
                    "intValue": "9"
                  }
                },
                {
                  "key": "gen_ai.usage.completion_tokens",
                  "value": {
                    "intValue": "8"
                  }
                },
                {
                  "key": "gen_ai.usage.total_tokens",
                  "value": {
                    "intValue": "17"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Accepts OTLP/HTTP 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 or the OpenTelemetry integration, which configures the exporter automatically.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.

resourceSpanslist of objectsRequired

Array of resource spans. Each element represents spans from a single resource (service).

Response

Spans accepted.

partialSuccessobjectOptional

Errors

400

Bad Request Error

403

Forbidden Error