---
title: "Create a span"
description: "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."
---

<a id="playground-button:docs/apis/spans/create-span"></a>

**POST** `https://api.respan.ai/api/request-logs/`

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.

## Servers

`https://api.respan.ai` — Respan API Server

<a id="request.auth"></a>

## Authentication

<a id="request.auth.Authorization"></a>

### RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer &lt;RESPAN_API_KEY&gt;. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -&gt; Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: `bearer`; format: `Respan API key`.


```http
Authorization: Bearer $RESPAN_API_KEY
```


<a id="request"></a>

## Request body

A request body is required.

### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Required body | Reference: `#/components/schemas/SpanCreateRequest` |
| `model` | `string` | Required in parent | Model used for the span.<br />Example: `"gpt-4o-mini"` |
| `prompt_messages` | `array<object>` | Optional | Chat input messages for the request log.<br />Example: `[{"role":"user","content":"Hello"}]` |
| `prompt_messages[]` | `object` | Array item | — |
| `completion_message` | `object` | Optional | Assistant message returned by the model.<br />Example: `{"role":"assistant","content":"Hi there!"}` |
| `prompt_tokens` | `integer` | Optional | Prompt/input tokens for the request. For Anthropic logs this corresponds to `input_tokens` before cache-token normalization.<br />Example: `50` |
| `completion_tokens` | `integer` | Optional | Completion/output tokens for the request. For Anthropic logs this corresponds to `output_tokens`.<br />Example: `100` |
| `usage` | `object` | Optional | Provider usage object. Cache token fields such as `cache_creation_input_tokens` and `cache_read_input_tokens` are accepted and normalized into Respan cache-token counters.<br />Example: `{"cache_creation_input_tokens":0,"cache_read_input_tokens":0}` |
| `usage.prompt_tokens` | `integer` | Optional | — |
| `usage.completion_tokens` | `integer` | Optional | — |
| `usage.total_tokens` | `integer` | Optional | — |
| `usage.input_tokens` | `integer` | Optional | Anthropic input token count. |
| `usage.output_tokens` | `integer` | Optional | Anthropic output token count. |
| `usage.cache_creation_input_tokens` | `integer` | Optional | Anthropic cache-creation input tokens. Normalized to `prompt_cache_creation_tokens`. |
| `usage.cache_read_input_tokens` | `integer` | Optional | Anthropic cache-read input tokens. Normalized to `prompt_cache_hit_tokens`. |
| `temperature` | `number` | Optional | Sampling temperature (0-2). Higher = more random.<br />Default: `1`<br />Example: `0.7` |
| `top_p` | `number` | Optional | Nucleus sampling parameter.<br />Default: `1`<br />Example: `1` |
| `max_tokens` | `integer` | Optional | Maximum tokens to generate.<br />Example: `1024` |
| `generation_time` | `number` | Optional | Accepted alias for total generation latency in seconds. Stored as `latency` in responses and query results.<br />Example: `1.23` |
| `ttft` | `number` | Optional | Accepted alias for time to first token in seconds. Stored as `time_to_first_token` in responses and query results.<br />Example: `0.35` |
| `customer_params` | `object` | Optional | Extended customer information. `customer_identifier` inside this object is promoted to the log customer identifier.<br />Example: `{"customer_identifier":"user_123","email":"alice@example.com","name":"Alice"}` |
| `customer_params.customer_identifier` | `string` | Optional | — |
| `customer_params.email` | `string` | Optional | — |
| `customer_params.name` | `string` | Optional | — |
| `metadata` | `object` | Optional | Arbitrary customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing read responses.<br />Example: `{"env":"production","feature":"chat"}` |
| `environment` | `string` | Optional | Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.<br />Allowed: `"prod"`, `"test"`<br />Read only<br />Example: `"prod"` |
| `stream` | `boolean` | Optional | Whether the response was streamed.<br />Default: `false`<br />Example: `false` |
| `status_code` | `integer` | Optional | HTTP status code of the request.<br />Default: `200`<br />Example: `200` |
| `tools` | `array<object>` | Optional | Tools available to the model (OpenAI function calling format).<br />Example: `[{"type":"function","function":{"name":"lookup_order","description":"Lookup an order by ID"}}]` |
| `tools[]` | `object` | Array item | — |
| `tool_calls` | `array<object>` | Optional | Tool calls returned by the model.<br />Example: `[{"id":"call_abc123","type":"function","function":{"name":"lookup_order","arguments":"{\"order_id\":\"ord_123\"}"}}]` |
| `tool_calls[]` | `object` | Array item | — |
| `timestamp` | `string` | Optional | ISO 8601 timestamp when the request completed.<br />Format: `date-time`<br />Example: `"2025-03-15T10:30:00Z"` |
| `trace_unique_id` | `string` | Optional | Trace ID to link spans into a trace tree.<br />Example: `"trace_abc123"` |
| `span_name` | `string` | Optional | Name of this span within the workflow.<br />Example: `"classify_intent"` |
| `span_parent_id` | `string` | Optional | Parent span ID. Builds the trace hierarchy.<br />Example: `"span_parent_001"` |
| `span_workflow_name` | `string` | Optional | Name of the parent workflow.<br />Example: `"customer_support_flow"` |
| `custom_identifier` | `string` | Optional | Indexed custom identifier for fast querying.<br />Example: `"order_456"` |
| `thread_identifier` | `string` | Optional | Conversation thread ID for multi-turn conversations.<br />Example: `"thread_abc"` |
| `group_identifier` | `string` | Optional | Groups related spans together.<br />Example: `"batch_789"` |
| `latency` | `number` | Optional | Total request latency in seconds. `generation_time` is also accepted and normalizes to this field.<br />Example: `1.23` |
| `time_to_first_token` | `number` | Optional | Time to first token in seconds. `ttft` is also accepted and normalizes to this field.<br />Example: `0.35` |
| `log_type` | `string` | Optional | Type of span. Determines how `input` and `output` are parsed.<br />Allowed: `"chat"`, `"completion"`, `"response"`, `"embedding"`, `"speech"`, `"transcription"`, `"workflow"`, `"agent"`, `"task"`, `"tool"`, `"guardrail"`, `"reranker"`, `"other"`<br />Default: `chat`<br />Example: `"chat"` |
| `input` | `string or object or array<object>` | Optional | Preferred universal input field. For chat spans, send an array of message objects or a JSON string. For non-chat spans, send any string/object/array structure that represents the span input.<br />Example: `"[{\"role\": \"user\", \"content\": \"Hello\"}]"` |
| `input (oneOf 1)` | `string` | Schema variant | — |
| `input (oneOf 2)` | `object` | Schema variant | — |
| `input (oneOf 3)` | `array<object>` | Schema variant | — |
| `input (oneOf 3)[]` | `object` | Array item | — |
| `output` | `string or object or array<object>` | Optional | Preferred universal output field. For chat spans, send an assistant message object or a JSON string. For non-chat spans, send any string/object/array structure that represents the span output.<br />Example: `"{\"role\": \"assistant\", \"content\": \"Hi there!\"}"` |
| `output (oneOf 1)` | `string` | Schema variant | — |
| `output (oneOf 2)` | `object` | Schema variant | — |
| `output (oneOf 3)` | `array<object>` | Schema variant | — |
| `output (oneOf 3)[]` | `object` | Array item | — |
| `messages` | `array<object>` | Optional | Legacy chat input field. Equivalent to `prompt_messages`; prefer `input` for new integrations.<br />Example: `[{"role":"user","content":"Hello"}]` |
| `messages[]` | `object` | Array item | — |
| `cost` | `number` | Optional | Cost in USD. Auto-calculated from model pricing if omitted.<br />Example: `0.0025` |
| `tokens_per_second` | `number` | Optional | Generation speed in tokens per second.<br />Example: `45.2` |
| `properties` | `object` | Optional | Typed metadata that preserves native JSON types.<br />Example: `{"cache_hit":false,"score":0.98}` |
| `variables` | `object` | Optional | Variables used for prompt templates.<br />Example: `{"customer_name":"Alice"}` |
| `customer_identifier` | `string` | Optional | Identifier for the end user who made this request.<br />Maximum length: `254`<br />Example: `"user_123"` |
| `tool_choice` | `string or object` | Optional | Controls tool selection. `"none"`, `"auto"`, or a specific tool object. |
| `tool_choice (oneOf 1)` | `string` | Schema variant | — |
| `tool_choice (oneOf 2)` | `object` | Schema variant | — |
| `response_format` | `object` | Optional | Response format configuration (e.g. JSON mode or structured output). |
| `frequency_penalty` | `number` | Optional | Penalizes repeated tokens (-2 to 2).<br />Example: `0` |
| `presence_penalty` | `number` | Optional | Penalizes tokens already present (-2 to 2).<br />Example: `0` |
| `stop` | `string or array<string>` | Optional | Stop sequence or sequences where generation halts. |
| `stop (oneOf 1)` | `string` | Schema variant | — |
| `stop (oneOf 2)` | `array<string>` | Schema variant | — |
| `stop (oneOf 2)[]` | `string` | Array item | — |
| `error_message` | `string` | Optional | Error message if the request failed.<br />Example: `""` |
| `warnings` | `string or object` | Optional | Warnings from the request. |
| `warnings (oneOf 1)` | `string` | Schema variant | — |
| `warnings (oneOf 2)` | `object` | Schema variant | — |
| `status` | `string` | Optional | Request status. `error` is stored as `failed`.<br />Allowed: `"success"`, `"error"`<br />Example: `"success"` |
| `prompt_id` | `string` | Optional | ID of the Respan prompt template used.<br />Example: `"prompt_abc123"` |
| `prompt_name` | `string` | Optional | Name of the prompt template.<br />Example: `"customer_support"` |
| `is_custom_prompt` | `boolean` | Optional | 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.<br />Default: `false`<br />Example: `false` |
| `start_time` | `string` | Optional | ISO 8601 timestamp when the request started.<br />Format: `date-time`<br />Example: `"2025-03-15T10:29:59Z"` |
| `full_request` | `object` | Optional | Full raw request object for reference. |
| `full_response` | `object` | Optional | Full raw response object from the provider. |
| `prompt_unit_price` | `number` | Optional | Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).<br />Example: `2.5` |
| `completion_unit_price` | `number` | Optional | Custom price per 1M completion tokens (for self-hosted/fine-tuned models).<br />Example: `10` |
| `respan_params` | `object` | Optional | Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags. |
| `keywordsai_params` | `object` | Optional | Legacy alias for `respan_params`. Still accepted and merged into `respan_params`. |
| `positive_feedback` | `boolean` | Optional | User feedback. `true` = positive, `false` = negative.<br />Example: `true` |
| `error_code` | `string` | Optional | Normalized application or provider error code.<br />Maximum length: `120` |


