--- title: "Create a span" method: POST path: "/api/request-logs/" tags: ["spans"] --- # Create a span `POST /api/request-logs/` 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. ## Headers - `Authorization` string, required ## Request body - object - `model` string, required — Model used for the span. - `prompt_messages` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaPromptMessagesItems[] — Chat input messages for the request log. - `completion_message` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaCompletionMessage — Assistant message returned by the model. - `prompt_tokens` integer — Prompt/input tokens for the request. For Anthropic logs this corresponds to `input_tokens` before cache-token normalization. - `completion_tokens` integer — Completion/output tokens for the request. For Anthropic logs this corresponds to `output_tokens`. - `usage` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaUsage — 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. - `prompt_tokens` integer - `completion_tokens` integer - `total_tokens` integer - `input_tokens` integer — Anthropic input token count. - `output_tokens` integer — Anthropic output token count. - `cache_creation_input_tokens` integer — Anthropic cache-creation input tokens. Normalized to `prompt_cache_creation_tokens`. - `cache_read_input_tokens` integer — Anthropic cache-read input tokens. Normalized to `prompt_cache_hit_tokens`. - `temperature` number, double — Sampling temperature (0-2). Higher = more random. - `top_p` number, double — Nucleus sampling parameter. - `max_tokens` integer — Maximum tokens to generate. - `generation_time` number, double — Accepted alias for total generation latency in seconds. Stored as `latency` in responses and query results. - `ttft` number, double — Accepted alias for time to first token in seconds. Stored as `time_to_first_token` in responses and query results. - `customer_params` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaCustomerParams — Extended customer information. `customer_identifier` inside this object is promoted to the log customer identifier. - `customer_identifier` string - `email` string - `name` string - `metadata` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaMetadata — Arbitrary key-value pairs for your reference. - `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. - `stream` boolean — Whether the response was streamed. - `status_code` integer — HTTP status code of the request. - `tools` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaToolsItems[] — Tools available to the model (OpenAI function calling format). - `tool_calls` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaToolCallsItems[] — Tool calls returned by the model. - `timestamp` string, date-time — ISO 8601 timestamp when the request completed. - `trace_unique_id` string — Trace ID to link spans into a trace tree. - `span_name` string — Name of this span within the workflow. - `span_parent_id` string — Parent span ID. Builds the trace hierarchy. - `span_workflow_name` string — Name of the parent workflow. - `custom_identifier` string — Indexed custom identifier for fast querying. - `thread_identifier` string — Conversation thread ID for multi-turn conversations. - `group_identifier` string — Groups related spans together. - `latency` number, double — Total request latency in seconds. `generation_time` is also accepted and normalizes to this field. - `time_to_first_token` number, double — Time to first token in seconds. `ttft` is also accepted and normalizes to this field. - `log_type` 'chat' | 'completion' | 'response' | 'embedding' | 'speech' | 'transcription' | 'workflow' | 'agent' | 'task' | 'tool' | 'guardrail' | 'reranker' | 'other' — Type of span. Determines how `input` and `output` are parsed. - `input` union — 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. - string - object - ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaInputOneOf2Items[] - `output` union — 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. - string - object - ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaOutputOneOf2Items[] - `messages` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaMessagesItems[] — Legacy chat input field. Equivalent to `prompt_messages`; prefer `input` for new integrations. - `cost` number, double — Cost in USD. Auto-calculated from model pricing if omitted. - `tokens_per_second` number, double — Generation speed in tokens per second. - `properties` ApiRequestLogsPostRequestBodyContentApplicationJsonSchema — Typed metadata that preserves native JSON types. - `variables` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaVariables — Variables used for prompt templates. - `customer_identifier` string — Identifier for the end user who made this request. - `tool_choice` union — Controls tool selection. `"none"`, `"auto"`, or a specific tool object. - string - object - `response_format` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaResponseFormat — Response format configuration (e.g. JSON mode or structured output). - `frequency_penalty` number, double — Penalizes repeated tokens (-2 to 2). - `presence_penalty` number, double — Penalizes tokens already present (-2 to 2). - `stop` union — Stop sequence or sequences where generation halts. - string - string[] - `error_message` string — Error message if the request failed. - `warnings` union — Warnings from the request. - string - object - `status` 'success' | 'error' — Request status. - `prompt_id` string — ID of the Respan prompt template used. - `prompt_name` string — Name of the prompt template. - `is_custom_prompt` boolean — Set `true` when using a custom `prompt_id`. - `start_time` string, date-time — ISO 8601 timestamp when the request started. - `full_request` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaFullRequest — Full raw request object for reference. - `full_response` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaFullResponse — Full raw response object from the provider. - `prompt_unit_price` number, double — Custom price per 1M prompt tokens (for self-hosted/fine-tuned models). - `completion_unit_price` number, double — Custom price per 1M completion tokens (for self-hosted/fine-tuned models). - `respan_params` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaRespanParams — Preferred namespace for Respan-specific controls such as customer tagging, metadata, prompt loading, cache settings, and logging flags. - `keywordsai_params` ApiRequestLogsPostRequestBodyContentApplicationJsonSchemaKeywordsaiParams — Legacy alias for `respan_params`. Still accepted and merged into `respan_params`. - `positive_feedback` boolean — User feedback. `true` = positive, `false` = negative. ## Response `201` Span created successfully - SpansCreateSpanResponse201 - `id` string — Unique identifier for the span. Alias for `unique_id`. - `unique_id` string — Full unique identifier for the created span. - `organization_id` string — Organization identifier associated with the span. - `customer_identifier` string — Customer identifier associated with the span. - `status` 'success' | 'error' — Request status. - `cost` number, double — Computed or supplied request cost in USD. - `timestamp` string, date-time — Timestamp when the span was recorded. - `environment` string — Environment derived from the API key used for the log. - `latency` number, double — Stored total latency in seconds. - `time_to_first_token` number, double — Stored time to first token in seconds. - `prompt_cache_creation_tokens` integer — Cache creation tokens normalized from usage. - `prompt_cache_hit_tokens` integer — Cache read/hit tokens normalized from usage. ## Other responses - `400` — Bad Request - `401` — Unauthorized - Missing/invalid authentication - `422` — Unprocessable Entity - `429` — Rate Limited - `500` — Internal Server Error --- [API](https://skmtc.dev/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.dev/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/58a2eabdccf3/schema)