Get span

Endpoint: GET /spans/{span_id}

Description

Returns one span by its integer row id. Spans are the individual operations recorded inside a trace; they are created only by ingesting OTLP traces.

Parameters

• Path: span_id — the integer row id, not the OTLP hex span_id.

Error responses

• 401 — Authentication failed.
• 404 — "Span with id {span_id} not found." — missing, orphaned (no matching trace yet), or the caller cannot see the parent trace. The same 404 is returned in all cases.
• 422 — span_id is not an integer.
• 500 — "An error occurred while retrieving the span."

Responses

• 200 — JSON object with the shape below (snake_case).

Example response (200)

{
  "id": 1,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "parent_span_id": null,
  "name": "chat completion",
  "otel_kind": "INTERNAL",
  "span_kind": "LLM",
  "start_time": "2026-09-07T10:00:00Z",
  "end_time": "2026-09-07T10:00:00.012Z",
  "duration_ms": 12.3,
  "status_code": "OK",
  "status_message": null,
  "llm_model": "gpt-4o",
  "llm_system": "openai",
  "prompt_tokens": 10,
  "completion_tokens": 5,
  "total_tokens": 15,
  "cached_read_tokens": null,
  "cached_write_tokens": null,
  "cost_usd": null,
  "estimated_cost_usd": "0.0001",
  "tool_name": null,
  "input_value": {},
  "input_mime_type": "application/json",
  "output_value": "Hello!",
  "output_mime_type": "text/plain",
  "attributes": {},
  "events": [],
  "links": [],
  "scope_name": "my-instrumentation",
  "scope_version": "1.0.0",
  "data_collection_id": null,
  "org_id": null,
  "created_at": "2026-09-07T10:00:01Z",
  "updated_at": "2026-09-07T10:00:01Z"
}

{
  "id": 0,
  "trace_id": "string (32-char lowercase hex)",
  "span_id": "string (16-char lowercase hex)",
  "parent_span_id": "string (16-char lowercase hex) | null",
  "name": "string",
  "otel_kind": "UNSPECIFIED | INTERNAL | SERVER | CLIENT | PRODUCER | CONSUMER",
  "span_kind": "LLM | CHAIN | RETRIEVER | RERANKER | TOOL | EMBEDDING | AGENT | GUARDRAIL | EVALUATOR | null",
  "start_time": "date",
  "end_time": "date",
  "duration_ms": "number | null",
  "status_code": "UNSET | OK | ERROR",
  "status_message": "string | null",
  "llm_model": "string | null",
  "llm_system": "string | null",
  "prompt_tokens": "integer | null",
  "completion_tokens": "integer | null",
  "total_tokens": "integer | null",
  "cached_read_tokens": "integer | null",
  "cached_write_tokens": "integer | null",
  "cost_usd": "string | null",
  "estimated_cost_usd": "string | null",
  "tool_name": "string | null",
  "input_value": "string | object | array | null",
  "input_mime_type": "string | null",
  "output_value": "string | object | array | null",
  "output_mime_type": "string | null",
  "attributes": "object | null",
  "events": "array | null",
  "links": "array | null",
  "scope_name": "string | null",
  "scope_version": "string | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "created_at": "date",
  "updated_at": "date"
}

Field notes

• id is the integer row id (used on this path). trace_id and span_id are lowercase hex OTLP ids; parent_span_id is hex or null for a root span.
• Enums:
  • otel_kind: UNSPECIFIED · INTERNAL · SERVER · CLIENT · PRODUCER · CONSUMER.
  • span_kind (OpenInference, optional): LLM · CHAIN · RETRIEVER · RERANKER · TOOL · EMBEDDING · AGENT · GUARDRAIL · EVALUATOR.
  • status_code: UNSET · OK · ERROR.
• input_value / output_value are decoded to JSON structure when the matching *_mime_type is JSON; otherwise they stay a string. attributes / events / links have nested JSON-string object/array values promoted to structure, while prose is left as a string.
• cost_usd is observed LLM spend; estimated_cost_usd is derived from tokens. A span contributes to at most one of the two.
• There is no project_id on a span. user_id is omitted; org_id is present only so clients can tell org-shared from personal.

Visibility

A span is visible exactly when its parent trace is. Project-scoped keys and non-admin org members are gated on the trace's project assignment, not on the span — see Get traces for the full trace visibility rules.

curl

curl "https://api.aegisevals.ai/api/v1/spans/1" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"