---
type: api
title: Simulate a pipeline
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-ingest-simulate
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-ingest-simulate
products:
  - Elasticsearch
---

# Simulate a pipeline


Availability: 5.0+

## Paths

- `POST` (also `GET`) `/_ingest/pipeline/{id}/_simulate`
- `POST` (also `GET`) `/_ingest/pipeline/_simulate`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth)

#### Path Parameters

- `id` (string Id) — optional, leave it out to use `/_ingest/pipeline/_simulate`
  The pipeline to test.
If you don't specify a `pipeline` in the request body, this parameter is required.

## Description

Run an ingest pipeline against a set of provided documents.
You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.

## Required authorization

* Cluster privileges: `read_pipeline`

## Query String Parameters

- `verbose` (boolean · default: false)
  If `true`, the response includes output data for each processor in the executed pipeline.

## Request Body

`application/json`

- `docs` ([] Document) — required
  Sample documents to test in the pipeline.
  - `_id` (string Id) — optional
    Unique identifier for the document.
This ID must be unique within the `_index`.
  - `_index` (string IndexName) — optional
    Name of the index containing the document.
  - `_source` (object) — required
    JSON body for the document.
- `pipeline` ({} Pipeline) — optional
  The pipeline to test.
If you don't specify the `pipeline` request path parameter, this parameter is required.
If you specify both this and the request path parameter, the API only uses the request path parameter.
  - `description` (string) — optional
    Description of the ingest pipeline.
  - `on_failure` ([] {} ProcessorContainer) — optional
    Processors to run immediately after a processor failure.
    See [ProcessorContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/types/ingest-_types-processorcontainer)
  - `processors` ([] {} ProcessorContainer) — optional
    Processors used to perform transformations on documents before indexing.
Processors run sequentially in the order specified.
    See [ProcessorContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/types/ingest-_types-processorcontainer)
  - `version` (number VersionNumber) — optional
    Version number used by external systems to track ingest pipelines.
  - `deprecated` (boolean · default: false) — optional
    Marks this ingest pipeline as deprecated.
When a deprecated ingest pipeline is referenced as the default or final pipeline when creating or updating a non-deprecated index template, Elasticsearch will emit a deprecation warning.
  - `_meta` (Metadata) — optional
    Arbitrary metadata about the ingest pipeline. This map is not automatically generated by Elasticsearch.

## Response

`application/json`

- `docs` ([] SimulateDocumentResult)
  - `doc` ({} DocumentSimulation)
    - `_id` (string Id)
      Unique identifier for the document. This ID must be unique within the `_index`.
    - `_index` (string IndexName)
      Name of the index containing the document.
    - `_ingest` ({} Ingest)
      - `_redact` ({} Redact)
        - `_is_redacted` (boolean)
          indicates if document has been redacted
      - `timestamp` (DateTime)
      - `pipeline` (string Name)
    - `_routing` (string)
      Value used to send the document to a specific primary shard.
    - `_source` (map string to object)
      JSON body for the document.
    - `_version` (StringifiedVersionNumber)
    - `_version_type` (enum VersionType)
      

Supported values include:
  - `internal`: Use internal versioning that starts at 1 and increments with each update or delete.
  - `external`: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
  - `external_gte`: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document.
NOTE: The `external_gte` version type is meant for special use cases and should be used with care.
If used incorrectly, it can result in loss of data.
      Values: `internal`, `external`, `external_gte`
  - `error` ({} ErrorCause)
    - `type` (string)
      The type of error
    - `reason` (union string) — nullable
      A human-readable explanation of the error, in English.
      One of: `string`
    - `stack_trace` (string)
      The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
    - `caused_by` ({} ErrorCause) — recursive
      Same fields as `error` in `docs`
    - `root_cause` ([] ErrorCause) — recursive
      Same fields as `error` in `docs`
    - `suppressed` ([] ErrorCause) — recursive
      Same fields as `error` in `docs`
  - `processor_results` ([] PipelineProcessorResult)
    - `doc` ({} DocumentSimulation)
      Same fields as `doc` in `docs`
    - `tag` (string)
    - `processor_type` (string)
    - `status` (enum PipelineSimulationStatusOptions)
      Values: `success`, `error`, `error_ignored`, `skipped`, `dropped`
    - `description` (string)
    - `ignored_error` ({} ErrorCause)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` ({} ErrorCause) — recursive
        Same fields as `ignored_error` in `processor_results`
      - `root_cause` ([] ErrorCause) — recursive
        Same fields as `ignored_error` in `processor_results`
      - `suppressed` ([] ErrorCause) — recursive
        Same fields as `ignored_error` in `processor_results`
    - `error` ({} ErrorCause)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` ({} ErrorCause) — recursive
        Same fields as `error` in `processor_results`
      - `root_cause` ([] ErrorCause) — recursive
        Same fields as `error` in `processor_results`
      - `suppressed` ([] ErrorCause) — recursive
        Same fields as `error` in `processor_results`
