---
title: "Retrieve a span"
method: GET
path: "/api/request-logs/{unique_id}/"
tags: ["spans"]
---

# Retrieve a span

`GET /api/request-logs/{unique_id}/`

Retrieve a span by its unique ID. Returns the full span including input, output, metrics, metadata, trace context, evaluation scores, and credit/budget info (`limit_info`). Metadata keys beginning with `_` are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

## Path parameters

- `unique_id` string, required

## Headers

- `Authorization` string, required

## Response `200`

Successful response for Retrieve span

- SpansRetrieveSpanResponse200 — Full customer-facing span detail. Additional stored or enrichment fields may be present. For usage-capped records, the server can instead return a reduced object with `blurred: true`.
  - `id` string, required — Span ID (alias of `unique_id`).
  - `unique_id` string — Stored unique span ID.
  - `span_unique_id` string — Tracing span ID, when supplied.
  - `trace_unique_id` string — Parent trace ID.
  - `span_name` string — Span name.
  - `span_parent_id` string — Parent span ID.
  - `span_workflow_name` string — Workflow name associated with the span.
  - `timestamp` string, date-time — Completion timestamp.
  - `start_time` string, date-time — Start timestamp.
  - `period_start` string, date-time — Billing/aggregation period start.
  - `period_end` string, date-time — Billing/aggregation period end.
  - `input` union — Canonical span input.
    - string
    - object
    - unknown[]
      - unknown
    - number, double
    - boolean
  - `output` union — Canonical span output.
    - string
    - object
    - unknown[]
      - unknown
    - number, double
    - boolean
  - `prompt_messages` object[]
  - `completion_message` object
  - `completion_messages` unknown[]
    - unknown
  - `full_request` object — Credential-sanitized full request.
  - `full_response` object — Credential-sanitized full response.
  - `model` string — Model used by the span.
  - `provider_id` string — Provider route used by the span.
  - `environment` string — API-key environment.
  - `log_type` string — Span/log type.
  - `log_method` string — How this span was ingested.
  - `status` string — Span status.
  - `status_code` integer — HTTP or application status code.
  - `error_code` string — Normalized error code.
  - `error_message` string — Error message, when the span failed.
  - `warnings` union — Warnings captured for the request.
    - string
    - object
    - unknown[]
      - unknown
    - number, double
    - boolean
  - `prompt_tokens` integer — Input token count.
  - `completion_tokens` integer — Output token count.
  - `total_request_tokens` integer — Total token count.
  - `prompt_cache_hit_tokens` integer — Cached input-token count.
  - `prompt_cache_creation_tokens` integer — Cache-creation input-token count.
  - `reasoning_tokens` integer — Reasoning-token count.
  - `cost` number, double — Cost in USD.
  - `latency` number, double — End-to-end latency in seconds.
  - `time_to_first_token` number, double — Time to first token in seconds.
  - `tokens_per_second` number, double — Output throughput.
  - `routing_time` number, double — Gateway routing time.
  - `metadata` object — Customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing responses.
  - `properties` union — Typed span properties.
    - string
    - object
    - unknown[]
      - unknown
    - number, double
    - boolean
  - `variables` object
  - `tools` object[]
  - `tool_calls` object[]
  - `scores` object — Evaluation scores keyed by evaluator identifier or slug.
  - `customer_identifier` string — End-customer identifier.
  - `customer_email` string — End-customer email.
  - `customer_name` string — End-customer name.
  - `custom_identifier` string — Indexed custom identifier.
  - `group_identifier` string — Group identifier.
  - `session_identifier` string — Session identifier.
  - `thread_identifier` string — Conversation thread identifier.
  - `organization_id` string — Organization UUID.
  - `unique_organization_id` string — Organization UUID.
  - `organization_key_id` string — API-key identifier.
  - `organization_key_name` string — API-key display name.
  - `prompt_id` string — Prompt family ID.
  - `prompt_name` string — Prompt display name.
  - `prompt_version_number` integer — Prompt version number.
  - `deployment_id` string — Deployment ID.
  - `deployment_name` string — Deployment name.
  - `stream` boolean — Whether the response streamed.
  - `temperature` number, double — Sampling temperature.
  - `top_p` number, double — Nucleus-sampling parameter.
  - `max_tokens` integer — Configured generation limit.
  - `response_format` object
  - `limit_info` ApiRequestLogsUniqueIdGetResponsesContentApplicationJsonSchemaLimitInfo
    - `is_allowed` boolean
    - `limits` ApiRequestLogsUniqueIdGetResponsesContentApplicationJsonSchemaLimitInfoLimitsItems[]
      - `name` string
      - `current_value` number, double
      - `new_value` number, double
      - `limit_value` number, double
      - `is_within_limit` boolean
  - `blurred` boolean — When true, usage policy reduced the response to visibility-safe fields.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - Missing/invalid authentication
- `404` — Not Found
- `429` — Rate Limited
- `500` — Internal Server Error

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)