<details class="api-schema-source">
<summary>OpenAPI request schema</summary>


```json
{
  "$ref": "#/components/schemas/SpanCreateRequest"
}
```

</details>

##### Example


```json
{
  "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"
}
```


<a id="response"></a>

## Responses

### 201

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

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| <a id="response.body.id"></a>`id` | `string` | Optional | Unique identifier for the span. Alias for `unique_id`. |
| <a id="response.body.unique_id"></a>`unique_id` | `string` | Optional | Full unique identifier for the created span. |
| <a id="response.body.organization_id"></a>`organization_id` | `string` | Optional | Organization identifier associated with the span. |
| <a id="response.body.customer_identifier"></a>`customer_identifier` | `string` | Optional | Customer identifier associated with the span. |
| <a id="response.body.status"></a>`status` | `string` | Optional | Stored status. `warning` means the span was stored with warnings, for example estimated token usage.<br />Allowed: `"success"`, `"warning"`, `"failed"`, `"pending"`, `"running"` |
| <a id="response.body.cost"></a>`cost` | `number` | Optional | Computed or supplied request cost in USD. |
| <a id="response.body.timestamp"></a>`timestamp` | `string` | Optional | Timestamp when the span was recorded.<br />Format: `date-time` |
| <a id="response.body.environment"></a>`environment` | `string` | Optional | Environment derived from the API key used for the log. |
| <a id="response.body.latency"></a>`latency` | `number` | Optional | Stored total latency in seconds. |
| <a id="response.body.time_to_first_token"></a>`time_to_first_token` | `number` | Optional | Stored time to first token in seconds. |
| <a id="response.body.prompt_cache_creation_tokens"></a>`prompt_cache_creation_tokens` | `integer` | Optional | Cache creation tokens normalized from usage. |
| <a id="response.body.prompt_cache_hit_tokens"></a>`prompt_cache_hit_tokens` | `integer` | Optional | Cache read/hit tokens normalized from usage. |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the span. Alias for `unique_id`."
    },
    "unique_id": {
      "type": "string",
      "description": "Full unique identifier for the created span."
    },
    "organization_id": {
      "type": "string",
      "description": "Organization identifier associated with the span."
    },
    "customer_identifier": {
      "type": "string",
      "description": "Customer identifier associated with the span."
    },
    "status": {
      "type": "string",
      "description": "Stored status. `warning` means the span was stored with warnings, for example estimated token usage.",
      "enum": [
        "success",
        "warning",
        "failed",
        "pending",
        "running"
      ]
    },
    "cost": {
      "type": "number",
      "description": "Computed or supplied request cost in USD."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the span was recorded."
    },
    "environment": {
      "type": "string",
      "description": "Environment derived from the API key used for the log."
    },
    "latency": {
      "type": "number",
      "description": "Stored total latency in seconds."
    },
    "time_to_first_token": {
      "type": "number",
      "description": "Stored time to first token in seconds."
    },
    "prompt_cache_creation_tokens": {
      "type": "integer",
      "description": "Cache creation tokens normalized from usage."
    },
    "prompt_cache_hit_tokens": {
      "type": "integer",
      "description": "Cache read/hit tokens normalized from usage."
    }
  }
}
```

</details>

##### Example


```json
{
  "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
}
```


<a id="response.error"></a>

### 400

Bad Request

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `id` | `string` | Optional | Error identifier when available. |
| `error` | `string` | Optional | Error message. |
| `error_class` | `string` | Optional | Error classification. |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Error identifier when available."
    },
    "error": {
      "type": "string",
      "description": "Error message."
    },
    "error_class": {
      "type": "string",
      "description": "Error classification."
    }
  }
}
```

