{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/shards",
  "title": "Shard requests",
  "url": "https://redis.io/docs/latest/operate/rs/8.0/references/rest-api/requests/shards/",
  "summary": "REST API requests for database shards",
  "content": "\n| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-all-shards) | `/v1/shards` | Get all shards |\n| [GET](#get-shard) | `/v1/shards/{uid}` | Get a specific shard |\n\n## Get all shards {#get-all-shards}\n\n\tGET /v1/shards\n\nGet information about all shards in the cluster.\n\n### Request {#get-all-request} \n\n#### Example HTTP request\n\n\tGET /v1/shards?extra_info_keys=used_memory_rss\u0026extra_info_keys=connected_clients\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Query parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| extra_info_keys | list of strings | An optional list of extra keys to be fetched from the Redis [`INFO`](https://redis.io/docs/latest/commands/info) command. See [extra_info_keys](#extra_info_keys) for common keys to include. |\n\n### Response {#get-all-response} \n\nReturns a JSON array of [shard objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/shard).\n\n#### Example JSON body\n\n```json\n[\n  {\n    \"uid\": \"1\",\n    \"role\": \"master\",\n    \"assigned_slots\": \"0-16383\",\n    \"bdb_uid\": 1,\n    \"detailed_status\": \"ok\",\n    \"loading\": {\n      \"status\": \"idle\"\n    },\n    \"node_uid\": \"1\",\n    \"redis_info\": {\n\t\t\t\"connected_clients\": 14,\n\t\t\t\"used_memory_rss\": 12263424\n\t\t},\n    \"report_timestamp\": \"2024-06-28T18:44:01Z\",\n    \"status\": \"active\"\n  },\n  {\n    \"uid\": \"2\",\n    \"role\": \"slave\",\n    // additional fields...\n  }\n]\n```\n\n### Status codes {#get-all-status-codes} \n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |\n\n## Get shard {#get-shard}\n\n\tGET /v1/shards/{int: uid}\n\nGets information about a single shard.\n\n### Request {#get-request} \n\n#### Example HTTP request\n\n\tGET /v1/shards/1?extra_info_keys=used_memory_rss\u0026extra_info_keys=connected_clients\n\n#### Request headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The unique ID of the requested shard. |\n\n#### Query parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| extra_info_keys | list of strings | An optional list of extra keys to be fetched from the Redis [`INFO`](https://redis.io/docs/latest/commands/info) command. See [extra_info_keys](#extra_info_keys) for common keys to include. |\n\n### Response {#get-response} \n\nReturns a [shard object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/shard).\n\n#### Example JSON body\n\n```json\n{\n  \"assigned_slots\": \"0-16383\",\n  \"bdb_uid\": 1,\n  \"detailed_status\": \"ok\",\n  \"loading\": {\n    \"status\": \"idle\"\n  },\n  \"node_uid\": \"1\",\n  \"redis_info\": {\n\t\t\"connected_clients\": 14,\n\t\t\"used_memory_rss\": 12263424\n\t},\n  \"role\": \"master\",\n  \"report_timestamp\": \"2024-06-28T18:44:01Z\",\n  \"status\": \"active\",\n  \"uid\": \"1\"\n}\n```\n\n### Status codes {#get-status-codes} \n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Shard UID does not exist. |\n\n## extra_info_keys\n\nYou can include any Redis [`INFO`](https://redis.io/docs/latest/commands/info) command key for shard requests using the `extra_info_keys` query parameter. The requested keys are returned in the `redis_info` object of the response.\n\nSee the following tables for common keys to include.\n\n### Client keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| blocked_clients | integer | Number of clients pending on a blocking call |\n| client_recent_max_input_buffer | integer | Biggest input buffer among current client connections |\n| client_recent_max_output_buffer | integer | Biggest output buffer among current client connections |\n| connected_clients | integer | Number of client connections, excluding connections from replicas |\n\n### Memory keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| maxmemory | integer | Value of the maxmemory configuration directive |\n| used_memory | integer | Total number of bytes allocated by Redis |\n| used_memory_dataset | integer | Size in bytes of the dataset |\n| used_memory_lua | integer | Number of bytes used by the Lua engine |\n| used_memory_overhead | integer | Sum of all overheads that the server allocated for managing its internal data structures |\n| used_memory_peak | integer | Peak memory in bytes consumed by Redis |\n| used_memory_rss | integer | Number of bytes that Redis allocated as seen by the operating system |\n\n### Persistence keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| aof_enabled | integer | Flag indicating append-only file (AOF) logging is activated |\n| aof_rewrite_in_progress | integer | Flag indicating an AOF rewrite operation is on-going |\n| rdb_bgsave_in_progress | integer | Flag indicating an RDB save is on-going |\n| rdb_changes_since_last_save | integer | Number of changes since the last dump |\n| rdb_last_bgsave_status | string | Status of the last RDB save operation |\n| rdb_last_save_time | integer | Epoch-based timestamp of last successful RDB save |\n\n### Replication keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| master_last_io_seconds_ago | integer | Number of seconds since the last interaction with the primary shard |\n| master_repl_offset | integer | The server's current replication offset |\n| slave_repl_offset | integer | Replication offset of the replica instance |\n\n### Server keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| configured_hz | integer | Server's configured frequency setting |\n| hz | integer | Server's current frequency setting |\n| redis_version | string | Version of the Redis server |\n| uptime_in_days | integer | Number of days since Redis server start |\n| uptime_in_seconds | integer | Number of seconds since Redis server start |\n\n### Statistics keys\n\n| Key | Type | Description |\n|-----|------|-------------|\n| instantaneous_ops_per_sec | integer | Number of commands processed per second |\n| keyspace_hits | integer | Number of successful lookup of keys in the main dictionary |\n| keyspace_misses | integer | Number of failed lookup of keys in the main dictionary |\n| total_commands_processed | integer | Total number of commands processed by the server |\n| total_connections_received | integer | Total number of connections accepted by the server |\n| total_net_input_bytes | integer | Total number of bytes read from the network |\n| total_net_output_bytes | integer | Total number of bytes written to the network |\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-08-24T11:13:03-07:00",
  "children": [{"id":"operate/rs/references/rest-api/requests/shards/actions","summary":"REST API requests to perform shard actions","title":"Shard actions requests","url":"https://redis.io/docs/latest/operate/rs/8.0/references/rest-api/requests/shards/actions/"},{"id":"operate/rs/references/rest-api/requests/shards/stats","summary":"Shard statistics requests","title":"Shards stats requests","url":"https://redis.io/docs/latest/operate/rs/8.0/references/rest-api/requests/shards/stats/"}]
}