Throttle a reindex operation Generally available; Added in 2.4.0

POST /_reindex/{task_id}/_rethrottle
Api key auth Basic auth Bearer auth

Change the maximum number of documents to index per second for a particular reindex operation. For example, to unthrottle to unlimited documents per second:

POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1

Rethrottling that speeds up the query takes effect immediately. Rethrottling that slows down the query will take effect after completing the current batch of documents. This behavior prevents scroll timeouts.

This API follows reindex tasks across node-shutdown relocations, so callers can keep using the original task ID throughout the lifetime of the operation. The relocated task ID is also accepted and is followed transparently. In either case, returned task IDs and timings reflect the original task, not its relocated successor.

The rethrottle may not have been applied to any tasks if either node_failures or task_failures are non-empty, or if the response contains no successfully rethrottled tasks — that is, no entries under nodes (returned with the default group_by=nodes in stack) or under tasks (returned in serverless, or in stack with group_by=none or group_by=parents).

Path parameters

  • task_id string Required

    The task identifier, returned when creating a reindex task, or by listing tasks via GET /_reindex or GET /_tasks. In stack, can be either the original task ID or the task ID of the relocated task.

Query parameters

  • requests_per_second number Required

    The maximum number of documents to index per second, across the entire reindex operation (including slices). It can be either -1 to turn off throttling or any decimal number like 1.7 or 12 to throttle to that level.

  • group_by string Generally available

    The way to group the tasks in the response. We recommend setting this to none, which provides the cleanest response format.

    Supported values include:

    • nodes: Group tasks by node ID.
    • parents: Group tasks by parent task ID.
    • none: Do not group tasks.

    Values are nodes, parents, or none.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • node_failures array[object]

      Node-level failures encountered while applying the rethrottle request. Will return a failed_node_exception wrapping a no_such_node_exception, if a node handling the task either never existed, or has left the cluster, and one of the following is true:

      1. The task has completed.
      2. The task cannot be found.

      Note: Rethrottle handles relocations, so it should succeed if the task can be found and has not completed.

      Hide node_failures attributes Show node_failures attributes object

      Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • type string Required

        The type of error

      • reason string | null

        A human-readable explanation of the error, in English.

        One of:
        string-1 string string-2 string | null
      • stack_trace string

        The server stack trace. Present only if the error_trace=true parameter was sent with the request.

      • caused_by object

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • root_cause array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • suppressed array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

    • task_failures array[object]

      Per-task failures encountered while applying the rethrottle. If a rethrottle is attempted during a relocation handoff, the failure object reports status: SERVICE_UNAVAILABLE (the HTTP response itself is still 200 OK). In this case, the request can be retried until success.

      Hide task_failures attributes Show task_failures attributes object
      • task_id number Required
      • node_id string Required
      • status string Required
      • reason object Required

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Hide reason attributes Show reason attributes object
        • type string Required

          The type of error

        • reason string | null

          A human-readable explanation of the error, in English.

          One of:
          string-1 string string-2 string | null
        • stack_trace string

          The server stack trace. Present only if the error_trace=true parameter was sent with the request.

        • caused_by object

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • root_cause array[object]

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • suppressed array[object]

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

    • nodes object Generally available

      Tasks grouped by node, returned only when group_by=nodes (the default).

    • tasks array[object] | object

      The tasks that were successfully rethrottled. Always returned in serverless. Returned with group_by=none or group_by=parents in stack.

      One of:
      array-1 array[object] object-2 object
POST /_reindex/{task_id}/_rethrottle 
POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1

resp = client.reindex_rethrottle(
    task_id="r1A2WoRbTwKZ516z6NEs5A:36619",
    requests_per_second="-1",
)
const response = await client.reindexRethrottle({
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1",
});
response = client.reindex_rethrottle(
  task_id: "r1A2WoRbTwKZ516z6NEs5A:36619",
  requests_per_second: "-1"
)
$resp = $client->reindexRethrottle([
    "task_id" => "r1A2WoRbTwKZ516z6NEs5A:36619",
    "requests_per_second" => "-1",
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1"
client.reindexRethrottle(r -> r
    .requestsPerSecond(-1.0F)
    .taskId("r1A2WoRbTwKZ516z6NEs5A:36619")
);
Response examples (200)
A successful response from `POST _reindex/{task_id}/_rethrottle?requests_per_second=10`. This is the response shape always returned in serverless, and in stack only when `group_by=none`. Task IDs and timings reflect the original task across node-shutdown relocations. 
{
  "tasks": [
    {
      "node": "r1A2WoRbTwKZ516z6NEs5A",
      "id": 36619,
      "type": "transport",
      "action": "indices:data/write/reindex",
      "status": {
        "total": 11500,
        "updated": 0,
        "created": 4000,
        "deleted": 0,
        "batches": 4,
        "version_conflicts": 0,
        "noops": 0,
        "retries": {
          "bulk": 0,
          "search": 0
        },
        "throttled_millis": 0,
        "requests_per_second": 10.0,
        "throttled_until_millis": 0
      },
      "description": "reindex from [my-source-index] to [my-dest-index]",
      "start_time_in_millis": 1762190000000,
      "running_time_in_nanos": 4200000000,
      "cancellable": true,
      "headers": {}
    }
  ]
}
A successful response from `POST _reindex/{task_id}/_rethrottle` when the task ID's node is not in the cluster (for example, the node was shut down without relocation, or the task ID was never valid). The empty `tasks` array and `failed_node_exception` wrapping a `no_such_node_exception` indicate the task is gone. 
{
  "node_failures": [
    {
      "type": "failed_node_exception",
      "reason": "Failed node [non_existing_node]",
      "node_id": "non_existing_node",
      "caused_by": {
        "type": "no_such_node_exception",
        "reason": "No such node [non_existing_node]",
        "node_id": "non_existing_node"
      }
    }
  ],
  "tasks": []
}
While the HTTP status remains `200 OK`, a rethrottle sent during a node-shutdown relocation handoff can return `task_failures` with `status: SERVICE_UNAVAILABLE` and a `status_exception` cause. Retry with the same task ID; the retry follows the relocated task until it succeeds. 
{
  "task_failures": [
    {
      "task_id": 36619,
      "node_id": "r1A2WoRbTwKZ516z6NEs5A",
      "status": "SERVICE_UNAVAILABLE",
      "reason": {
        "type": "status_exception",
        "reason": "cannot rethrottle, task is being relocated"
      }
    }
  ],
  "tasks": {}
}