---
title: "Create trace destination"
method: POST
path: "/v1/trace-destinations"
tags: ["trace_destinations"]
---

# Create trace destination

`POST /v1/trace-destinations`

Send this organization's agent traces to an OpenTelemetry backend it owns.

Every finished agentic search, chat completion, and question-answering run is converted to OTLP spans
and pushed to the destination: the agent's query, the tool calls it made with
their arguments and results, the model turns with their token usage, and the
chunks it returned, which is the same trace the dashboard shows. Mixedbread's own
internal spans are never exported.

`langfuse` destinations take the host and the project key pair; `otlp` takes
a traces endpoint and its auth headers, which covers any OTLP/HTTP collector.
The credentials are checked against the destination before it is stored.

## Request body

- TraceDestinationCreateParams — Parameters for connecting a destination. `langfuse` takes the host and project key pair from the Langfuse project settings; `otlp` takes a traces endpoint and the headers it authenticates with, which covers any OTLP/HTTP collector.
  - `name` string, required — Human-readable name
  - `provider` 'langfuse' | 'otlp' — Destination type
  - `host` string, nullable — Langfuse base URL, e.g. https://cloud.langfuse.com
  - `public_key` string, nullable — Langfuse project public key
  - `secret_key` string, nullable — Langfuse project secret key
  - `endpoint` string, nullable — OTLP/HTTP traces endpoint, for the `otlp` provider
  - `headers` object, nullable — Headers sent with every OTLP request, for the `otlp` provider
  - `event_types` string[] — Which trace kinds to export
  - `enabled` boolean — Whether to start exporting immediately

## Response `201`

The connected trace destination

- TraceDestination — An OTLP endpoint this organization's agent traces are exported to.
  - `id` string, uuid, required — Unique identifier of the destination
  - `name` string, required — Human-readable name
  - `provider` 'langfuse' | 'otlp', required — Destination type
  - `endpoint` string, required — OTLP/HTTP traces endpoint spans are posted to
  - `credential_hint` string, nullable — Non-secret half of the credential: the Langfuse public key, or the auth header name
  - `event_types` string[], required — Which trace kinds are exported to this destination
  - `enabled` boolean, required — Whether traces are currently being exported
  - `last_exported_at` string, date-time, nullable — When a batch last reached the destination
  - `last_error` string, nullable — Why the most recent delivery failed; cleared by the next success
  - `last_error_at` string, date-time, nullable — When the most recent delivery failed
  - `created_at` string, date-time, required — When the destination was created
  - `updated_at` string, date-time, required — When the destination was last updated
  - `object` 'trace_destination' — Type of the object

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-27** `d2ebbe3adcaa` — 1 warning, 1 info
  - added the new `qa` enum value to the `event_types/items/` response property for the response status `201`
  - added the new `qa` enum value to the request property `event_types/items/`
- **2026-08-26** `4ec9b6a07a95` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mixedbread/apis/mxbai-omni/changes/v1/trace-destinations/post.md)

---

[API](https://skmtc.dev/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.dev/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/79d5edfa05e3/schema)