Anthropic Gateway1

Behaviors11

Caches6

Credit Transactions2

Dashboard12

Error Groups5

Gateway2

Google Gateway1

Incidents3

Limit Policies5

Models15

OpenAI Batch9

OpenRouter Gateway1

Prompts19

Provider Gateway1

Respan Models1

Spans7

Temporary API Keys5

Traces8

TypeSafe Gateway1

Users4

Spans

Create a span

Changed on Oct 21, 2026

Records a span through the logging API. /api/request-logs/create/ remains supported as a legacy alias. generation_time is normalized to latency, and ttft to time_to_first_token. The API key determines the stored environment; a body value does not override it. Metadata keys beginning with _ are reserved for platform use and omitted from span and trace read responses.

post/api/request-logs/

Request

Base URL
https://api.respan.ai
URL
https://api.respan.ai/api/request-logs/
Auth
HTTP bearer

Request body

modelstring required

Model used for the span.

prompt_messagesobject[]

Chat input messages for the request log.

completion_messageobject

Assistant message returned by the model.

prompt_tokensinteger

Prompt/input tokens for the request. For Anthropic logs this corresponds to input_tokens before cache-token normalization.

completion_tokensinteger

Completion/output tokens for the request. For Anthropic logs this corresponds to output_tokens.

temperaturenumber

Sampling temperature (0-2). Higher = more random.

top_pnumber

Nucleus sampling parameter.

max_tokensinteger

Maximum tokens to generate.

generation_timenumber

Accepted alias for total generation latency in seconds. Stored as latency in responses and query results.

ttftnumber

Accepted alias for time to first token in seconds. Stored as time_to_first_token in responses and query results.

metadataobject

Arbitrary customer metadata. Keys beginning with _ are reserved and omitted from customer-facing read responses.

environment'prod' | 'test'

Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.

streamboolean

Whether the response was streamed.

status_codeinteger

HTTP status code of the request.

toolsobject[]

Tools available to the model (OpenAI function calling format).

tool_callsobject[]

Tool calls returned by the model.

timestampstring date-time

ISO 8601 timestamp when the request completed.

trace_unique_idstring

Trace ID to link spans into a trace tree.

span_namestring

Name of this span within the workflow.

span_parent_idstring

Parent span ID. Builds the trace hierarchy.

span_workflow_namestring

Name of the parent workflow.

custom_identifierstring

Indexed custom identifier for fast querying.

thread_identifierstring

Conversation thread ID for multi-turn conversations.

group_identifierstring

Groups related spans together.

latencynumber

Total request latency in seconds. generation_time is also accepted and normalizes to this field.

time_to_first_tokennumber

Time to first token in seconds. ttft is also accepted and normalizes to this field.

Type of span. Determines how input and output are parsed.

messagesobject[]

Legacy chat input field. Equivalent to prompt_messages; prefer input for new integrations.

costnumber

Cost in USD. Auto-calculated from model pricing if omitted.

tokens_per_secondnumber

Generation speed in tokens per second.

propertiesobject

Typed metadata that preserves native JSON types.

variablesobject

Variables used for prompt templates.

customer_identifierstring

Identifier for the end user who made this request.

response_formatobject

Response format configuration (e.g. JSON mode or structured output).

frequency_penaltynumber

Penalizes repeated tokens (-2 to 2).

presence_penaltynumber

Penalizes tokens already present (-2 to 2).

error_messagestring

Error message if the request failed.

status'success' | 'error'

Request status. error is stored as failed.

prompt_idstring

ID of the Respan prompt template used.

prompt_namestring

Name of the prompt template.

is_custom_promptboolean

Not read at the top level. Respan reads is_custom_prompt only inside a prompt object, as in {"prompt": {"prompt_id": "your-id", "is_custom_prompt": true}}. Set it there for a prompt you manage outside Respan. Otherwise Respan looks up prompt.prompt_id among your saved prompts and rejects the span if none matches. A top-level prompt_id is logged as sent and isn't looked up.

start_timestring date-time

ISO 8601 timestamp when the request started.

full_requestobject

Full raw request object for reference.

full_responseobject

Full raw response object from the provider.

prompt_unit_pricenumber

Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).

completion_unit_pricenumber

Custom price per 1M completion tokens (for self-hosted/fine-tuned models).

respan_paramsobject

Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags.

keywordsai_paramsobject

Legacy alias for respan_params. Still accepted and merged into respan_params.

positive_feedbackboolean

User feedback. true = positive, false = negative.

error_codestring

Normalized application or provider error code.

Example request

{
  "model": "gpt-4o-mini",
  "prompt_messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "completion_message": {
    "role": "assistant",
    "content": "Hi there!"
  },
  "prompt_tokens": 50,
  "completion_tokens": 100,
  "usage": {
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "temperature": 0.7,
  "top_p": 1,
  "max_tokens": 1024,
  "generation_time": 1.23,
  "ttft": 0.35,
  "customer_params": {
    "customer_identifier": "user_123",
    "email": "alice@example.com",
    "name": "Alice"
  },
  "metadata": {
    "env": "production",
    "feature": "chat"
  },
  "environment": "prod",
  "status_code": 200,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Lookup an order by ID"
      }
    }
  ],
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "lookup_order",
        "arguments": "{\"order_id\":\"ord_123\"}"
      }
    }
  ],
  "timestamp": "2025-03-15T10:30:00Z",
  "trace_unique_id": "trace_abc123",
  "span_name": "classify_intent",
  "span_parent_id": "span_parent_001",
  "span_workflow_name": "customer_support_flow",
  "custom_identifier": "order_456",
  "thread_identifier": "thread_abc",
  "group_identifier": "batch_789",
  "latency": 1.23,
  "time_to_first_token": 0.35,
  "log_type": "chat",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "cost": 0.0025,
  "tokens_per_second": 45.2,
  "properties": {
    "cache_hit": false,
    "score": 0.98
  },
  "variables": {
    "customer_name": "Alice"
  },
  "customer_identifier": "user_123",
  "status": "success",
  "prompt_id": "prompt_abc123",
  "prompt_name": "customer_support",
  "start_time": "2025-03-15T10:29:59Z",
  "prompt_unit_price": 2.5,
  "completion_unit_price": 10,
  "positive_feedback": true
}

Response

The stored span, with the same fields as Get a span.

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' | 'warning' | 'failed' | 'pending' | 'running'

Stored status. warning means the span was stored with warnings, for example estimated token usage.

costnumber

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

Stored total latency in seconds.

time_to_first_tokennumber

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.

Changes

Oct 21, 2026c30bcb383ee8 Revision changes
- breaking
  added the new required request property
- breaking
  request body became required
- breaking
  the response's property format changed from double to no format for status
- breaking
  the response's property format changed from double to no format for status
- breaking
  the response's property format changed from double to no format for status
- info
  api operation id spans_createSpan removed and replaced with createSpan
- info
  api tag Spans added
- info
  api tag spans removed
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
Oct 2, 2026b830b79cfd52 Revision changes
- warning
  added the new failed enum value to the response property for the response status
- warning
  added the new pending enum value to the response property for the response status
- warning
  added the new running enum value to the response property for the response status
- warning
  added the new warning enum value to the response property for the response status
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  removed the error enum value from the response property for the response status

Operation history (7 revisions)