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 1 commit
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
84 changes: 84 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,84 @@
---
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: Re-throttle a running delete by query task

```bash
curl -X POST "localhost:9200/_delete_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=10" -H 'Content-Type: application/json'
Copy link
Collaborator

Choose a reason for hiding this comment

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

Please use Dev Tools format (POST /_delete_by_query/, etc.) without curl

```

### Example request: Re-throttle a running reindex task

```bash
curl -X POST "localhost:9200/_reindex/<YOUR_TASK_ID>/_rethrottle?requests_per_second=20" -H 'Content-Type: application/json'
```

### Example request: Re-throttle a running update by query task

```bash
curl -X POST "localhost:9200/_update_by_query/<YOUR_TASK_ID>/_rethrottle?requests_per_second=5" -H 'Content-Type: application/json'
```

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 52 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": 52, "column": 74}}}, "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 where 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 (e.g., `reindex`). |
| `nodes.<node_id>.tasks.<task_id>.status` | Object | Current status of the task. |
| `nodes.<node_id>.tasks.<task_id>.status.total` | Integer | Total number of documents to process. |
| `nodes.<node_id>.tasks.<task_id>.status.created` | Integer | Number of documents created. |
| `nodes.<node_id>.tasks.<task_id>.status.updated` | Integer | Number of documents updated. |
| `nodes.<node_id>.tasks.<task_id>.status.deleted` | Integer | Number of documents deleted. |
| `nodes.<node_id>.tasks.<task_id>.status.batches` | Integer | Number of batches processed. |
| `nodes.<node_id>.tasks.<task_id>.status.version_conflicts` | Integer | Number of version conflicts. |
| `nodes.<node_id>.tasks.<task_id>.status.noops` | Integer | 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 | Time in milliseconds the task was throttled. |
| `nodes.<node_id>.tasks.<task_id>.status.throttled_until_millis` | Integer | Time in milliseconds 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 | Task start time in epoch milliseconds. |
| `nodes.<node_id>.tasks.<task_id>.running_time_in_nanos` | Integer | Task runtime in nanoseconds. |
| `nodes.<node_id>.tasks.<task_id>.cancellable` | Boolean | Whether the task can be cancelled. |
| `nodes.<node_id>.tasks.<task_id>.cancelled` | Boolean | Whether the task has been cancelled. |
| `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