Cluster & CAT APIs

Cluster and CAT APIs help you monitor stack health and get quick operational summaries — useful for debugging ingestion issues, uptime checks, and verifying index counts.

Connection details: Connect to Your Cluster.

Cluster API reference: Cluster APIs (opens in a new tab)
CAT API reference: CAT APIs (opens in a new tab)

Common endpoints

Method	Path	Purpose
`GET`	`/_cluster/health`	Cluster health (`green`, `yellow`, `red`)
`GET`	`/_cluster/health/{index}`	Health for specific indexes
`GET`	`/_cluster/stats`	Cluster statistics (nodes, indexes, docs)
`GET`	`/_cat/indices?v`	Index list with doc counts and store size
`GET`	`/_cat/health?v`	One-line cluster health
`GET`	`/_cat/aliases?v`	List aliases
`GET`	`/_cat/nodes?v`	Node summary (fields may be limited on hosted stacks)
`GET`	`/_cat/shards/{index}?v`	Shard allocation per index

Some cluster admin endpoints (/_cluster/settings with persistent changes, reroute, etc.) may be restricted on hosted stacks — see Managed Stack Limitations.

Cluster health

curl -X GET "@opensearch.endpointAddress:443/_cluster/health?pretty" \
  -u "@opensearch.username:@opensearch.password"

Example response fields:

Field	Meaning
`status`	`green` (all primary/replica shards active), `yellow` (replicas unassigned), `red` (primary shards missing)
`number_of_nodes`	Nodes in the cluster
`active_primary_shards`	Primary shards online
`relocating_shards`	Shards currently moving (non-zero during maintenance)

Health for a specific index pattern:

curl -X GET "@opensearch.endpointAddress:443/_cluster/health/filebeat-*?pretty" \
  -u "@opensearch.username:@opensearch.password"

List indexes (CAT)

curl -X GET "@opensearch.endpointAddress:443/_cat/indices?v&s=index" \
  -u "@opensearch.username:@opensearch.password"

Useful columns: index, health, docs.count, store.size, creation.date.string.

Filter with a pattern:

curl -X GET "@opensearch.endpointAddress:443/_cat/indices/filebeat-*?v&h=index,health,docs.count,store.size" \
  -u "@opensearch.username:@opensearch.password"

Monitoring and uptime checks

Use /_cluster/health from an external monitor (cron, Prometheus blackbox probe, etc.) to detect cluster problems.

Simple uptime check — exit code 0 only when status is green or yellow:

STATUS=$(curl -s -u "@opensearch.username:@opensearch.password" \
  "@opensearch.endpointAddress:443/_cluster/health" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
 
if [ "$STATUS" = "red" ]; then
  echo "OpenSearch cluster status: $STATUS"
  exit 1
fi
echo "OpenSearch cluster status: $STATUS"

Python health check for use in scripts or alerting hooks:

health_check.py

import sys
import requests
 
response = requests.get(
    "@opensearch.endpointAddress:443/_cluster/health",
    auth=("@opensearch.username", "@opensearch.password"),
    timeout=10,
)
response.raise_for_status()
status = response.json()["status"]
 
if status == "red":
    print(f"Cluster health is {status}")
    sys.exit(1)
 
print(f"Cluster health is {status}")

Document count spot-check — compare today's index size against expectations:

curl -X POST "@opensearch.endpointAddress:443/filebeat-*/_count" \
  -u "@opensearch.username:@opensearch.password" \
  -H "Content-Type: application/json" \
  -d '{"query": {"range": {"@timestamp": {"gte": "now-1h"}}}}'

Pair with ingestion statistics in the dashboard to confirm data is arriving.

Read cluster stats

Higher-level summary than CAT — node count, total documents, store size:

curl -X GET "@opensearch.endpointAddress:443/_cluster/stats?pretty" \
  -u "@opensearch.username:@opensearch.password"

When to use Dashboards instead

For interactive investigation (Discover, index management UI, stack version), use Launch Logs (OpenSearch Dashboards). Use Cluster and CAT APIs when you need scriptable, automatable checks or quick terminal output.