Settings Otel

Operations about OpenTelemetry settings

Retrieve the OpenTelemetry configuration

get

/settings/otel

Retrieve the current OpenTelemetry configuration, including every field exposed in the UI. Requires the otel:manage scope.

Authorizations

X-N8N-API-KEYstringRequired

Responses

200

Operation successful.

application/json

The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided. Fields managed declaratively via environment variables are returned with their effective value and ignored on write.

enabledbooleanRequired

Whether OpenTelemetry tracing is enabled.

Example: true

exporterEndpointstring · uriRequired

The base URL of the OTLP collector to export traces to.

Example: http://localhost:4318

exporterTracingPathstringRequired

The path appended to the endpoint for the OTLP traces signal.

Example: /v1/traces

exporterServiceNamestring · min: 1Required

The service.name resource attribute reported on every span.

Example: n8n

exporterHeadersstringRequired

Additional headers sent to the OTLP collector, as a single string of comma-separated key=value pairs (e.g. authorization=Bearer my-token,x-tenant-id=acme). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.

Example: authorization=Bearer my-token,x-tenant-id=acme

tracesSampleRatenumber · max: 1Required

The ratio of traces to sample, between 0 (none) and 1 (all).

Example: 1

startupConnectivityTimeoutMsintegerRequired

How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.

Example: 2000

includeNodeSpansbooleanRequired

Whether to emit a span for each node execution in addition to the workflow span.

Example: true

injectOutboundbooleanRequired

Whether to inject trace context headers into outbound HTTP requests made by nodes.

Example: true

productionExecutionsOnlybooleanRequired

When true, only production executions of published (active) workflows are traced, not manual/test runs.

Example: true

401

Unauthorized

403

Forbidden

get/settings/otel

GET /api/v1/settings/otel HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "enabled": true,
  "exporterEndpoint": "http://localhost:4318",
  "exporterTracingPath": "/v1/traces",
  "exporterServiceName": "n8n",
  "exporterHeaders": "authorization=Bearer my-token,x-tenant-id=acme",
  "tracesSampleRate": 1,
  "startupConnectivityTimeoutMs": 2000,
  "includeNodeSpans": true,
  "injectOutbound": true,
  "productionExecutionsOnly": true
}

Set the OpenTelemetry configuration

put

/settings/otel

Set the OpenTelemetry configuration. This is a full replacement: every field must be provided, and a partial body is rejected. The update takes effect exactly as it would from the UI, using the same validation, and is applied to the running instance immediately. Fields managed declaratively via environment variables are read-only: attempting to change one is rejected with 409, while re-submitting its current value (as returned by GET) is accepted. Requires the otel:manage scope.

Authorizations

X-N8N-API-KEYstringRequired

Body

The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided. Fields managed declaratively via environment variables are returned with their effective value and ignored on write.

enabledbooleanRequired

Whether OpenTelemetry tracing is enabled.

Example: true

exporterEndpointstring · uriRequired

The base URL of the OTLP collector to export traces to.

Example: http://localhost:4318

exporterTracingPathstringRequired

The path appended to the endpoint for the OTLP traces signal.

Example: /v1/traces

exporterServiceNamestring · min: 1Required

The service.name resource attribute reported on every span.

Example: n8n

exporterHeadersstringRequired

Additional headers sent to the OTLP collector, as a single string of comma-separated key=value pairs (e.g. authorization=Bearer my-token,x-tenant-id=acme). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.

Example: authorization=Bearer my-token,x-tenant-id=acme

tracesSampleRatenumber · max: 1Required

The ratio of traces to sample, between 0 (none) and 1 (all).

Example: 1

startupConnectivityTimeoutMsintegerRequired

How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.

Example: 2000

includeNodeSpansbooleanRequired

Whether to emit a span for each node execution in addition to the workflow span.

Example: true

injectOutboundbooleanRequired

Whether to inject trace context headers into outbound HTTP requests made by nodes.

Example: true

productionExecutionsOnlybooleanRequired

When true, only production executions of published (active) workflows are traced, not manual/test runs.

Example: true

Responses

200

Operation successful.

application/json

The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided. Fields managed declaratively via environment variables are returned with their effective value and ignored on write.

enabledbooleanRequired

