Ingest traces from logs

POST /api/v1/traces/ingest

Python

import requests

URL = "https://api.keywordsai.co/v1/traces/ingest"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
    "Content-Type": "application/json",
}

payload = [
    {
        "trace_unique_id": "a-trace-id",
        "span_unique_id": "root-span-id",
        "span_name": "pirate_joke_plus_audience_reactions.workflow",
        "span_parent_id": None,
        "timestamp": "2025-09-08T07:46:19.041835Z",
        "start_time": "2025-09-08T07:46:14.007279Z",
        "span_workflow_name": "pirate_joke_plus_audience_reactions",
        "span_path": "",
        "provider_id": "",
        "model": "python",
        "input": "{\"args\": [], \"kwargs\": {}}",
        "output": "\"python\"",
        "encoding_format": "float",
        "latency": 5.034556,
        "keywordsai_params": {"has_webhook": false, "environment": "prod"},
        "disable_log": false
    },
    {
        "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:14.617987Z",
        "start_time": "2025-09-08T07:46:14.007452Z",
        "span_workflow_name": "pirate_joke_generator",
        "span_path": "joke_creation",
        "provider_id": "openai",
        "model": "gpt-3.5-turbo",
        "input": "[{\"role\": \"assistant\", \"content\": \"Why did the opentelemetry developer go broke?\\n\\n\"}, {\"role\": \"user\", \"content\": \"Tell me a joke about opentelemetry\"}]",
        "output": "{\"role\": \"assistant\", \"content\": \"Why did the opentelemetry developer go broke?\\n\\n\"}",
        "prompt_messages": [
            {"role": "assistant", "content": "Why did the opentelemetry developer go broke?\\n\\n"},
            {"role": "user", "content": "Tell me a joke about opentelemetry"}
        ],
        "completion_message": {"role": "assistant", "content": "Why did the opentelemetry developer go broke?\\n\\n"},
        "encoding_format": "float",
        "prompt_tokens": 15,
        "completion_tokens": 10,
        "cost": 2.25e-05,
        "latency": 0.610535,
        "keywordsai_params": {"has_webhook": false, "environment": "prod"},
        "disable_log": false
    }
]

resp = requests.post(URL, json=payload, headers=headers)
print(resp.status_code)
print(resp.text)

{
  "status": "ok",
  "ingested_spans": 2,
  "created_traces": 1,
  "trace_ids": ["a-trace-id"],
  "errors": []
}

Ingest a batch of span logs to construct one or more traces. Use this to import historical data or programmatically build traces when SDK instrumentation isn’t feasible.

If you’re starting fresh, we recommend using an SDK/integration (e.g., OpenAI Agents SDK) to capture traces automatically. This endpoint is best for bulk import and migration workflows.

Example project: Github Link

Body

body · array · required

Array of span log objects. Each object corresponds to a span within a trace. Spans with the same trace_unique_id are grouped into a single trace. Parent-child relationships are inferred via span_parent_id. Aligns with the sample payload in the logs_to_trace example.

trace_unique_id · string · required

Unique identifier for the trace. All spans with this value are grouped together.

span_unique_id · string · required

Unique identifier for the span.

span_parent_id · string

Parent span ID; omit or set null for root spans.

span_name · string

Name of the span (e.g., “openai.chat”, “workflow.start”).

span_workflow_name · string

Nearest parent workflow name.

span_path · string

Nested path within the workflow (e.g., “joke_creation.store_joke”).

start_time · string

RFC3339 UTC start timestamp.

timestamp · string

RFC3339 UTC end/event timestamp.

latency · number

Latency in seconds for the span operation.

input · string

Raw input string or JSON serialized string used by the span.

output · string

Raw output string or JSON serialized string produced by the span.

model · string

Model name used by the span (e.g., “gpt-3.5-turbo”, “gpt-4o-mini”).

encoding_format · string

Embedding encoding format for spans that generate embeddings (e.g., “float”).

