---
title: "Create a trace (OTLP)"
method: POST
path: "/api/v2/traces"
tags: ["traces"]
---

# Create a trace (OTLP)

`POST /api/v2/traces`

Send traces using the standard [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/) protocol. This endpoint expects OTLP JSON or protobuf, not the simpler span fields used by `POST /api/request-logs/`. To create a visible sample trace from the API reference, use the `Sample two-span trace` request example below; it creates a workflow root span and one chat child span. If you run the same example more than once, change `traceId` and `spanId` values to new 32-hex and 16-hex IDs so each run creates a separate trace.

For SDK setup, use the [Respan tracing SDK](/docs/sdks/python-sdk/overview) or the [OpenTelemetry integration](/docs/integrations/opentelemetry), which auto-configures the exporter.

## Headers

- `Authorization` string, required

## Request body

- object
  - `resourceSpans` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItems[], required — Array of resource spans. Each element represents spans from a single resource (service).
    - `resource` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsResource — Resource metadata. Set `service.name` attribute to identify your application.
      - `attributes` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsResourceAttributesItems[] — Key-value attributes identifying the resource.
        - `key` string
        - `value` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsResourceAttributesItemsValue — OTLP typed value. Use `stringValue`, `intValue`, `doubleValue`, `boolValue`, `arrayValue`, or `kvlistValue`.
    - `scopeSpans` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItems[] — Array of instrumentation scope spans.
      - `scope` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsScope — Instrumentation scope (library name and version).
        - `name` string
        - `version` string
      - `spans` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsSpansItems[] — Array of span objects.
        - `traceId` string, required — Hex-encoded trace ID (32 hex chars).
        - `spanId` string, required — Hex-encoded span ID (16 hex chars).
        - `parentSpanId` string — Parent span ID. Empty for root spans.
        - `name` string, required — Span operation name.
        - `startTimeUnixNano` string, required — Start time as nanoseconds since Unix epoch.
        - `endTimeUnixNano` string, required — End time as nanoseconds since Unix epoch.
        - `status` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsSpansItemsStatus — Span status.
          - `code` '1' | '2' — `1` = OK, `2` = ERROR.
          - `message` string — Error description (when code=2).
        - `attributes` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsSpansItemsAttributesItems[] — Span attributes as OTLP key-value pairs. Values use OTLP typed wrappers: `stringValue`, `intValue`, `doubleValue`, `boolValue`, `arrayValue`, or `kvlistValue`. **Trace shape:** use `traceloop.span.kind` (`workflow`, `task`, `tool`, `chat`, etc.) to classify spans, and `traceloop.workflow.name` to make the workflow name searchable. For chat/completion child spans, include `llm.request.type` (`chat` or `completion`) so model, messages, and token fields are promoted. **LLM fields:** `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens`, `gen_ai.usage.total_tokens`, `gen_ai.prompt.{N}.role`, `gen_ai.prompt.{N}.content`, `gen_ai.completion.{N}.role`, `gen_ai.completion.{N}.content`. **Respan fields:** `respan.customer_params.customer_identifier`, `respan.customer_params.email`, `respan.customer_params.name`, `respan.threads.thread_identifier`, `respan.trace.trace_group_identifier`, and `respan.metadata.<key>` for custom metadata. All other attributes are stored in metadata and queryable via metadata filters.
          - `key` string
          - `value` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsSpansItemsAttributesItemsValue
        - `events` ApiV2TracesPostRequestBodyContentApplicationJsonSchemaResourceSpansItemsScopeSpansItemsSpansItemsEventsItems[] — Span events (e.g. exceptions). Each has `name`, `timeUnixNano`, and `attributes`.

## Response `200`

Spans accepted.

- TracesCreateTraceResponse200
  - `partialSuccess` ApiV2TracesPostResponsesContentApplicationJsonSchemaPartialSuccess
    - `rejectedSpans` integer — Number of spans that failed to ingest.
    - `errorMessage` string — Error description (empty on success).

## Other responses

- `400` — Bad Request - Malformed payload.
- `401` — Unauthorized - Invalid or missing API key.

---

[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)