Retrieve a trace | Respan Docs

curl https://api.respan.ai/api/traces/trace_unique_id/ \
     -H "Authorization: Bearer sk_live_xxxxx"

{
  "id": "trace_abc123",
  "trace_unique_id": "trace_abc123",
  "root_span_unique_id": "span_root_123",
  "unique_organization_id": "org_xyz789",
  "organization_id": "org_xyz789",
  "organization_name": "Acme Inc",
  "environment": "production",
  "customer_identifier": "user@example.com",
  "start_time": "2024-01-15T10:30:00Z",
  "end_time": "2024-01-15T10:30:02.500000Z",
  "duration": 2.5,
  "span_count": 3,
  "llm_call_count": 2,
  "total_cost": 0.00345,
  "total_prompt_tokens": 150,
  "total_completion_tokens": 75,
  "total_tokens": 225,
  "error_count": 0,
  "name": "chat_completion",
  "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
  "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}",
  "metadata": {
    "user_id": "user123"
  },
  "trace_group_identifier": "workflow_v1",
  "session_identifier": "session456",
  "model": "gpt-4",
  "span_tree": [
    {
      "id": "log_root_1",
      "unique_id": "log_root_1",
      "span_unique_id": "span_root_123",
      "span_name": "chat_completion",
      "trace_unique_id": "trace_abc123",
      "log_type": "chat",
      "timestamp": "2024-01-15T10:30:02Z",
      "start_time": "2024-01-15T10:30:00Z",
      "prompt_tokens": 50,
      "completion_tokens": 75,
      "cost": 0.00345,
      "model": "gpt-4",
      "latency": 2,
      "status_code": 200,
      "status": "success",
      "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
      "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}",
      "children": []
    }
  ]
}

Retrieve a single trace by trace_unique_id, including aggregate metrics and the full span tree.

Path parameters

trace_unique_idstringRequired

Unique trace identifier.

Response

Trace detail with span tree.

idstring

Trace identifier.

trace_unique_idstring

Unique trace identifier.

root_span_unique_idstring

Root span ID for the trace.

unique_organization_idstring

Organization unique ID.

organization_idstring

Alias of unique_organization_id.

organization_namestring

Organization name when available.

organization_key_idstring

API key identifier used to create the trace.

environmentstring

Environment for the trace.

customer_identifierstring

Customer or user identifier.

start_timedatetime

When the trace started.

end_timedatetime

When the trace ended.

durationdouble

Total duration in seconds.

span_countinteger

Total spans in the trace.

llm_call_countinteger

Number of LLM-call spans.

total_costdouble

Total cost in USD.

total_prompt_tokensinteger

Sum of prompt tokens.

total_completion_tokensinteger

Sum of completion tokens.

total_tokensinteger

Sum of all tokens.

error_countinteger

Number of error spans.

namestring

Root span name.

inputstring

Root span input. API key responses may include full storage-enriched content.

outputstring

Root span output. API key responses may include full storage-enriched content.

metadataobject

Trace metadata.

trace_group_identifierstring

Workflow or trace-group identifier.

session_identifierstring

Session identifier when present.

modelstring

Primary/root model used.

storage_object_keystring

Storage object key for the root span payload when present.

span_treelist of objects

Hierarchical span tree for the trace.

Errors

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

Path parameters

Headers

Response

Errors