Create a trace (OTLP)

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"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Send traces using the standard OTLP/HTTP protocol. This endpoint expects OTLP JSON or protobuf, not the simpler span fields used by POST /api/request-logs/. To create a visible sample trace from the API reference, use the Sample two-span trace request example below; it creates a workflow root span and one chat child span. If you run the same example more than once, change traceId and spanId values to new 32-hex and 16-hex IDs so each run creates a separate trace.

For SDK setup, use the Respan tracing SDK or the OpenTelemetry integration, which auto-configures the exporter.

Send traces using the standard [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/) protocol. This endpoint expects OTLP JSON or protobuf, not the simpler span fields used by `POST /api/request-logs/`. To create a visible sample trace from the API reference, use the `Sample two-span trace` request example below; it creates a workflow root span and one chat child span. If you run the same example more than once, change `traceId` and `spanId` values to new 32-hex and 16-hex IDs so each run creates a separate trace. For SDK setup, use the [Respan tracing SDK](/docs/sdks/python-sdk/overview) or the [OpenTelemetry integration](/docs/integrations/opentelemetry), which auto-configures the exporter.

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

401

Unauthorized Error