Skip to main content
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

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"
    }
  ]'
⌘I