Skip to content

Adding rethrottle api docs #9607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 14, 2025
Merged

Adding rethrottle api docs #9607

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7fe6cde
Adding retrottle api docs
AntonEliatra Apr 14, 2025
c461394
Apply suggestions from code review
AntonEliatra Jun 30, 2025
e430713
addressing PR comments
AntonEliatra Jun 30, 2025
e245865
Apply suggestions from code review
natebower Jul 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 168 additions & 0 deletions _api-reference/tasks/rethrottle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
---
layout: default
title: Rethrottle
parent: Tasks API
nav_order: 40
---

# Rethrottle

Check failure on line 8 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 8, "column": 3}}}, "severity": "ERROR"}

You can use the following APIs to dynamically change the `requests_per_second` for [`_reindex`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/reindex/), [`_update_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/update-by-query/), or [`_delete_by_query`]({{site.url}}{{site.baseurl}}/api-reference/document-apis/delete-by-query/) operations that are already running.

## Endpoints

```json
POST /_delete_by_query/{task_id}/_rethrottle
POST /_reindex/{task_id}/_rethrottle
POST /_update_by_query/{task_id}/_rethrottle
```

## Path parameters

Parameter | Data type | Description
:--- | :--- | :---
`task_id` | String | The unique identifier for the running task that you want to rethrottle.

Check failure on line 24 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 24, "column": 82}}}, "severity": "ERROR"}

## Query parameters

Parameter | Data type | Description
:--- | :--- | :---
`requests_per_second` | Float | The new throttle value to apply to the task. Use `-1` to disable throttling. Optional.

### Example request: Rethrottle a running delete by query task

Check failure on line 32 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 32, "column": 22}}}, "severity": "ERROR"}

```json
POST /_delete_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=10
```
{% include copy-curl.html %}


### Example request: Rethrottle a running reindex task

Check failure on line 40 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 40, "column": 22}}}, "severity": "ERROR"}

```json
POST /_reindex/<YOUR_TASK_ID>/_rethrottle?requests_per_second=20
```
{% include copy-curl.html %}

### Example request: Rethrottle a running update by query task

Check failure on line 47 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Rethrottle. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 47, "column": 22}}}, "severity": "ERROR"}

```json
POST /_update_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=5
```
{% include copy-curl.html %}

## Example response

The following response provides details regarding the active `update_by_query` task:

```
{
"nodes": {
"bvv8SKpiRhOhF9_Bu8gZ7w": {
"name": "opensearch-node1",
"transport_address": "172.18.0.4:9300",
"host": "172.18.0.4",
"ip": "172.18.0.4:9300",
"roles": [
"cluster_manager",
"data",
"ingest",
"remote_cluster_client"
],
"attributes": {
"shard_indexing_pressure_enabled": "true"
},
"tasks": {
"bvv8SKpiRhOhF9_Bu8gZ7w:640": {
"node": "bvv8SKpiRhOhF9_Bu8gZ7w",
"id": 640,
"type": "transport",
"action": "indices:data/write/update/byquery",
"status": {
"total": 4785,
"updated": 1000,
"created": 0,
"deleted": 0,
"batches": 1,
"version_conflicts": 0,
"noops": 0,
"retries": {
"bulk": 0,
"search": 0
},
"throttled_millis": 0,
"requests_per_second": 50,
"throttled_until_millis": 2146
},
"description": "update-by-query [test-rethrottle] updated with Script{type=inline, lang='painless', idOrCode='ctx._source.new_field = 'updated'', options={}, params={}}",
"start_time_in_millis": 1751310547697,
"running_time_in_nanos": 9567425129,
"cancellable": true,
"cancelled": false,
"headers": {
"X-Opaque-Id": "1b911516-44cd-4920-8c1e-79368ea7cdfd"
},
"resource_stats": {
"average": {
"cpu_time_in_nanos": 0,
"memory_in_bytes": 0
},
"total": {
"cpu_time_in_nanos": 0,
"memory_in_bytes": 0
},
"min": {
"cpu_time_in_nanos": 0,
"memory_in_bytes": 0
},
"max": {
"cpu_time_in_nanos": 0,
"memory_in_bytes": 0
},
"thread_info": {
"thread_executions": 0,
"active_threads": 0
}
}
}
}
}
}
}
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add an example response?

## Response body fields

The response provides detailed task- and node-level information about the rethrottled operation.

Check failure on line 136 in _api-reference/tasks/rethrottle.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: rethrottled. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: rethrottled. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_api-reference/tasks/rethrottle.md", "range": {"start": {"line": 136, "column": 75}}}, "severity": "ERROR"}

| Field | Data type | Description |
| :--- | :--- | :--- |
| `nodes` | Object | A map of node IDs to details about the task on each node. |
| `nodes.<node_id>.name` | String | The name of the node on which the task is running. |
| `nodes.<node_id>.transport_address` | String | The transport address of the node. |
| `nodes.<node_id>.host` | String | The host IP address. |
| `nodes.<node_id>.ip` | String | The IP address and port. |
| `nodes.<node_id>.roles` | Array | The roles assigned to the node. |
| `nodes.<node_id>.attributes` | Object | Node-level attributes. |
| `nodes.<node_id>.tasks` | Object | A map of task IDs to detailed information about each task. |
| `nodes.<node_id>.tasks.<task_id>.type` | String | The task type, such as `transport`. |
| `nodes.<node_id>.tasks.<task_id>.action` | String | The specific action being performed (for example, `reindex`). |
| `nodes.<node_id>.tasks.<task_id>.status` | Object | The current status of the task. |
| `nodes.<node_id>.tasks.<task_id>.status.total` | Integer | The total number of documents to process. |
| `nodes.<node_id>.tasks.<task_id>.status.created` | Integer | The number of documents created. |
| `nodes.<node_id>.tasks.<task_id>.status.updated` | Integer | The number of documents updated. |
| `nodes.<node_id>.tasks.<task_id>.status.deleted` | Integer | The number of documents deleted. |
| `nodes.<node_id>.tasks.<task_id>.status.batches` | Integer | The number of batches processed. |
| `nodes.<node_id>.tasks.<task_id>.status.version_conflicts` | Integer | The number of version conflicts. |
| `nodes.<node_id>.tasks.<task_id>.status.noops` | Integer | The number of no-op updates. |
| `nodes.<node_id>.tasks.<task_id>.status.retries` | Object | Retry stats for bulk and search operations. |
| `nodes.<node_id>.tasks.<task_id>.status.requests_per_second` | Float | Current throttle rate in requests per second. |
| `nodes.<node_id>.tasks.<task_id>.status.throttled_millis` | Integer | The time, in milliseconds, that the task was throttled. |
| `nodes.<node_id>.tasks.<task_id>.status.throttled_until_millis` | Integer | The time, in milliseconds, that the task is expected to remain throttled. |
| `nodes.<node_id>.tasks.<task_id>.description` | String | A human-readable description of the task. |
| `nodes.<node_id>.tasks.<task_id>.start_time_in_millis` | Integer | The task start time in epoch milliseconds. |
| `nodes.<node_id>.tasks.<task_id>.running_time_in_nanos` | Integer | The task runtime in nanoseconds. |
| `nodes.<node_id>.tasks.<task_id>.cancellable` | Boolean | Whether the task can be canceled. |
| `nodes.<node_id>.tasks.<task_id>.cancelled` | Boolean | Whether the task has been canceled. |
| `nodes.<node_id>.tasks.<task_id>.headers` | Object | Optional HTTP headers associated with the task. |
| `nodes.<node_id>.tasks.<task_id>.resource_stats` | Object | Statistics about resource usage. |
Loading