provider_id · string

LLM or service provider ID (e.g., “openai”).

prompt_tokens · integer

Number of prompt tokens used (if applicable).

completion_tokens · integer

Number of completion tokens used (if applicable).

cost · float

Cost associated with the span (if applicable).

metadata · object

Custom attributes as a key-value object.

warnings · string

Warnings or notes captured during span execution.

disable_log · boolean

Set true to disable logging for the span in observability system.

disable_fallback · boolean

Disable fallback behavior for the span if supported.

keywordsai_params · object

Additional Keywords AI parameters (e.g., has_webhook, environment).

temperature · number

Controls randomness for LLM spans; typical range 0.0–1.0.

presence_penalty · number

Presence penalty parameter used in some LLM requests.

frequency_penalty · number

Frequency penalty parameter used in some LLM requests.

max_tokens · integer

Maximum tokens requested for completion/embedding generations.

stream · boolean

Whether streaming was enabled for the span.

prompt_messages · array

Array of messages sent to the LLM (each with role and content). Present for chat spans.

completion_message · object

Assistant message returned by the LLM (role/content). Present for chat spans.

Python

import requests

URL = "https://api.keywordsai.co/v1/traces/ingest"
headers = {
    "Authorization": f"Bearer {YOUR_KEYWORDS_AI_API_KEY}",
    "Content-Type": "application/json",
}

payload = [
    {
        "trace_unique_id": "a-trace-id",
        "span_unique_id": "root-span-id",
        "span_name": "pirate_joke_plus_audience_reactions.workflow",
        "span_parent_id": None,
        "timestamp": "2025-09-08T07:46:19.041835Z",
        "start_time": "2025-09-08T07:46:14.007279Z",
        "span_workflow_name": "pirate_joke_plus_audience_reactions",
        "span_path": "",
        "provider_id": "",
        "model": "python",
        "input": "{\"args\": [], \"kwargs\": {}}",
        "output": "\"python\"",
        "encoding_format": "float",
        "latency": 5.034556,
        "keywordsai_params": {"has_webhook": false, "environment": "prod"},
        "disable_log": false
    },
    {
        "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:14.617987Z",
        "start_time": "2025-09-08T07:46:14.007452Z",
        "span_workflow_name": "pirate_joke_generator",
        "span_path": "joke_creation",
        "provider_id": "openai",
        "model": "gpt-3.5-turbo",
        "input": "[{\"role\": \"assistant\", \"content\": \"Why did the opentelemetry developer go broke?\\n\\n\"}, {\"role\": \"user\", \"content\": \"Tell me a joke about opentelemetry\"}]",
        "output": "{\"role\": \"assistant\", \"content\": \"Why did the opentelemetry developer go broke?\\n\\n\"}",
        "prompt_messages": [
            {"role": "assistant", "content": "Why did the opentelemetry developer go broke?\\n\\n"},
            {"role": "user", "content": "Tell me a joke about opentelemetry"}
        ],
        "completion_message": {"role": "assistant", "content": "Why did the opentelemetry developer go broke?\\n\\n"},
        "encoding_format": "float",
        "prompt_tokens": 15,
        "completion_tokens": 10,
        "cost": 2.25e-05,
        "latency": 0.610535,
        "keywordsai_params": {"has_webhook": false, "environment": "prod"},
        "disable_log": false
    }
]

resp = requests.post(URL, json=payload, headers=headers)
print(resp.status_code)
print(resp.text)

{
  "status": "ok",
  "ingested_spans": 2,
  "created_traces": 1,
  "trace_ids": ["a-trace-id"],
  "errors": []
}

Prerequisites for successful ingestion:

• Accurate timestamps for each span (start_time and/or timestamp) to preserve relative timing within a trace.
• Properly assigned trace and span IDs that reflect the correct parent-child relationships (trace_unique_id groups spans into a single trace; span_parent_id links children to their parents).