---
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. 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.

## Headers

- `Authorization` string, required

## Request body

- SpanCreateRequest — Typed metadata that preserves native JSON types.

## 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.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)