Skip to Content

Get a trace

GEThttps://api.respan.ai/api/traces/{trace_unique_id}/

Returns aggregate metrics and the full span tree. Metadata keys beginning with _ are reserved for platform use and omitted from span and trace read responses.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

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.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Path parameters

Parameter Type Required Description and constraints
trace_unique_id string Required
Unique trace identifier.

Responses

200

Trace detail with span tree.

application/json

Field Type Requirement Description and constraints
$ object Body
-
id string Optional
Trace identifier.
trace_unique_id string Optional
Unique trace identifier.
root_span_unique_id string Optional
Root span ID for the trace.
unique_organization_id string Optional
Organization unique ID.
organization_id string Optional
Alias of unique_organization_id.
organization_name string Optional
Organization name when available.
organization_key_id string Optional
API key identifier used to create the trace.
environment string Optional
Environment for the trace.
customer_identifier string Optional
Customer or user identifier.
start_time string Optional
When the trace started.
Format: date-time
end_time string Optional
When the trace ended.
Format: date-time
duration number Optional
Total duration in seconds.
span_count integer Optional
Total spans in the trace.
llm_call_count integer Optional
Number of LLM-call spans.
total_cost number Optional
Total cost in USD.
total_prompt_tokens integer Optional
Sum of prompt tokens.
total_completion_tokens integer Optional
Sum of completion tokens.
total_tokens integer Optional
Sum of all tokens.
error_count integer Optional
Number of error spans.
name string Optional
Root span name.
input string or null Optional
Root span input. API key responses may include full storage-enriched content.
output string or null Optional
Root span output. API key responses may include full storage-enriched content.
metadata object Optional
Customer metadata. Keys beginning with _ are reserved and omitted from customer-facing responses.
trace_group_identifier string Optional
Workflow or trace-group identifier.
session_identifier string Optional
Session identifier when present.
model string Optional
Primary/root model used.
storage_object_key string Optional
Storage object key for the root span payload when present.
span_tree array<object> Optional
Hierarchical span tree for the trace.
span_tree[] object Array item
-
span_tree[].id string Optional
Span identifier.
span_tree[].unique_id string Optional
Underlying log unique ID.
span_tree[].span_unique_id string Optional
Unique span identifier within the trace.
span_tree[].span_name string Optional
Span name.
span_tree[].span_parent_id string or null Optional
Parent span ID.
span_tree[].trace_unique_id string Optional
Trace ID.
span_tree[].customer_identifier string Optional
Customer identifier.
span_tree[].thread_identifier string Optional
Thread identifier when present.
span_tree[].session_identifier string Optional
Session identifier when present.
span_tree[].organization_key_id string Optional
API key identifier.
span_tree[].organization_id string Optional
Organization unique ID.
span_tree[].environment string Optional
Environment.
span_tree[].log_type string Optional
Span/log type.
span_tree[].timestamp string Optional
Span end time.
Format: date-time
span_tree[].start_time string Optional
Span start time.
Format: date-time
span_tree[].end_time string Optional
Alias of timestamp.
Format: date-time
span_tree[].prompt_tokens integer Optional
Prompt tokens for this span.
span_tree[].completion_tokens integer Optional
Completion tokens for this span.
span_tree[].total_request_tokens integer Optional
Total tokens for this span.
span_tree[].cost number Optional
Span cost in USD.
span_tree[].model string Optional
Model used by the span.
span_tree[].latency number Optional
Span duration in seconds.
span_tree[].status_code integer Optional
Status code recorded for the span.
span_tree[].status string Optional
Span status.
span_tree[].input string or null Optional
Span input.
span_tree[].output string or null Optional
Span output.
span_tree[].metadata object Optional
Customer metadata. Keys beginning with _ are reserved and omitted from customer-facing responses.
span_tree[].span_links string Optional
Serialized OTEL span links when present.
span_tree[].storage_object_key string Optional
Backing storage object key when present.
span_tree[].span_workflow_name string Optional
Workflow name when present.
span_tree[].children array<object> Optional
Nested child spans.
span_tree[].children[] object Array item
-

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Trace identifier."
    },
    "trace_unique_id": {
      "type": "string",
      "description": "Unique trace identifier."
    },
    "root_span_unique_id": {
      "type": "string",
      "description": "Root span ID for the trace."
    },
    "unique_organization_id": {
      "type": "string",
      "description": "Organization unique ID."
    },
    "organization_id": {
      "type": "string",
      "description": "Alias of `unique_organization_id`."
    },
    "organization_name": {
      "type": "string",
      "description": "Organization name when available."
    },
    "organization_key_id": {
      "type": "string",
      "description": "API key identifier used to create the trace."
    },
    "environment": {
      "type": "string",
      "description": "Environment for the trace."
    },
    "customer_identifier": {
      "type": "string",
      "description": "Customer or user identifier."
    },
    "start_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the trace started."
    },
    "end_time": {
      "type": "string",
      "format": "date-time",
      "description": "When the trace ended."
    },
    "duration": {
      "type": "number",
      "description": "Total duration in seconds."
    },
    "span_count": {
      "type": "integer",
      "description": "Total spans in the trace."
    },
    "llm_call_count": {
      "type": "integer",
      "description": "Number of LLM-call spans."
    },
    "total_cost": {
      "type": "number",
      "description": "Total cost in USD."
    },
    "total_prompt_tokens": {
      "type": "integer",
      "description": "Sum of prompt tokens."
    },
    "total_completion_tokens": {
      "type": "integer",
      "description": "Sum of completion tokens."
    },
    "total_tokens": {
      "type": "integer",
      "description": "Sum of all tokens."
    },
    "error_count": {
      "type": "integer",
      "description": "Number of error spans."
    },
    "name": {
      "type": "string",
      "description": "Root span name."
    },
    "input": {
      "type": "string",
      "description": "Root span input. API key responses may include full storage-enriched content.",
      "nullable": true
    },
    "output": {
      "type": "string",
      "description": "Root span output. API key responses may include full storage-enriched content.",
      "nullable": true
    },
    "metadata": {
      "type": "object",
      "description": "Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses."
    },
    "trace_group_identifier": {
      "type": "string",
      "description": "Workflow or trace-group identifier."
    },
    "session_identifier": {
      "type": "string",
      "description": "Session identifier when present."
    },
    "model": {
      "type": "string",
      "description": "Primary/root model used."
    },
    "storage_object_key": {
      "type": "string",
      "description": "Storage object key for the root span payload when present."
    },
    "span_tree": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Span identifier."
          },
          "unique_id": {
            "type": "string",
            "description": "Underlying log unique ID."
          },
          "span_unique_id": {
            "type": "string",
            "description": "Unique span identifier within the trace."
          },
          "span_name": {
            "type": "string",
            "description": "Span name."
          },
          "span_parent_id": {
            "type": "string",
            "nullable": true,
            "description": "Parent span ID."
          },
          "trace_unique_id": {
            "type": "string",
            "description": "Trace ID."
          },
          "customer_identifier": {
            "type": "string",
            "description": "Customer identifier."
          },
          "thread_identifier": {
            "type": "string",
            "description": "Thread identifier when present."
          },
          "session_identifier": {
            "type": "string",
            "description": "Session identifier when present."
          },
          "organization_key_id": {
            "type": "string",
            "description": "API key identifier."
          },
          "organization_id": {
            "type": "string",
            "description": "Organization unique ID."
          },
          "environment": {
            "type": "string",
            "description": "Environment."
          },
          "log_type": {
            "type": "string",
            "description": "Span/log type."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Span end time."
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "Span start time."
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "description": "Alias of `timestamp`."
          },
          "prompt_tokens": {
            "type": "integer",
            "description": "Prompt tokens for this span."
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Completion tokens for this span."
          },
          "total_request_tokens": {
            "type": "integer",
            "description": "Total tokens for this span."
          },
          "cost": {
            "type": "number",
            "description": "Span cost in USD."
          },
          "model": {
            "type": "string",
            "description": "Model used by the span."
          },
          "latency": {
            "type": "number",
            "description": "Span duration in seconds."
          },
          "status_code": {
            "type": "integer",
            "description": "Status code recorded for the span."
          },
          "status": {
            "type": "string",
            "description": "Span status."
          },
          "input": {
            "type": "string",
            "description": "Span input.",
            "nullable": true
          },
          "output": {
            "type": "string",
            "description": "Span output.",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "description": "Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses."
          },
          "span_links": {
            "type": "string",
            "description": "Serialized OTEL span links when present."
          },
          "storage_object_key": {
            "type": "string",
            "description": "Backing storage object key when present."
          },
          "span_workflow_name": {
            "type": "string",
            "description": "Workflow name when present."
          },
          "children": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Nested child spans."
          }
        }
      },
      "description": "Hierarchical span tree for the trace."
    }
  }
}
Example
JSON
{ "id": "trace_abc123", "trace_unique_id": "trace_abc123", "unique_organization_id": "org_xyz789", "organization_id": "org_xyz789", "organization_name": "Acme Inc", "root_span_unique_id": "span_root_123", "environment": "prod", "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", "span_parent_id": null, "trace_unique_id": "trace_abc123", "start_time": "2024-01-15T10:30:00Z", "timestamp": "2024-01-15T10:30:02Z", "latency": 2, "log_type": "chat", "model": "gpt-4", "prompt_tokens": 50, "completion_tokens": 75, "cost": 0.00345, "status": "success", "status_code": 200, "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]", "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}", "children": [] } ] }

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

