+++
title = "Usage, metrics and queries from the CLI"
description = "Read a cluster's usage against its plan, its request metrics and its top search terms."
weight = 119
updated = 2026-11-11

[extra]
nav_title = "Usage, metrics and queries"
weight = 60
+++

Three commands show what a cluster holds and how it's being used. Each takes a cluster's ID or name, or uses `BONSAI_CLUSTER`.

Durations are written like `30m`, `1h`, `24h`, `7d` or `1h30m`. A day is 24 hours.

## Usage

`cluster usage` shows the cluster's documents, shards and disk size against its plan's limits:

```
$ bonsai cluster usage search
Cluster  search
ID       search-nozais
Docs     28,553 / 500,000 (5%)
Shards   2 / 10 (20%)
Size     233.0 MiB / 953.7 MiB (24%)
Polled   just now
```

`--since <D>` sets how far back to look, 90 days at most. The default is `7d`. With `--json` you get the samples over that time.

## Metrics

`cluster metrics` shows request counts, error rates, traffic and latency:

```
$ bonsai cluster metrics search
Cluster    search
ID         search-nozais
Range      last 1h, 1m buckets
Requests   6,281
Writes     811
4xx        2.1%
5xx        0.0%
Bytes in   1.7 MiB
Bytes out  12.6 MiB
p50        28.2 ms typical, 39.6 ms in the slowest 1m
p95        118.9 ms typical, 184.2 ms in the slowest 1m
p99        215.8 ms typical, 451.3 ms in the slowest 1m
```

Latency is shown twice per percentile: the typical bucket (the median), and the slowest bucket in the range.

| Flag | |
|---|---|
| `--since <D>` | How far back to look, 30 days at most. The default is `1h` |
| `--resolution <R>` | The bucket size, such as `1m` or `1h` |

With `--json` you get every bucket, to chart or to alert on.

## Top queries

`cluster queries` shows the search terms your users send most, with how long they take and how many hits they return:

```
$ bonsai cluster queries search --top 5
Top 5 of 28 search terms on search (ID search-nozais) over 7d, computed 47s ago
QUERY       VOLUME  AVG TIME  AVG HITS
size guide  66,360  29.1 ms   703.5
watch       65,856  17.3 ms   944.3
red shoes   63,000  18.2 ms   223.2
sandals     59,976  26.4 ms   814.6
scarf       59,472  24.3 ms   469.9
```

| Flag | |
|---|---|
| `--window <W>` | The window the terms are counted over. The default is `7d` |
| `--top <N>` | Show this many terms. The default is 20, or every term with `--json` |

This needs a token with the `query_logs:read` scope, which new tokens don't have unless you pick it, because search terms are your users' data. Without it, the command exits with code 3 and names the scope. See [Query Logs](@/docs/features/query-logs/index.md) for the same data in the dashboard.

## In scripts

All three print the API's JSON with `--json`. For example, fail a CI job when a cluster is over 80% of its plan's documents:

```bash
bonsai cluster show search --json \
  | jq -e '.stats.docs / .stats.limits.docs < 0.8' > /dev/null
```