Add a Trace Destination
/v1/traces/destinationsOverview
Requires an owner, admin or developer session; API keys are rejected. Only an owner or admin can turn on include_content. A workspace can have at most 10 destinations.
The endpoint must be a public https URL on port 443, 4318 or 8443, with no credentials in it. A webhook destination is given a signing secret, returned once in signing_secret. A Langfuse destination is named by its host only, such as https://cloud.langfuse.com, and authenticates with its public and secret keys. Headers, keys and the signing secret are stored encrypted. See the Trace Export guide (/docs/trace-export).
Request Body
workspace_idstringRequirednamestringRequiredkindstringRequiredValues: "webhook""otlp""langfuse"
endpointstringRequiredA public https URL on port 443, 4318 or 8443. For Langfuse, the host only.
encodingstringprotobuf is for OTLP only.
Values: "json""protobuf"
Default: "json"
headersobjectSent with every delivery, such as an API key header. Stored encrypted. Not for Langfuse; framing headers and audiolab-* names are refused.
public_keystringLangfuse public key (pk-lf-…). Langfuse only, and required.
secret_keystringLangfuse secret key (sk-lf-…). Langfuse only, and required.
sample_ratenumberDefault: 1
· Maximum 1
productsstring[]Default: []
Show nested fields
A product, as request logs, exports and trace destinations filter by it.
include_contentbooleanOwners and admins only.
Default: false
enabledbooleanDefault: true
Responses
201The destination. A webhook's signing secret is returned once.
idstringRequiredtrd_ followed by 22 characters.
Example: "trd_example"
objectstringRequiredValues: "trace_destination"
workspace_idstringRequiredExample: "ws_example"
namestringRequiredExample: "Honeycomb"
kindstringRequiredwebhook: signed JSON. otlp: OTLP/HTTP traces. langfuse: Langfuse's ingestion API.
Values: "webhook""otlp""langfuse"
Example: "otlp"
endpointstringRequiredThe URL traces are sent to; for Langfuse, its host.
Example: "https://api.honeycomb.io/v1/traces"
encodingstringRequiredOTLP body encoding; json for other kinds.
Values: "json""protobuf"
Example: "protobuf"
header_namesstring[]RequiredNames of the saved headers. Values are never returned.
Show nested fields
string
secret_hintstring | nullRequiredLast four characters of a webhook signing secret or Langfuse public key.
sample_ratenumberRequiredShare of requests sent. Sampling is per request, or per session_id when one is sent.
· Maximum 1
productsstring[]RequiredProducts traced; empty means all.
Show nested fields
A product, as request logs, exports and trace destinations filter by it.
include_contentbooleanRequiredAlso send LLM prompts and outputs as text. Never applied under zero data retention.
enabledbooleanRequiredcreated_atstringRequiredupdated_atstringRequiredlast_deliveryobjectRequiredShow nested fields
statusstring | nullRequiredThe most recent batch's outcome; null before the first.
Values: "delivered""retrying""dead"null
status_codeinteger | nullRequiredHTTP status the destination answered with.
Example: 200
errorstring | nullRequiredExample: null
attempted_atstring | nullRequireddelivered_atstring | nullRequiredThe last successful delivery.
pendingintegerRequiredTraces waiting to be delivered or retried.
deadintegerRequiredTraces that could not be delivered, kept for 7 days.
signing_secretstringA webhook's signing secret (whsec_…), returned only when created or rotated.
400Request validation failed.
errorobjectRequiredShow nested fields
codestringRequiredmessagestringRequiredparamstring | nullrequest_idstring | nullmetadataobjectTyped detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.
401Authentication is missing or invalid.
errorobjectRequiredShow nested fields
codestringRequiredmessagestringRequiredparamstring | nullrequest_idstring | nullmetadataobjectTyped detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.
403Authenticated principal lacks permission.
errorobjectRequiredShow nested fields
codestringRequiredmessagestringRequiredparamstring | nullrequest_idstring | nullmetadataobjectTyped detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.
409Request conflicts with current resource state.
errorobjectRequiredShow nested fields
codestringRequiredmessagestringRequiredparamstring | nullrequest_idstring | nullmetadataobjectTyped detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.
500Internal server error.
errorobjectRequiredShow nested fields
codestringRequiredmessagestringRequiredparamstring | nullrequest_idstring | nullmetadataobjectTyped detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.