404

Not Found

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Trace not found"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Trace not found"
    }
  }
}

429

Rate Limited

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Request was throttled. Expected available in 1 second."

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Request was throttled. Expected available in 1 second."
    }
  }
}

500

Internal Server Error

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Optional
Example: "Internal server error"

OpenAPI response schema

{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "example": "Internal server error"
    }
  }
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Get a trace",
  "operationId": "retrieveTrace",
  "tags": [
    "Traces"
  ],
  "description": "Returns aggregate metrics and the full span tree. Metadata keys beginning with `_` are reserved for platform use and omitted from span and trace read responses.",
  "parameters": [
    {
      "name": "trace_unique_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Unique trace identifier."
    }
  ],
  "responses": {
    "200": {
      "description": "Trace detail with span tree.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Trace identifier."
              },
              "trace_unique_id": {
                "type": "string",
                "description": "Unique trace identifier."
              },
              "root_span_unique_id": {
                "type": "string",
                "description": "Root span ID for the trace."
              },
              "unique_organization_id": {
                "type": "string",
                "description": "Organization unique ID."
              },
              "organization_id": {
                "type": "string",
                "description": "Alias of `unique_organization_id`."
              },
              "organization_name": {
                "type": "string",
                "description": "Organization name when available."
              },
              "organization_key_id": {
                "type": "string",
                "description": "API key identifier used to create the trace."
              },
              "environment": {
                "type": "string",
                "description": "Environment for the trace."
              },
              "customer_identifier": {
                "type": "string",
                "description": "Customer or user identifier."
              },
              "start_time": {
                "type": "string",
                "format": "date-time",
                "description": "When the trace started."
              },
              "end_time": {
                "type": "string",
                "format": "date-time",
                "description": "When the trace ended."
              },
              "duration": {
                "type": "number",
                "description": "Total duration in seconds."
              },
              "span_count": {
                "type": "integer",
                "description": "Total spans in the trace."
              },
              "llm_call_count": {
                "type": "integer",
                "description": "Number of LLM-call spans."
              },
              "total_cost": {
                "type": "number",
                "description": "Total cost in USD."
              },
              "total_prompt_tokens": {
                "type": "integer",
                "description": "Sum of prompt tokens."
              },
              "total_completion_tokens": {
                "type": "integer",
                "description": "Sum of completion tokens."
              },
              "total_tokens": {
                "type": "integer",
                "description": "Sum of all tokens."
              },
              "error_count": {
                "type": "integer",
                "description": "Number of error spans."
              },
              "name": {
                "type": "string",
                "description": "Root span name."
              },
              "input": {
                "type": "string",
                "description": "Root span input. API key responses may include full storage-enriched content.",
                "nullable": true
              },
              "output": {
                "type": "string",
                "description": "Root span output. API key responses may include full storage-enriched content.",
                "nullable": true
              },
              "metadata": {
                "type": "object",
                "description": "Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses."
              },
              "trace_group_identifier": {
                "type": "string",
                "description": "Workflow or trace-group identifier."
              },
              "session_identifier": {
                "type": "string",
                "description": "Session identifier when present."
              },
              "model": {
                "type": "string",
                "description": "Primary/root model used."
              },
              "storage_object_key": {
                "type": "string",
                "description": "Storage object key for the root span payload when present."
              },
              "span_tree": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Span identifier."
                    },
                    "unique_id": {
                      "type": "string",
                      "description": "Underlying log unique ID."
                    },
                    "span_unique_id": {
                      "type": "string",
                      "description": "Unique span identifier within the trace."
                    },
                    "span_name": {
                      "type": "string",
                      "description": "Span name."
                    },
                    "span_parent_id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Parent span ID."
                    },
                    "trace_unique_id": {
                      "type": "string",
                      "description": "Trace ID."
                    },
                    "customer_identifier": {
                      "type": "string",
                      "description": "Customer identifier."
                    },
                    "thread_identifier": {
                      "type": "string",
                      "description": "Thread identifier when present."
                    },
                    "session_identifier": {
                      "type": "string",
                      "description": "Session identifier when present."
                    },
                    "organization_key_id": {
                      "type": "string",
                      "description": "API key identifier."
                    },
                    "organization_id": {
                      "type": "string",
                      "description": "Organization unique ID."
                    },
                    "environment": {
                      "type": "string",
                      "description": "Environment."
                    },
                    "log_type": {
                      "type": "string",
                      "description": "Span/log type."
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Span end time."
                    },
                    "start_time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Span start time."
                    },
                    "end_time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Alias of `timestamp`."
                    },
                    "prompt_tokens": {
                      "type": "integer",
                      "description": "Prompt tokens for this span."
                    },
                    "completion_tokens": {
                      "type": "integer",
                      "description": "Completion tokens for this span."
                    },
                    "total_request_tokens": {
                      "type": "integer",
                      "description": "Total tokens for this span."
                    },
                    "cost": {
                      "type": "number",
                      "description": "Span cost in USD."
                    },
                    "model": {
                      "type": "string",
                      "description": "Model used by the span."
                    },
                    "latency": {
                      "type": "number",
                      "description": "Span duration in seconds."
                    },
                    "status_code": {
                      "type": "integer",
                      "description": "Status code recorded for the span."
                    },
                    "status": {
                      "type": "string",
                      "description": "Span status."
                    },
                    "input": {
                      "type": "string",
                      "description": "Span input.",
                      "nullable": true
                    },
                    "output": {
                      "type": "string",
                      "description": "Span output.",
                      "nullable": true
                    },
                    "metadata": {
                      "type": "object",
                      "description": "Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses."
                    },
                    "span_links": {
                      "type": "string",
                      "description": "Serialized OTEL span links when present."
                    },
                    "storage_object_key": {
                      "type": "string",
                      "description": "Backing storage object key when present."
                    },
                    "span_workflow_name": {
                      "type": "string",
                      "description": "Workflow name when present."
                    },
                    "children": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      },
                      "description": "Nested child spans."
                    }
                  }
                },
                "description": "Hierarchical span tree for the trace."
              }
            }
          },
          "example": {
            "id": "trace_abc123",
            "trace_unique_id": "trace_abc123",
            "unique_organization_id": "org_xyz789",
            "organization_id": "org_xyz789",
            "organization_name": "Acme Inc",
            "root_span_unique_id": "span_root_123",
            "environment": "prod",
            "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",
                "span_parent_id": null,
                "trace_unique_id": "trace_abc123",
                "start_time": "2024-01-15T10:30:00Z",
                "timestamp": "2024-01-15T10:30:02Z",
                "latency": 2,
                "log_type": "chat",
                "model": "gpt-4",
                "prompt_tokens": 50,
                "completion_tokens": 75,
                "cost": 0.00345,
                "status": "success",
                "status_code": 200,
                "input": "[{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]",
                "output": "{\"role\": \"assistant\", \"content\": \"Quantum computing is a revolutionary technology...\"}",
                "children": []
              }
            ]
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "404": {
      "description": "Not Found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Trace not found"
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "Rate Limited",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Request was throttled. Expected available in 1 second."
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "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.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}