</details>

##### Example


```json
{
  "id": "request_log_organization_banned",
  "error": "Your organization has been banned from creating logs.",
  "error_class": "AuthenticationError"
}
```


### 403

The API key is missing, invalid or expired.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Required in parent | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
```

</details>

##### Example


```json
{
  "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
```


### 422

Unprocessable Entity

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `error` | `string` | Optional | Validation error message.<br />Example: `"Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Validation error message.",
      "example": "Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"
    }
  }
}
```

</details>

### 429

Rate Limited

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `detail` | `string` | Optional | Rate limit detail.<br />Example: `"Rate limit exceeded. Please try again later."` |
| `error` | `string` | Optional | Error message.<br />Example: `"Too many log creation requests. Please slow down."` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Rate limit detail.",
      "example": "Rate limit exceeded. Please try again later."
    },
    "error": {
      "type": "string",
      "description": "Error message.",
      "example": "Too many log creation requests. Please slow down."
    }
  }
}
```

</details>

### 500

Internal Server Error

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |
| `error` | `string` | Optional | Error message<br />Example: `"Internal server error"` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error message",
      "example": "Internal server error"
    }
  }
}
```

</details>

## OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

<!-- openapi-operation:start -->
<details class="api-schema-source">
<summary>OpenAPI operation</summary>


```json
{
  "summary": "Create a span",
  "operationId": "createSpan",
  "tags": [
    "Spans"
  ],
  "description": "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.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SpanCreateRequest"
        },
        "example": {
          "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"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The stored span, with the same fields as Get a span.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique identifier for the span. Alias for `unique_id`."
              },
              "unique_id": {
                "type": "string",
                "description": "Full unique identifier for the created span."
              },
              "organization_id": {
                "type": "string",
                "description": "Organization identifier associated with the span."
              },
              "customer_identifier": {
                "type": "string",
                "description": "Customer identifier associated with the span."
              },
              "status": {
                "type": "string",
                "description": "Stored status. `warning` means the span was stored with warnings, for example estimated token usage.",
                "enum": [
                  "success",
                  "warning",
                  "failed",
                  "pending",
                  "running"
                ]
              },
              "cost": {
                "type": "number",
                "description": "Computed or supplied request cost in USD."
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when the span was recorded."
              },
              "environment": {
                "type": "string",
                "description": "Environment derived from the API key used for the log."
              },
              "latency": {
                "type": "number",
                "description": "Stored total latency in seconds."
              },
              "time_to_first_token": {
                "type": "number",
                "description": "Stored time to first token in seconds."
              },
              "prompt_cache_creation_tokens": {
                "type": "integer",
                "description": "Cache creation tokens normalized from usage."
              },
              "prompt_cache_hit_tokens": {
                "type": "integer",
                "description": "Cache read/hit tokens normalized from usage."
              }
            }
          },
          "example": {
            "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
          }
        }
      }
    },
    "400": {
      "description": "Bad Request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Error identifier when available."
              },
              "error": {
                "type": "string",
                "description": "Error message."
              },
              "error_class": {
                "type": "string",
                "description": "Error classification."
              }
            }
          },
          "example": {
            "id": "request_log_organization_banned",
            "error": "Your organization has been banned from creating logs.",
            "error_class": "AuthenticationError"
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    },
    "422": {
      "description": "Unprocessable Entity",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Validation error message.",
                "example": "Invalid logging format: [{'type': 'missing', 'loc': ['model'], 'msg': 'Field required'}]"
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "Rate Limited",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "detail": {
                "type": "string",
                "description": "Rate limit detail.",
                "example": "Rate limit exceeded. Please try again later."
              },
              "error": {
                "type": "string",
                "description": "Error message.",
                "example": "Too many log creation requests. Please slow down."
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Internal Server Error",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message",
                "example": "Internal server error"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}
```

</details>
<!-- openapi-operation:end -->

<!-- openapi-path-item:start -->
<details class="api-schema-source">
<summary>OpenAPI path metadata</summary>


```json
{}
```

</details>
<!-- openapi-path-item:end -->

<!-- openapi-components:start -->
<details class="api-schema-source">
<summary>Referenced OpenAPI components</summary>


```json
{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "schemas": {
    "SpanCreateRequest": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string",
          "description": "Model used for the span.",
          "example": "gpt-4o-mini"
        },
        "prompt_messages": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Chat input messages for the request log.",
          "example": [
            {
              "role": "user",
              "content": "Hello"
            }
          ]
        },
        "completion_message": {
          "type": "object",
          "description": "Assistant message returned by the model.",
          "example": {
            "role": "assistant",
            "content": "Hi there!"
          }
        },
        "prompt_tokens": {
          "type": "integer",
          "description": "Prompt/input tokens for the request. For Anthropic logs this corresponds to `input_tokens` before cache-token normalization.",
          "example": 50
        },
        "completion_tokens": {
          "type": "integer",
          "description": "Completion/output tokens for the request. For Anthropic logs this corresponds to `output_tokens`.",
          "example": 100
        },
        "usage": {
          "type": "object",
          "description": "Provider usage object. Cache token fields such as `cache_creation_input_tokens` and `cache_read_input_tokens` are accepted and normalized into Respan cache-token counters.",
          "properties": {
            "prompt_tokens": {
              "type": "integer"
            },
            "completion_tokens": {
              "type": "integer"
            },
            "total_tokens": {
              "type": "integer"
            },
            "input_tokens": {
              "type": "integer",
              "description": "Anthropic input token count."
            },
            "output_tokens": {
              "type": "integer",
              "description": "Anthropic output token count."
            },
            "cache_creation_input_tokens": {
              "type": "integer",
              "description": "Anthropic cache-creation input tokens. Normalized to `prompt_cache_creation_tokens`."
            },
            "cache_read_input_tokens": {
              "type": "integer",
              "description": "Anthropic cache-read input tokens. Normalized to `prompt_cache_hit_tokens`."
            }
          },
          "example": {
            "cache_creation_input_tokens": 0,
            "cache_read_input_tokens": 0
          }
        },
        "temperature": {
          "type": "number",
          "description": "Sampling temperature (0-2). Higher = more random.",
          "default": 1,
          "example": 0.7
        },
        "top_p": {
          "type": "number",
          "description": "Nucleus sampling parameter.",
          "default": 1,
          "example": 1
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum tokens to generate.",
          "example": 1024
        },
        "generation_time": {
          "type": "number",
          "description": "Accepted alias for total generation latency in seconds. Stored as `latency` in responses and query results.",
          "example": 1.23
        },
        "ttft": {
          "type": "number",
          "description": "Accepted alias for time to first token in seconds. Stored as `time_to_first_token` in responses and query results.",
          "example": 0.35
        },
        "customer_params": {
          "type": "object",
          "description": "Extended customer information. `customer_identifier` inside this object is promoted to the log customer identifier.",
          "properties": {
            "customer_identifier": {
              "type": "string"
            },
            "email": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "example": {
            "customer_identifier": "user_123",
            "email": "alice@example.com",
            "name": "Alice"
          }
        },
        "metadata": {
          "type": "object",
          "description": "Arbitrary customer metadata. Keys beginning with `_` are reserved and omitted from customer-facing read responses.",
          "example": {
            "env": "production",
            "feature": "chat"
          }
        },
        "environment": {
          "type": "string",
          "description": "Stored environment for the log. This is derived from the API key environment; body-supplied values do not override a prod/test key.",
          "enum": [
            "prod",
            "test"
          ],
          "readOnly": true,
          "example": "prod"
        },
        "stream": {
          "type": "boolean",
          "description": "Whether the response was streamed.",
          "default": false,
          "example": false
        },
        "status_code": {
          "type": "integer",
          "description": "HTTP status code of the request.",
          "default": 200,
          "example": 200
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Tools available to the model (OpenAI function calling format).",
          "example": [
            {
              "type": "function",
              "function": {
                "name": "lookup_order",
                "description": "Lookup an order by ID"
              }
            }
          ]
        },
        "tool_calls": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Tool calls returned by the model.",
          "example": [
            {
              "id": "call_abc123",
              "type": "function",
              "function": {
                "name": "lookup_order",
                "arguments": "{\"order_id\":\"ord_123\"}"
              }
            }
          ]
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when the request completed.",
          "example": "2025-03-15T10:30:00Z"
        },
        "trace_unique_id": {
          "type": "string",
          "description": "Trace ID to link spans into a trace tree.",
          "example": "trace_abc123"
        },
        "span_name": {
          "type": "string",
          "description": "Name of this span within the workflow.",
          "example": "classify_intent"
        },
        "span_parent_id": {
          "type": "string",
          "description": "Parent span ID. Builds the trace hierarchy.",
          "example": "span_parent_001"
        },
        "span_workflow_name": {
          "type": "string",
          "description": "Name of the parent workflow.",
          "example": "customer_support_flow"
        },
        "custom_identifier": {
          "type": "string",
          "description": "Indexed custom identifier for fast querying.",
          "example": "order_456"
        },
        "thread_identifier": {
          "type": "string",
          "description": "Conversation thread ID for multi-turn conversations.",
          "example": "thread_abc"
        },
        "group_identifier": {
          "type": "string",
          "description": "Groups related spans together.",
          "example": "batch_789"
        },
        "latency": {
          "type": "number",
          "description": "Total request latency in seconds. `generation_time` is also accepted and normalizes to this field.",
          "example": 1.23
        },
        "time_to_first_token": {
          "type": "number",
          "description": "Time to first token in seconds. `ttft` is also accepted and normalizes to this field.",
          "example": 0.35
        },
        "log_type": {
          "type": "string",
          "description": "Type of span. Determines how `input` and `output` are parsed.",
          "default": "chat",
          "enum": [
            "chat",
            "completion",
            "response",
            "embedding",
            "speech",
            "transcription",
            "workflow",
            "agent",
            "task",
            "tool",
            "guardrail",
            "reranker",
            "other"
          ],
          "example": "chat"
        },
        "input": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            },
            {
              "type": "array",
              "items": {
                "type": "object"
              }
            }
          ],
          "description": "Preferred universal input field. For chat spans, send an array of message objects or a JSON string. For non-chat spans, send any string/object/array structure that represents the span input.",
          "example": "[{\"role\": \"user\", \"content\": \"Hello\"}]"
        },
        "output": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            },
            {
              "type": "array",
              "items": {
                "type": "object"
              }
            }
          ],
          "description": "Preferred universal output field. For chat spans, send an assistant message object or a JSON string. For non-chat spans, send any string/object/array structure that represents the span output.",
          "example": "{\"role\": \"assistant\", \"content\": \"Hi there!\"}"
        },
        "messages": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Legacy chat input field. Equivalent to `prompt_messages`; prefer `input` for new integrations.",
          "example": [
            {
              "role": "user",
              "content": "Hello"
            }
          ]
        },
        "cost": {
          "type": "number",
          "description": "Cost in USD. Auto-calculated from model pricing if omitted.",
          "example": 0.0025
        },
        "tokens_per_second": {
          "type": "number",
          "description": "Generation speed in tokens per second.",
          "example": 45.2
        },
        "properties": {
          "type": "object",
          "description": "Typed metadata that preserves native JSON types.",
          "example": {
            "cache_hit": false,
            "score": 0.98
          }
        },
        "variables": {
          "type": "object",
          "description": "Variables used for prompt templates.",
          "example": {
            "customer_name": "Alice"
          }
        },
        "customer_identifier": {
          "type": "string",
          "description": "Identifier for the end user who made this request.",
          "maxLength": 254,
          "example": "user_123"
        },
        "tool_choice": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ],
          "description": "Controls tool selection. `\"none\"`, `\"auto\"`, or a specific tool object."
        },
        "response_format": {
          "type": "object",
          "description": "Response format configuration (e.g. JSON mode or structured output)."
        },
        "frequency_penalty": {
          "type": "number",
          "description": "Penalizes repeated tokens (-2 to 2).",
          "example": 0
        },
        "presence_penalty": {
          "type": "number",
          "description": "Penalizes tokens already present (-2 to 2).",
          "example": 0
        },
        "stop": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ],
          "description": "Stop sequence or sequences where generation halts."
        },
        "error_message": {
          "type": "string",
          "description": "Error message if the request failed.",
          "example": ""
        },
        "warnings": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ],
          "description": "Warnings from the request."
        },
        "status": {
          "type": "string",
          "description": "Request status. `error` is stored as `failed`.",
          "enum": [
            "success",
            "error"
          ],
          "example": "success"
        },
        "prompt_id": {
          "type": "string",
          "description": "ID of the Respan prompt template used.",
          "example": "prompt_abc123"
        },
        "prompt_name": {
          "type": "string",
          "description": "Name of the prompt template.",
          "example": "customer_support"
        },
        "is_custom_prompt": {
          "type": "boolean",
          "description": "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.",
          "default": false,
          "example": false
        },
        "start_time": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when the request started.",
          "example": "2025-03-15T10:29:59Z"
        },
        "full_request": {
          "type": "object",
          "description": "Full raw request object for reference."
        },
        "full_response": {
          "type": "object",
          "description": "Full raw response object from the provider."
        },
        "prompt_unit_price": {
          "type": "number",
          "description": "Custom price per 1M prompt tokens (for self-hosted/fine-tuned models).",
          "example": 2.5
        },
        "completion_unit_price": {
          "type": "number",
          "description": "Custom price per 1M completion tokens (for self-hosted/fine-tuned models).",
          "example": 10
        },
        "respan_params": {
          "type": "object",
          "description": "Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags."
        },
        "keywordsai_params": {
          "type": "object",
          "description": "Legacy alias for `respan_params`. Still accepted and merged into `respan_params`."
        },
        "positive_feedback": {
          "type": "boolean",
          "description": "User feedback. `true` = positive, `false` = negative.",
          "example": true
        },
        "error_code": {
          "type": "string",
          "maxLength": 120,
          "description": "Normalized application or provider error code."
        }
      },
      "required": [
        "model"
      ]
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "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.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}
```

</details>
<!-- openapi-components:end -->