+++
title = "Working with a cluster's data"
description = "Create indices, load documents and search with bonsai cluster request, which sends a request to the cluster's own API without showing its password."
weight = 120
updated = 2026-11-18

[extra]
nav_title = "Cluster data"
weight = 55
+++

`bonsai cluster request` sends one request to a cluster's own API, Elasticsearch's or OpenSearch's, with the cluster's credential, and prints the cluster's answer. It is how you, a script or an agent creates indices, loads documents and searches without handling the password.

```bash
bonsai cluster request search PUT /products -d @mapping.json
bonsai cluster request search POST /products/_bulk -d @products.ndjson
bonsai cluster request search POST /products/_search -d '{"query": {"match": {"name": "fern"}}}'
bonsai cluster request search GET '/_cat/indices?v'
bonsai cluster request search DELETE /products --confirm products
```

It needs CLI 0.5.0 or newer, and a token with the `credentials:read` [scope](@/docs/api/authentication/index.md#scopes). A token from `bonsai login` has it unless you unchecked it.

## The request

```
bonsai cluster request <cluster> <METHOD> <path>
```

The cluster is an ID or a name, the method is any HTTP method but `TRACE` and `CONNECT`, and the path starts with `/` and can carry a query string. Quote a path with `?` or `*` in it, so the shell leaves it alone.

| Flag | |
|---|---|
| `-d`, `--data <BODY>` | The body: the text itself, `@FILE` to read a file, or `-` to read stdin |
| `-H`, `--header <NAME: VALUE>` | An extra header. Repeatable. `Authorization` is refused: it is the credential's |
| `--credential <ID>` | The credential to send with. The default is the cluster's default credential |
| `--confirm <INDEX>` | The index's name, for a request that deletes one |
| `--timeout <DURATION>` | How long the cluster has to answer. The default is `5m` |

The body is sent as it is. Its `Content-Type` is `application/json`, or `application/x-ndjson` for `_bulk` and `_msearch`, unless you set one with `-H`. Those two endpoints refuse a body that doesn't end with a newline, so the CLI adds one when it is missing.

## The answer

The cluster's answer goes to stdout, whatever its status. Piped or redirected, it is the bytes the cluster sent, so `jq` and your scripts see exactly that. On a terminal, JSON is indented.

When the cluster answers with an error, the body is still printed, a line on stderr says what the cluster said, and the [exit code](@/docs/cli/scripting/index.md#exit-codes) tells a script what happened:

| Code | Meaning |
|---|---|
| 0 | The cluster answered with a status under 400 |
| 1 | Any other error from the cluster, or one reaching it |
| 2 | Usage: a bad flag, or a delete without its confirmation |
| 3 | The cluster answered 401 or 403 |
| 4 | The cluster answered 404 |
| 9 | `--timeout` ran out. The cluster may still apply the request |

An answer larger than 64 MiB is refused instead of read into memory.

## Deleting

Deleting an index, or running `_delete_by_query` on one, removes data for good. On a terminal the CLI asks you to type the index's name. Without one, as in a script or an agent's shell, it needs `--confirm` with that name, and exits 2 before anything is sent when the name is missing or wrong:

```bash
bonsai cluster request search DELETE /products --confirm products
```

A path that could name two different indices, depending on where it is decoded, is refused whatever `--confirm` says. Write the path so that it names the index plainly.

The check covers `DELETE /<index>` and `_delete_by_query`. It doesn't cover every request that can remove data: deleting one document, or removing an index through `POST /_aliases`, goes ahead.

## What is sent again

Only what is safe to repeat: a connection that was never made, and a `429` from the cluster. A `5xx`, a connection that broke, or a timeout after the request left is never sent again, since the cluster may have applied it. Neither is a `429` from `_update_by_query`, `_delete_by_query` or `_reindex`, which can answer it after doing part of their work.

A failure says which it was. "Couldn't reach the cluster" means nothing was sent. A connection that broke afterwards says the cluster may have applied the request, so check before you send a write again.

## The password

The CLI reads the cluster's connection URL for the one request and keeps the password out of everything it prints: stdout, stderr, `-vv` logs and error text. Requests go over https only, and redirects are not followed, so the password can't be sent anywhere else.

This is what makes it safe to give to an agent. The [agent skill](@/docs/cli/agent-skill/index.md) teaches it, so an agent with a shell uses `cluster request` instead of fetching the URL for `curl`. An agent that calls tools has the same thing as [`cluster_request`](@/docs/cli/mcp-server/index.md#data) in `bonsai mcp`.

Bonsai blocks some of Elasticsearch's and OpenSearch's endpoints. See [Unsupported API endpoints](@/docs/platform/unsupported-api-endpoints/index.md).
