4e064cf81dae

latestOpenAPI 3.1.02026-08-131831,331960.0 KB
spans

Create a span

Create a request-log span via the logging API. This is the standard create endpoint; /api/request-logs/create/ remains supported as a legacy alias. For LLM request logs, send prompt_messages, completion_message, token counts, timing, metadata, tools, and trace fields directly in the body. generation_time is accepted and normalized to latency; ttft is accepted and normalized to time_to_first_token. The stored environment is derived from the API key environment, so use a key for the target environment rather than relying on a body override. 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.

post/api/request-logs/

Headers

Authorizationstring required

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.

Request body

SpanCreateRequest required

Typed metadata that preserves native JSON types.

Response

Span created successfully

idstring

Unique identifier for the span. Alias for unique_id.

unique_idstring

Full unique identifier for the created span.

organization_idstring

Organization identifier associated with the span.

customer_identifierstring

Customer identifier associated with the span.

status'success' | 'error'

Request status.

costnumber double

Computed or supplied request cost in USD.

timestampstring date-time

Timestamp when the span was recorded.

environmentstring

Environment derived from the API key used for the log.

latencynumber double

Stored total latency in seconds.

time_to_first_tokennumber double

Stored time to first token in seconds.

prompt_cache_creation_tokensinteger

Cache creation tokens normalized from usage.

prompt_cache_hit_tokensinteger

Cache read/hit tokens normalized from usage.