## Code Examples

#### Console

```console
POST /_ingest/pipeline/_simulate
{
  "pipeline" :
  {
    "description": "_description",
    "processors": [
      {
        "set" : {
          "field" : "field2",
          "value" : "_value"
        }
      }
    ]
  },
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}
```

#### JavaScript

```javascript
const response = await client.ingest.simulate({
  pipeline: {
    description: "_description",
    processors: [
      {
        set: {
          field: "field2",
          value: "_value",
        },
      },
    ],
  },
  docs: [
    {
      _index: "index",
      _id: "id",
      _source: {
        foo: "bar",
      },
    },
    {
      _index: "index",
      _id: "id",
      _source: {
        foo: "rab",
      },
    },
  ],
});
```

#### Python

```python
resp = client.ingest.simulate(
    pipeline={
        "description": "_description",
        "processors": [
            {
                "set": {
                    "field": "field2",
                    "value": "_value"
                }
            }
        ]
    },
    docs=[
        {
            "_index": "index",
            "_id": "id",
            "_source": {
                "foo": "bar"
            }
        },
        {
            "_index": "index",
            "_id": "id",
            "_source": {
                "foo": "rab"
            }
        }
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_ingest/pipeline/_simulate" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "description": "_description",
      "processors": [
        {
          "set": {
            "field": "field2",
            "value": "_value"
          }
        }
      ]
    },
    "docs": [
      {
        "_index": "index",
        "_id": "id",
        "_source": {
          "foo": "bar"
        }
      },
      {
        "_index": "index",
        "_id": "id",
        "_source": {
          "foo": "rab"
        }
      }
    ]
  }'
```

#### Java

```java
client.ingest().simulate(s -> s
    .docs(List.of(Document.of(d -> d
            .id("id")
            .index("index")
            .source(JsonData.fromJson("{\"foo\":\"bar\"}"))),Document.of(d -> d
            .id("id")
            .index("index")
            .source(JsonData.fromJson("{\"foo\":\"rab\"}")))))
    .pipeline(p -> p
        .description("_description")
        .processors(pr -> pr
            .set(se -> se
                .field("field2")
                .value(JsonData.fromJson("\"_value\""))
            )
        )
    )
);
```

#### C#

```c#
var response = await client.Ingest
    .SimulateAsync(d1 => d1
        .Docs(d2 => d2
            .Id("id")
            .Index("index")
            .Source(JsonSerializer.Deserialize<JsonElement>("""
            {
              "foo": "bar"
            }
            """)), d2 => d2
            .Id("id")
            .Index("index")
            .Source(JsonSerializer.Deserialize<JsonElement>("""
            {
              "foo": "rab"
            }
            """))
        )
        .Pipeline(d2 => d2
            .Description("_description")
            .Processors(d3 => d3
                .Set(d4 => d4
                    .Field(x => x.Field2)
                    .Value("_value")
                )
            )
        )
    );
```

#### PHP

```php
$resp = $client->ingest()->simulate([
    "body" => [
        "pipeline" => [
            "description" => "_description",
            "processors" => array(
                [
                    "set" => [
                        "field" => "field2",
                        "value" => "_value",
                    ],
                ],
            ),
        ],
        "docs" => array(
            [
                "_index" => "index",
                "_id" => "id",
                "_source" => [
                    "foo" => "bar",
                ],
            ],
            [
                "_index" => "index",
                "_id" => "id",
                "_source" => [
                    "foo" => "rab",
                ],
            ],
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.ingest.simulate(
  body: {
    "pipeline": {
      "description": "_description",
      "processors": [
        {
          "set": {
            "field": "field2",
            "value": "_value"
          }
        }
      ]
    },
    "docs": [
      {
        "_index": "index",
        "_id": "id",
        "_source": {
          "foo": "bar"
        }
      },
      {
        "_index": "index",
        "_id": "id",
        "_source": {
          "foo": "rab"
        }
      }
    ]
  }
)
```

## Response Examples

#### Simulate pipeline response example1

A successful response for running an ingest pipeline against a set of provided documents.

```json
{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_version": "-3",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}
```