Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Use manual ingestion when you have existing log data, custom telemetry pipelines, or OpenTelemetry setups that need to send traces to Respan without using a framework SDK.

​
OTLP endpoint

If you have an existing OpenTelemetry setup, send traces directly to Respan’s OTLP-compatible endpoint. This works with any OpenTelemetry SDK or collector. 
POST https://api.respan.ai/api/v2/traces
Authorization: Bearer {RESPAN_API_KEY}
Content-Type: application/json  (or application/x-protobuf)

​
Environment variable configuration

.env
OTEL_EXPORTER_OTLP_ENDPOINT="https://api.respan.ai/api"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_RESPAN_API_KEY"
OTEL_EXPORTER_OTLP_PROTOCOL="http/json"

​
SDK configuration

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.respan.ai/api/v2/traces",
    headers={"Authorization": "Bearer YOUR_RESPAN_API_KEY"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("gen_ai.request.model", "gpt-4")
    # Your code here
Respan automatically parses OTel spans, extracts Gen AI semantic conventions and Respan-specific attributes, and maps them to the Respan data model. For the full OTLP schema and recognized attributes, see the OTLP ingest API reference.

​
Ingest API

Example project: Ingest traces example
Construct traces by posting spans as JSON. Every span is a JSON object. Spans with the same trace_unique_id are grouped into a single trace. Parent-child relationships are defined via span_parent_id.

​
Endpoint

POST {RESPAN_BASE_URL}/v1/traces/ingest
Authorization: Bearer {RESPAN_API_KEY}

​
Span fields

FieldTypeRequiredDescription
trace_unique_idstringYesGroups spans into a single trace
span_unique_idstringYesUnique ID for the span
span_parent_idstringParent span ID; omit or null for root spans
span_namestringName of the span (e.g. "openai.chat")
start_timestringSpan start time (RFC3339 UTC)
timestampstringSpan end time (RFC3339 UTC)
modelstringModel used
inputstring / objectSpan input data
outputstring / objectSpan output data
metadataobjectCustom key-value pairs
For the full list, see Span fields reference.

​
Example

curl -X POST "$RESPAN_BASE_URL/v1/traces/ingest" \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "trace_unique_id": "a-trace-id",
      "span_unique_id": "root-span-id",
      "span_name": "workflow.start",
      "span_parent_id": null,
      "timestamp": "2025-09-08T07:46:14.007279Z",
      "start_time": "2025-09-08T07:46:14.007279Z"
    },
    {
      "trace_unique_id": "a-trace-id",
      "span_unique_id": "child-span-id",
      "span_name": "openai.chat",
      "span_parent_id": "root-span-id",
      "timestamp": "2025-09-08T07:46:19.041835Z",
      "start_time": "2025-09-08T07:46:18.037942Z"
    }
  ]'