> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# LangWatch + n8n Integration

> Complete LangWatch integration for n8n workflows with observability, evaluation, and prompt management

[YouTube video player](https://www.youtube.com/embed/SViNC7FWHMU)

Integrate LangWatch with your n8n workflows to get LLM observability, evaluation, and prompt management. The integration provides automatic workflow instrumentation and a set of LangWatch nodes you add to a workflow.

> [card] [LangWatch Nodes](#langwatch-nodes)
>
> Add LangWatch nodes to your workflows for evaluation, prompts, and datasets

> [card] [Workflow Observability](#workflow-observability)
>
> Automatically trace your n8n workflows with OpenTelemetry instrumentation

## Quick Start

**1. Get your LangWatch API Key**

Sign up at [app.langwatch.ai](https://app.langwatch.ai) and get your API key from the project settings.

**2. Install LangWatch Nodes**

> [tab] Local n8n instance
>
> For installing with a local n8n instance:
>
> ```bash theme={null}
> cd ~/.n8n/nodes
>
> npm i @langwatch/n8n-observability @langwatch/n8n-nodes-langwatch
>
> export EXTERNAL_HOOK_FILES=$(node -e "console.log(require.resolve('@langwatch/n8n-observability/hooks'))")
> export N8N_OTEL_SERVICE_NAME=my-n8n-instance-name
> export LANGWATCH_API_KEY=sk-lw-...
> ```

> [tab] Docker
>
> For installing with Docker, please refer to the [n8n documentation](https://docs.n8n.io/integrations/community-nodes/installation/manual-install/).

> [tab] n8n Cloud
>
> To install the LangWatch nodes in n8n Cloud, you will need to wait until they are
> verified by n8n and available as community nodes.

**3. Set up Credentials**

In n8n, go to Settings → Credentials → New → LangWatch API and add your API key.

**4. Start Building**

Add LangWatch nodes to your workflows.

## LangWatch Nodes

The LangWatch n8n nodes cover evaluation, prompt management, and dataset processing.

### Available Nodes

> [card] [Dataset Batch Trigger](#dataset-batch-trigger)
>
> Process dataset rows sequentially with experiment context

> [card] [Dataset Row Trigger](#dataset-row-trigger)
>
> Fetch single dataset rows with cursor management

> [card] [Evaluation](#evaluation-node)
>
> Run evaluators and record results with multiple modes

> [card] [Prompt](#prompt-node)
>
> Retrieve and compile prompts from LangWatch Prompt Manager

### Node Types

**Triggers:**

* **Dataset Batch Trigger**: Emits one item per dataset row sequentially
* **Dataset Row Trigger**: Fetches single dataset rows with cursor management

**Actions:**

* **Evaluation**: Runs evaluators and records results with multiple operation modes
* **Prompt**: Retrieves and compiles prompts from LangWatch Prompt Manager

### Dataset Batch Trigger

Process your datasets row by row with full experiment context for batch evaluations.

![Dataset Batch Trigger node configuration](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/trigger-dataset-row.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=679602722b0be458a3d8944503bd487f)

**Key Features:**

* Sequential row processing with progress tracking
* Experiment context initialization for batch evaluations
* Flexible row selection (start/end, step size, limits)
* Shuffle support with seed for randomized processing

**Configuration Options:**

* **Dataset**: Slug or ID of your LangWatch dataset
* **Experiment**: Enable experiment tracking with ID/name
* **Row Processing**: Configure start row, end row, step size, and limits

**Output Fields:**

* `entry` - Your dataset row payload
* `row_number`, `row_id`, `datasetId`, `projectId` - Row metadata
* `_progress` - Processing progress information
* `_langwatch.dataset` - Dataset context
* `_langwatch.experiment` - Experiment context (when enabled)

### Dataset Row Trigger

Fetch individual dataset rows with internal cursor management for stepwise processing.

![Dataset Row Trigger node configuration](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/trigger-dataset-row.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=679602722b0be458a3d8944503bd487f)

**Key Features:**

* Single row processing per execution
* Internal cursor management
* Reset progress capability
* Shuffle rows with seed support

**Use Cases:**

* Scheduled dataset processing
* Step-by-step evaluation workflows
* Incremental data processing

### Evaluation Node

Run evaluators and record results with multiple operation modes for comprehensive evaluation workflows.

![Evaluation node configuration showing auto mode](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/node-evaluation-auto.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=a4cd7cd1e47e4e3bcd1cdf77ace7cc4f)

**Operation Modes:**

> [tab] Auto (Recommended)
>
> Automatically selects behavior based on available inputs and context.

> [tab] Check If Evaluating
>
> Determines if the workflow is running in an evaluation context.

> [tab] Record Result
>
> Log a pre-computed evaluation result to LangWatch.

> [tab] Run and Record
>
> Execute an evaluator and automatically record the results.

> [tab] Set Outputs (Dataset)
>
> Write llm input and output back to a dataset for future use.

**Key Parameters:**

* **Run ID**: Override or infer from `_langwatch.batch.runId`
* **Evaluator**: Manual selection or dropdown of available evaluators
* **Evaluation Data**: Input data for the evaluation
* **Guardrail Settings**: Configure `asGuardrail` and `failOnFail` options
* **Dataset Output**: Map results to dataset fields

### Prompt Node

Retrieve and compile prompts from LangWatch Prompt Manager with variable substitution.

![Prompt node configuration interface](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/node-prompt.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=30cf94c666339bf0a5d7a2d7c8eb813f)

**Key Features:**

* Prompt selection by handle or ID
* Version control (latest or specific version)
* Variable compilation with multiple sources
* Strict compilation mode for missing variables

**Variable Sources:**

> [tab] Manual Variables
>
> Define name/value pairs directly in the node configuration.

> [tab] Input Data Variables
>
> Map template variables to input data paths from previous nodes.

> [tab] Mixed Mode
>
> Combine manual variables with input data mapping for maximum flexibility.

**Configuration Options:**

* **Prompt Selection**: Manual (handle/ID) or dropdown selection
* **Version**: Latest or specific version
* **Compile Prompt**: Enable/disable variable substitution
* **Strict Compilation**: Fail if required variables are missing

## Workflow Observability

Automatically instrument your n8n workflows with OpenTelemetry to capture comprehensive observability data.

![n8n observability setup showing workflow instrumentation](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/observability.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=a779672b697329211f4d05b0b27d0416)

> [!NOTE]
>
> Workflow observability is only available for self-hosted n8n instances, not n8n Cloud.

### Features

* **Automatic Workflow Tracing**: Capture complete workflow execution with spans for each node
* **Error Tracking**: Automatic error capture and metadata collection
* **I/O Capture**: Safe JSON input/output capture (toggleable)
* **Node Filtering**: Include/exclude specific nodes from tracing
* **Flexible Deployment**: Works with Docker, bare metal, or programmatic setup

### Setup Options

> [tab] Docker - Custom Image
>
> Create a custom n8n image with LangWatch observability pre-installed.
>
> ```dockerfile theme={null}
> FROM n8nio/n8n:latest
> USER root
> WORKDIR /usr/local/lib/node_modules/n8n
> RUN npm install @langwatch/n8n-observability
> ENV EXTERNAL_HOOK_FILES=/usr/local/lib/node_modules/n8n/node_modules/@langwatch/n8n-observability/dist/hooks.cjs
> USER node
> ```
>
> ```bash theme={null}
> docker build -t my-n8n-langwatch .
> docker run -p 5678:5678 \
>   -e LANGWATCH_API_KEY=your_api_key \
>   -e N8N_OTEL_SERVICE_NAME=my-n8n \
>   my-n8n-langwatch
> ```

> [tab] Docker - Volume Mount
>
> Mount the observability hooks without building a custom image.
>
> ```yaml theme={null}
> # docker-compose.yml
> services:
>   n8n:
>     image: n8nio/n8n:latest
>     environment:
>       - LANGWATCH_API_KEY=${LANGWATCH_API_KEY}
>       - N8N_OTEL_SERVICE_NAME=my-n8n
>       - EXTERNAL_HOOK_FILES=/data/langwatch-hooks.cjs
>     volumes:
>       - ./node_modules/@langwatch/n8n-observability/dist/hooks.cjs:/data/langwatch-hooks.cjs:ro
>       - n8n_data:/home/node/.n8n
>     ports:
>       - "5678:5678"
> volumes:
>   n8n_data:
> ```

> [tab] Bare Metal
>
> Install globally and configure environment variables.
>
> ```bash theme={null}
> mkdir -p ~/.n8n/nodes
> cd ~/.n8n/nodes
> npm i @langwatch/n8n-observability
>
> export LANGWATCH_API_KEY=your_api_key
> export N8N_OTEL_SERVICE_NAME=my-n8n
> export EXTERNAL_HOOK_FILES=$(node -e "console.log(require.resolve('@langwatch/n8n-observability/hooks'))")
>
> n8n start
> ```

> [tab] Programmatic
>
> Initialize observability in your custom n8n setup.
>
> ```typescript theme={null}
> import { setupN8nObservability } from '@langwatch/n8n-observability';
>
> await setupN8nObservability({
>   serviceName: process.env.N8N_OTEL_SERVICE_NAME ?? 'n8n',
>   debug: process.env.N8N_OTEL_DEBUG === '1',
> });
> ```

### Configuration

**LANGWATCH\_API\_KEY** `string` *required*

Your LangWatch API key. Get this from your LangWatch project settings.

**N8N\_OTEL\_SERVICE\_NAME** `string` (default: n8n)

Service name for your n8n instance in LangWatch.

**N8N\_OTEL\_NODE\_INCLUDE** `string`

Comma-separated list of node names/types to include in tracing. If not set, all nodes are traced.

**N8N\_OTEL\_NODE\_EXCLUDE** `string`

Comma-separated list of node names/types to exclude from tracing.

**N8N\_OTEL\_CAPTURE\_INPUT** `boolean` (default: true)

Whether to capture node input data. Set to `false` to disable.

**N8N\_OTEL\_CAPTURE\_OUTPUT** `boolean` (default: true)

Whether to capture node output data. Set to `false` to disable.

**LW\_DEBUG** `boolean` (default: false)

Enable LangWatch SDK debug logging.

**N8N\_OTEL\_DEBUG** `boolean` (default: false)

Enable observability hook debugging and diagnostics.

### Verification

Verify your observability setup is working:

```bash theme={null}
node -e "console.log(require.resolve('@langwatch/n8n-observability/hooks'))"
```

Look for this startup message:

```text theme={null}
[@langwatch/n8n-observability] observability ready and patches applied
```

## Complete Integration Example

Here's how to combine both LangWatch nodes and observability for a comprehensive evaluation workflow:

![Complete n8n workflow with LangWatch nodes and observability](https://mintcdn.com/langwatch/bkDi2jeP3Lppp9Q0/images/integration/n8n/cover.webp?fit=max\&auto=format\&n=bkDi2jeP3Lppp9Q0\&q=85\&s=c1c76a3480d220882bb8d404f5e56654)

**Workflow Steps:**

1. **Dataset Batch Trigger** - Process evaluation dataset
2. **Prompt Node** - Retrieve and compile prompts with variables
3. **HTTP Request** - Call your LLM API
4. **Evaluation Node** - Run evaluators and record results
5. **Observability** - Automatic tracing of all steps

## LangWatch Concepts

> [!NOTE]
>
> For a complete understanding of LangWatch concepts like traces, spans, threads, and user IDs, see
> our [Concepts Guide](https://langwatch.ai/docs/concepts.md).

Key concepts for n8n integration:

* **Traces**: Each n8n workflow execution becomes a trace in LangWatch
* **Spans**: Individual nodes within a workflow become spans
* **Threads**: Group related workflow executions using `thread_id`
* **User ID**: Track which user triggered the workflow
* **Labels**: Tag workflows for organization and filtering

## Troubleshooting

> [accordion] Nodes not appearing in n8n
>
> * Ensure the package is installed: `npm list @langwatch/n8n-nodes-langwatch` - Restart
>   n8n after installation - Check n8n logs for any loading errors

> [accordion] Observability not working
>
> * Verify environment variables are set correctly - Check that the hook file path is correct - Look
>   for the startup message in n8n logs - Ensure you're using self-hosted n8n (not n8n Cloud)

> [accordion] Credentials not working
>
> * Verify your API key is correct in LangWatch dashboard - Check the endpoint URL (should be
>   `https://app.langwatch.ai` for cloud) - Test the connection in the credential settings

> [accordion] No traces appearing in LangWatch
>
> * Check that workflows are actually executing - Verify the service name in LangWatch
>   matches your configuration - Look for any error messages in n8n logs - Ensure your
>   LangWatch project is active

## Resources

* [LangWatch Documentation](https://langwatch.ai/docs/)
* [n8n Community Nodes Guide](https://docs.n8n.io/integrations/community-nodes/)
* [LangWatch n8n Nodes Repository](https://github.com/langwatch/n8n-nodes-langwatch)
* [LangWatch n8n Observability Repository](https://github.com/langwatch/n8n-observability)
* [LangWatch Datasets Guide](https://langwatch.ai/docs/datasets/overview.md)
* [LangWatch Prompt Management](https://langwatch.ai/docs/prompt-management/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.