> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keywordsai.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Ingest traces from logs
> Import logs or programmatically construct traces by posting a list of span logs to the ingestion endpoint.
Example project: Logs to trace example
This guide shows how to create traces by sending a list of span logs to the Keywords AI ingestion endpoint.
## Step 1: Prerequisites
* API key with access to your workspace
* Environment variables:
* `KEYWORDSAI_API_KEY`
* `KEYWORDSAI_BASE_URL`
## Step 2: Understand the payload
Send an array of JSON objects, each representing a span (log item). Spans with the same `trace_unique_id` are grouped into a single trace. Parent-child relationships are inferred via `span_parent_id`.
Key fields:
* `trace_unique_id` (string, required) — groups spans into a single trace
* `span_unique_id` (string, required) — unique ID for the span
* `span_parent_id` (string, optional) — omit or set `null` for root spans
* `span_name` (string, optional) — e.g., "openai.chat", "workflow\.start"
* `span_workflow_name` (string, optional) — nearest parent workflow name (not a top-level grouping field)
* `span_path` (string, optional) — nested path within the workflow
* `start_time` (RFC3339 UTC, optional)
* `timestamp` (RFC3339 UTC, optional)
* `provider_id`, `model`, `input`, `output`, `metadata`, `keywordsai_params`, etc. (optional)
## Step 3: Make the request
* Endpoint: `{KEYWORDSAI_BASE_URL}/v1/traces/ingest`
* Authentication: `Authorization: Bearer ${KEYWORDSAI_API_KEY}`
Note: If your organization uses a different ingestion path (e.g., an integration-specific endpoint), use that endpoint instead. TBD
## Payload overview
Send an array of JSON objects. Each object represents a span (log item) that will be assembled into one or more traces.
Field definitions (to be confirmed):
* trace\_unique\_id: string — groups spans into a single trace. Required
* span\_unique\_id: string — unique ID for the span. Required
* span\_parent\_id: string — parent span’s unique ID; omit or set null for root. Optional
* span\_name: string — name of the span (e.g., "openai.chat"). Optional
* span\_workflow\_name: string — name of the workflow or top-level process. Optional
* span\_path: string — nested function/path of the workflow. Optional
* timestamp: ISO 8601 / RFC3339 (UTC) — event/end time. Required?
* start\_time: ISO 8601 / RFC3339 (UTC) — start time. Required?
* input/output: string or JSON. Optional
* provider\_id: string — e.g., "openai". Optional
* latency: number (seconds). Optional
* metadata: object — custom attributes. Optional
* keywordsai\_params: object — additional Keywords AI params. Optional
Validation and construction rules (to be confirmed):
* Spans with the same `trace_unique_id` will be grouped into a single trace.
* Hierarchy is inferred from `span_parent_id` relationships.
* Timestamps should be in UTC using a Z suffix or timezone offset.
* Span IDs should be unique across a trace; avoid collisions with existing traces. TBD
* Maximum payload size, rate limits, and ordering requirements. TBD
## Minimal request example
```bash Bash theme={"system"}
curl -X POST "$KEYWORDSAI_BASE_URL/v1/traces/ingest" \
-H "Authorization: Bearer $KEYWORDSAI_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"trace_unique_id": "a-trace-id",
"span_unique_id": "root-span-id",
"span_name": "workflow.start",
"span_parent_id": null,
"timestamp": "2025-09-08T07:46:14.007279Z",
"start_time": "2025-09-08T07:46:14.007279Z"
},
{
"trace_unique_id": "a-trace-id",
"span_unique_id": "child-span-id",
"span_name": "openai.chat",
"span_parent_id": "root-span-id",
"timestamp": "2025-09-08T07:46:19.041835Z",
"start_time": "2025-09-08T07:46:18.037942Z"
}
]'
```
```python Python theme={"system"}
import os
import requests
BASE_URL = os.getenv("KEYWORDSAI_BASE_URL")
API_KEY = os.getenv("KEYWORDSAI_API_KEY")
payload = [
{
"trace_unique_id": "a-trace-id",
"span_unique_id": "root-span-id",
"span_name": "workflow.start",
"span_parent_id": None,
"timestamp": "2025-09-08T07:46:14.007279Z",
"start_time": "2025-09-08T07:46:14.007279Z",
},
{
"trace_unique_id": "a-trace-id",
"span_unique_id": "child-span-id",
"span_name": "openai.chat",
"span_parent_id": "root-span-id",
"timestamp": "2025-09-08T07:46:19.041835Z",
"start_time": "2025-09-08T07:46:18.037942Z",
},
]
resp = requests.post(
f"{BASE_URL}/v1/traces/ingest",
json=payload,
headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
)
print("Status:", resp.status_code)
print("Body:", resp.text)
```
```typescript Typescript theme={"system"}
const URL = `${process.env.KEYWORDSAI_BASE_URL}/v1/traces/ingest`;
const headers = {
Authorization: `Bearer ${process.env.KEYWORDSAI_API_KEY}`,
"Content-Type": "application/json",
};
const payload = [
{
trace_unique_id: "a-trace-id",
span_unique_id: "root-span-id",
span_name: "workflow.start",
span_parent_id: null,
timestamp: "2025-09-08T07:46:14.007279Z",
start_time: "2025-09-08T07:46:14.007279Z",
},
{
trace_unique_id: "a-trace-id",
span_unique_id: "child-span-id",
span_name: "openai.chat",
span_parent_id: "root-span-id",
timestamp: "2025-09-08T07:46:19.041835Z",
start_time: "2025-09-08T07:46:18.037942Z",
},
];
fetch(URL, { method: "POST", headers, body: JSON.stringify(payload) })
.then((r) => r.json())
.then((d) => console.log(d))
.catch((e) => console.error(e));
```