Whether OpenTelemetry tracing is enabled.

Example: true

exporterEndpointstring · uriRequired

The base URL of the OTLP collector to export traces to.

Example: http://localhost:4318

exporterTracingPathstringRequired

The path appended to the endpoint for the OTLP traces signal.

Example: /v1/traces

exporterServiceNamestring · min: 1Required

The service.name resource attribute reported on every span.

Example: n8n

exporterHeadersstringRequired

Additional headers sent to the OTLP collector, as a single string of comma-separated key=value pairs (e.g. authorization=Bearer my-token,x-tenant-id=acme). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.

Example: authorization=Bearer my-token,x-tenant-id=acme

tracesSampleRatenumber · max: 1Required

The ratio of traces to sample, between 0 (none) and 1 (all).

Example: 1

startupConnectivityTimeoutMsintegerRequired

How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.

Example: 2000

includeNodeSpansbooleanRequired

Whether to emit a span for each node execution in addition to the workflow span.

Example: true

injectOutboundbooleanRequired

Whether to inject trace context headers into outbound HTTP requests made by nodes.

Example: true

productionExecutionsOnlybooleanRequired

When true, only production executions of published (active) workflows are traced, not manual/test runs.

Example: true

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

409

Conflict

put/settings/otel

PUT /api/v1/settings/otel HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 324

{
  "enabled": true,
  "exporterEndpoint": "http://localhost:4318",
  "exporterTracingPath": "/v1/traces",
  "exporterServiceName": "n8n",
  "exporterHeaders": "authorization=Bearer my-token,x-tenant-id=acme",
  "tracesSampleRate": 1,
  "startupConnectivityTimeoutMs": 2000,
  "includeNodeSpans": true,
  "injectOutbound": true,
  "productionExecutionsOnly": true
}

{
  "enabled": true,
  "exporterEndpoint": "http://localhost:4318",
  "exporterTracingPath": "/v1/traces",
  "exporterServiceName": "n8n",
  "exporterHeaders": "authorization=Bearer my-token,x-tenant-id=acme",
  "tracesSampleRate": 1,
  "startupConnectivityTimeoutMs": 2000,
  "includeNodeSpans": true,
  "injectOutbound": true,
  "productionExecutionsOnly": true
}

Test the connection to an OTLP collector

post

/settings/otel/test-trace

Send a single test span to the given OTLP collector and report whether it was accepted. This tests the supplied connection details without changing the stored configuration. Fields managed declaratively via environment variables are overridden with their effective value before the test is sent. Requires the otel:manage scope.

Authorizations

X-N8N-API-KEYstringRequired

Body

The connection details to test against an OTLP collector. Fields managed declaratively via environment variables are overridden with their effective value before the test is sent.

exporterEndpointstring · uriRequired

The base URL of the OTLP collector to export traces to.

Example: http://localhost:4318

exporterTracingPathstringRequired

The path appended to the endpoint for the OTLP traces signal.

Example: /v1/traces

exporterServiceNamestring · min: 1Required

The service.name resource attribute reported on the test span.

Example: n8n

exporterHeadersstringRequired

Additional headers sent to the OTLP collector, as a single string of comma-separated key=value pairs (e.g. authorization=Bearer my-token,x-tenant-id=acme). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.

Example: authorization=Bearer my-token,x-tenant-id=acme

startupConnectivityTimeoutMsintegerRequired

How long, in milliseconds, to wait for the collector to respond.

Example: 2000

Responses

200

Operation successful.

application/json

The outcome of the test connection to the OTLP collector.

successbooleanRequired

Whether the test span was accepted by the collector.

Example: true

errorstringOptional

The error reported by the collector or exporter. Present only when success is false.

Example: Failed to connect: 401 Unauthorized

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

post/settings/otel/test-trace

POST /api/v1/settings/otel/test-trace HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 210

{
  "exporterEndpoint": "http://localhost:4318",
  "exporterTracingPath": "/v1/traces",
  "exporterServiceName": "n8n",
  "exporterHeaders": "authorization=Bearer my-token,x-tenant-id=acme",
  "startupConnectivityTimeoutMs": 2000
}

{
  "success": true,
  "error": "Failed to connect: 401 Unauthorized"
}