Create a span | Respan Docs

curl -X POST https://api.respan.ai/api/request-logs/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "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": {
    "feature": "chat"
  },
  "stream": false,
  "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": "2026-06-04T10:30:00Z"
}'

{
  "id": "log_abc123...",
  "unique_id": "log_abc123...",
  "organization_id": "org_xyz789",
  "customer_identifier": "user_123",
  "status": "success",
  "cost": 0.000375,
  "timestamp": "2026-03-25T10:30:00Z",
  "environment": "prod",
  "latency": 1.23,
  "time_to_first_token": 0.35,
  "prompt_cache_creation_tokens": 0,
  "prompt_cache_hit_tokens": 0
}

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.

Authentication

AuthorizationBearer

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

This endpoint expects an object.

Response

Span created successfully

idstringOptional

Unique identifier for the span. Alias for unique_id.

unique_idstringOptional

Full unique identifier for the created span.

organization_idstringOptional

Organization identifier associated with the span.

customer_identifierstringOptional

Customer identifier associated with the span.

statusenumOptional

Request status.

Allowed values:

costdoubleOptional

Computed or supplied request cost in USD.

timestampdatetimeOptional

Timestamp when the span was recorded.

environmentstringOptional

Environment derived from the API key used for the log.

latencydoubleOptional

Stored total latency in seconds.

time_to_first_tokendoubleOptional

Stored time to first token in seconds.

prompt_cache_creation_tokensintegerOptional

Cache creation tokens normalized from usage.

prompt_cache_hit_tokensintegerOptional

Cache read/hit tokens normalized from usage.

Errors

400

Bad Request Error

401

Unauthorized Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error