> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/settings-otel.md).

# Settings Otel

Operations about OpenTelemetry settings

## Retrieve the OpenTelemetry configuration

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsOtel","description":"Operations about OpenTelemetry settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"otelSettingsPublicDto.generated":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether OpenTelemetry tracing is enabled."},"exporterProtocol":{"type":"string","default":"http/protobuf","description":"The wire protocol used to export spans. Collectors conventionally serve OTLP/HTTP on port 4318 and OTLP/gRPC on port 4317. The endpoint scheme (`http://` or `https://`) controls TLS for both protocols. Optional: a write that omits it selects `http/protobuf`, but an instance that sets this field to another value with an environment variable rejects that write with 409.","enum":["http/protobuf","grpc"]},"exporterEndpoint":{"type":"string","format":"uri","description":"The base URL of the OTLP collector to export traces to. The value must be an `http://` or `https://` URL, because the scheme selects TLS — for gRPC, `https://` uses SSL and `http://` is plaintext."},"exporterTracingPath":{"type":"string","description":"The path appended to the endpoint for the OTLP traces signal. Ignored when `exporterProtocol` is `grpc`, which takes no URL path."},"exporterServiceName":{"type":"string","minLength":1,"description":"The `service.name` resource attribute reported on every span."},"exporterHeaders":{"type":"string","description":"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."},"tracesSampleRate":{"type":"number","description":"The ratio of traces to sample, between 0 (none) and 1 (all).","minimum":0,"maximum":1},"startupConnectivityTimeoutMs":{"type":"integer","description":"How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.","minimum":0},"includeNodeSpans":{"type":"boolean","description":"Whether to emit a span for each node execution in addition to the workflow span."},"emitWorkflowStartSpan":{"type":"boolean","description":"Whether to emit a `workflow.execute.started` span with a duration of 0 ms when each execution or resumed segment starts. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"emitNodeStartSpan":{"type":"boolean","description":"Whether to emit a `node.execute.started` span with a duration of 0 ms when each node span starts. This doubles the number of node spans. Has no effect when `includeNodeSpans` is false. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"injectOutbound":{"type":"boolean","description":"Whether to inject trace context headers into outbound HTTP requests made by nodes."},"productionExecutionsOnly":{"type":"boolean","description":"When true, only production executions of published (active) workflows are traced, not manual/test runs."}},"required":["enabled","exporterProtocol","exporterEndpoint","exporterTracingPath","exporterServiceName","exporterHeaders","tracesSampleRate","startupConnectivityTimeoutMs","includeNodeSpans","emitWorkflowStartSpan","emitNodeStartSpan","injectOutbound","productionExecutionsOnly"],"additionalProperties":false,"description":"The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided, except `exporterProtocol`, which defaults to `http/protobuf` when omitted, and `emitWorkflowStartSpan` and `emitNodeStartSpan`, which default to `false` when omitted. Fields managed declaratively via environment variables are returned with their effective value. A write can repeat these values, but changing them returns 409."}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/otel":{"get":{"operationId":"getOtelSettings","tags":["SettingsOtel"],"summary":"Retrieve the OpenTelemetry configuration","description":"Retrieve the current OpenTelemetry configuration, including every field exposed in the UI. Requires the `otel:manage` scope.","responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/otelSettingsPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}
```

## Set the OpenTelemetry configuration

> Set the OpenTelemetry configuration. This is a full replacement: every field must be provided, and a partial body is rejected. The exceptions are \`exporterProtocol\`, which defaults to \`http/protobuf\` when omitted, and \`emitWorkflowStartSpan\` and \`emitNodeStartSpan\`, which default to \`false\` when omitted. 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsOtel","description":"Operations about OpenTelemetry settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"schemas":{"otelSettingsPublicDto.generated":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether OpenTelemetry tracing is enabled."},"exporterProtocol":{"type":"string","default":"http/protobuf","description":"The wire protocol used to export spans. Collectors conventionally serve OTLP/HTTP on port 4318 and OTLP/gRPC on port 4317. The endpoint scheme (`http://` or `https://`) controls TLS for both protocols. Optional: a write that omits it selects `http/protobuf`, but an instance that sets this field to another value with an environment variable rejects that write with 409.","enum":["http/protobuf","grpc"]},"exporterEndpoint":{"type":"string","format":"uri","description":"The base URL of the OTLP collector to export traces to. The value must be an `http://` or `https://` URL, because the scheme selects TLS — for gRPC, `https://` uses SSL and `http://` is plaintext."},"exporterTracingPath":{"type":"string","description":"The path appended to the endpoint for the OTLP traces signal. Ignored when `exporterProtocol` is `grpc`, which takes no URL path."},"exporterServiceName":{"type":"string","minLength":1,"description":"The `service.name` resource attribute reported on every span."},"exporterHeaders":{"type":"string","description":"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."},"tracesSampleRate":{"type":"number","description":"The ratio of traces to sample, between 0 (none) and 1 (all).","minimum":0,"maximum":1},"startupConnectivityTimeoutMs":{"type":"integer","description":"How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.","minimum":0},"includeNodeSpans":{"type":"boolean","description":"Whether to emit a span for each node execution in addition to the workflow span."},"emitWorkflowStartSpan":{"type":"boolean","description":"Whether to emit a `workflow.execute.started` span with a duration of 0 ms when each execution or resumed segment starts. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"emitNodeStartSpan":{"type":"boolean","description":"Whether to emit a `node.execute.started` span with a duration of 0 ms when each node span starts. This doubles the number of node spans. Has no effect when `includeNodeSpans` is false. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"injectOutbound":{"type":"boolean","description":"Whether to inject trace context headers into outbound HTTP requests made by nodes."},"productionExecutionsOnly":{"type":"boolean","description":"When true, only production executions of published (active) workflows are traced, not manual/test runs."}},"required":["enabled","exporterProtocol","exporterEndpoint","exporterTracingPath","exporterServiceName","exporterHeaders","tracesSampleRate","startupConnectivityTimeoutMs","includeNodeSpans","emitWorkflowStartSpan","emitNodeStartSpan","injectOutbound","productionExecutionsOnly"],"additionalProperties":false,"description":"The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided, except `exporterProtocol`, which defaults to `http/protobuf` when omitted, and `emitWorkflowStartSpan` and `emitNodeStartSpan`, which default to `false` when omitted. Fields managed declaratively via environment variables are returned with their effective value. A write can repeat these values, but changing them returns 409."}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"conflict":{"description":"Conflict"},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/settings/otel":{"put":{"operationId":"updateOtelSettings","tags":["SettingsOtel"],"summary":"Set the OpenTelemetry configuration","description":"Set the OpenTelemetry configuration. This is a full replacement: every field must be provided, and a partial body is rejected. The exceptions are `exporterProtocol`, which defaults to `http/protobuf` when omitted, and `emitWorkflowStartSpan` and `emitNodeStartSpan`, which default to `false` when omitted. 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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether OpenTelemetry tracing is enabled."},"exporterProtocol":{"type":"string","enum":["http/protobuf","grpc"],"default":"http/protobuf","description":"The wire protocol used to export spans. Collectors conventionally serve OTLP/HTTP on port 4318 and OTLP/gRPC on port 4317. The endpoint scheme (`http://` or `https://`) controls TLS for both protocols. Optional: a write that omits it selects `http/protobuf`, but an instance that sets this field to another value with an environment variable rejects that write with 409."},"exporterEndpoint":{"type":"string","format":"uri","pattern":"^https?:\\/\\/","description":"The base URL of the OTLP collector to export traces to. The value must be an `http://` or `https://` URL, because the scheme selects TLS — for gRPC, `https://` uses SSL and `http://` is plaintext."},"exporterTracingPath":{"type":"string","description":"The path appended to the endpoint for the OTLP traces signal. Ignored when `exporterProtocol` is `grpc`, which takes no URL path."},"exporterServiceName":{"type":"string","minLength":1,"description":"The `service.name` resource attribute reported on every span."},"exporterHeaders":{"type":"string","description":"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."},"tracesSampleRate":{"type":"number","minimum":0,"maximum":1,"description":"The ratio of traces to sample, between 0 (none) and 1 (all)."},"startupConnectivityTimeoutMs":{"type":"integer","description":"How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.","minimum":0},"includeNodeSpans":{"type":"boolean","description":"Whether to emit a span for each node execution in addition to the workflow span."},"emitWorkflowStartSpan":{"type":"boolean","default":false,"description":"Whether to emit a `workflow.execute.started` span with a duration of 0 ms when each execution or resumed segment starts. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"emitNodeStartSpan":{"type":"boolean","default":false,"description":"Whether to emit a `node.execute.started` span with a duration of 0 ms when each node span starts. This doubles the number of node spans. Has no effect when `includeNodeSpans` is false. Optional: a write that omits it selects `false`, but an instance that sets this field to `true` with an environment variable rejects that write with 409."},"injectOutbound":{"type":"boolean","description":"Whether to inject trace context headers into outbound HTTP requests made by nodes."},"productionExecutionsOnly":{"type":"boolean","description":"When true, only production executions of published (active) workflows are traced, not manual/test runs."}},"required":["enabled","exporterEndpoint","exporterTracingPath","exporterServiceName","exporterHeaders","tracesSampleRate","startupConnectivityTimeoutMs","includeNodeSpans","injectOutbound","productionExecutionsOnly"],"additionalProperties":false,"description":"The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided, except `exporterProtocol`, which defaults to `http/protobuf` when omitted, and `emitWorkflowStartSpan` and `emitNodeStartSpan`, which default to `false` when omitted. Fields managed declaratively via environment variables are returned with their effective value. A write can repeat these values, but changing them returns 409."}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/otelSettingsPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```

## Test the connection to an OTLP collector

> 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsOtel","description":"Operations about OpenTelemetry settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{"CookieAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"CookieAuth":{"type":"apiKey","in":"cookie","name":"n8n-auth"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"unsupportedMediaType":{"description":"Unsupported media type."}}},"paths":{"/settings/otel/test-trace":{"post":{"operationId":"testOtelTrace","tags":["SettingsOtel"],"summary":"Test the connection to an OTLP collector","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exporterProtocol":{"type":"string","enum":["http/protobuf","grpc"],"default":"http/protobuf","description":"The wire protocol used to send the test span. Collectors conventionally serve OTLP/HTTP on port 4318 and OTLP/gRPC on port 4317. The endpoint scheme (`http://` or `https://`) controls TLS for both protocols. Optional: omitting it selects `http/protobuf`, unless an environment variable manages this field, which then supplies the value."},"exporterEndpoint":{"type":"string","format":"uri","pattern":"^https?:\\/\\/","description":"The base URL of the OTLP collector to export traces to. The value must be an `http://` or `https://` URL, because the scheme selects TLS — for gRPC, `https://` uses SSL and `http://` is plaintext."},"exporterTracingPath":{"type":"string","description":"The path appended to the endpoint for the OTLP traces signal. Ignored when `exporterProtocol` is `grpc`, which takes no URL path."},"exporterServiceName":{"type":"string","minLength":1,"description":"The `service.name` resource attribute reported on the test span."},"exporterHeaders":{"type":"string","description":"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."},"startupConnectivityTimeoutMs":{"type":"integer","minimum":0,"description":"How long, in milliseconds, to wait for the collector to respond."}},"required":["exporterEndpoint","exporterTracingPath","exporterServiceName","exporterHeaders","startupConnectivityTimeoutMs"],"additionalProperties":false,"description":"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."}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the test span was accepted by the collector."},"error":{"type":"string","description":"The error reported by the collector or exporter. Present only when `success` is false."}},"required":["success"],"additionalProperties":false,"description":"The outcome of the test connection to the OTLP collector."}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"415":{"$ref":"#/components/responses/unsupportedMediaType"}}}}}}
```