{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/usage_report",
  "title": "Usage report requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/usage_report/",
  "summary": "REST API request to get the database usage report from the cluster.",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-07-02T11:30:01-05:00",
  "children": [],
  "page_type": "content",
  "content_hash": "ba18e1110a2f4d5a1654d427beb553b27027e13730a53dd9a5d5d2e4f7b3ca00",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-usage-report) | `/v1/usage_report` | Get the cluster's database usage report |"
    },
    {
      "id": "get-usage-report",
      "title": "Get usage report",
      "role": "content",
      "text": "[code example]\n\nGets the database usage report from the cluster as Newline Delimited JSON (NDJSON). The response is returned as a gzip file if the request includes the `Accept-Encoding: gzip` header; otherwise, it returns an NDJSON file directly. The final line in the file is the response's MD5 hash."
    },
    {
      "id": "get-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n| Accept-Encoding | gzip | (Optional) Request gzip compression for the response |"
    },
    {
      "id": "get-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns Newline Delimited JSON (NDJSON), which represents the usage report for every database in the cluster. The response is returned as a gzip file if the request includes the `Accept-Encoding: gzip` header; otherwise, it returns an NDJSON file directly. The final line in the file is the response's MD5 hash.\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| active_active | boolean | Indicates if Active-Active is enabled |\n| api_version | string | API version |\n| backup | boolean | Indicates if backup is enabled |\n| bdb_uid | string | The database's unique ID |\n| cluster_name | string | Cluster name |\n| cluster_uuid | string | Cluster's unique ID |\n| date | string | Date of the report, including time and time zone |\n| <span class=\"break-all\">dominant_shard_criteria</span> | \"mem\"<br />\"ops\"<br />\"rof\" | Dominant criteria for shard selection |\n| type | \"core\"<br />\"premium\"<br />\"auto_tiering\" | Database type |\n| shard_type | \"micro\"<br />\"normal\"<br />\"large\"<br />\"auto_tiering\" | Shard type |\n| no_eviction | boolean | Indicates if no eviction policy is applied |\n| ops/sec | number | Consolidated ops/sec for the whole database |\n| persistence | boolean | Indicates if persistence is enabled |\n| <span class=\"break-all\">provisioned_memory</span> | number | Provisioned memory in bytes |\n| replication | boolean | Indicates if replication is enabled |\n| software_version | string | The Redis Software version |\n| used_memory | number | Used memory in bytes |\n| <span class=\"break-all\">using_redis_search</span> | boolean | Indicates if Redis Search is in use |\n| <span class=\"break-all\">master_shards_count</span> | number | Amount of primary shards |\n| license | object | License information for the cluster<br /> \"license\": {<br />    \"activation_date\": string,<br />    \"expiration_date\": string,<br />    \"ram_shards_in_use\": integer,<br />    \"ram_shards_limit\": integer,<br />    \"flash_shards_in_use\": integer,<br />    \"flash_shards_limit\": integer,<br />    \"shards_limit\": integer<br />}<br />**activation_date**: License activation date and time<br />**expiration_date**: License expiration date and time<br />**ram_shards_in_use**: Amount of RAM shards in use<br />**ram_shards_limit**: Amount of RAM shards allowed<br />**flash_shards_in_use**: Amount of flash shards in use<br />**flash_shards_limit**: Amount of flash shards allowed<br />**shards_limit**: Total shards limit |\n\n#### Example response\n\n[code example]\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| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Invalid date format |\n| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Unreachable node |"
    }
  ],
  "examples": [
    {
      "id": "get-usage-report-ex0",
      "language": "sh",
      "code": "GET /v1/usage_report",
      "section_id": "get-usage-report"
    },
    {
      "id": "get-request-ex0",
      "language": "sh",
      "code": "GET /v1/usage_report",
      "section_id": "get-request"
    },
    {
      "id": "get-response-ex0",
      "language": "json",
      "code": "{\n \"cluster_name\": \"mycluster.local\",\n \"cluster_uuid\": \"7e9f93c6-825e-4bbb-a067-7f6306b98609\",\n \"date\": \"2024-08-08T13:16:00.000000Z\",\n \"software_version\": \"7.0.0\",\n \"api_version\" \"1\",\n \"bdb_uid\": \"1\",\n \"type\": \"auto_tiering\",\n \"shard_type\": \"auto_tiering\",\n \"dominant_shard_criteria\": \"rof\",\n \"provisioned_memory\": 1073741824,\n \"used_memory\": 5828776,\n \"master_shards_count\": 3,\n \"no_eviction\": false,\n \"persistence\": false,\n \"backup\": false,\n \"using_redis_search\": false,\n \"ops_sec\": 0,\n \"replication\": false,\n \"active_active\": false,\n \"license\": {\n   \"activation_date\": \"2018-12-31T00:00:00Z\",\n   \"expiration_date\": \"2019-12-31T00:00:00Z\",\n   \"ram_shards_in_use\": 0,\n   \"ram_shards_limit\": 300,\n   \"flash_shards_in_use\": 0,\n   \"flash_shards_limit\": 100,\n   \"shards_limit\": 400\n }\n}\n{\n \"cluster_name\": \"mycluster.local\",\n \"cluster_uuid\": \"7e9f93c6-825e-4bbb-a067-7f6306b98609\",\n \"date\": \"2024-08-08T13:17:00.000000Z\",\n \"software_version\": \"7.0.0\",\n \"api_version\" \"1\",\n \"bdb_uid\": \"1\",\n \"type\": \"auto_tiering\",\n \"shard_type\": \"auto_tiering\",\n \"dominant_shard_criteria\": \"rof\",\n \"provisioned_memory\": 1073741824,\n \"used_memory\": 5828776,\n \"master_shards_count\": 3,\n \"no_eviction\": false,\n \"persistence\": false,\n \"backup\": false,\n \"using_redis_search\": false,\n \"ops_sec\": 0,\n \"replication\": false,\n \"active_active\": false,\n \"license\": {\n   \"activation_date\": \"2018-12-31T00:00:00Z\",\n   \"expiration_date\": \"2019-12-31T00:00:00Z\",\n   \"ram_shards_in_use\": 0,\n   \"ram_shards_limit\": 300,\n   \"flash_shards_in_use\": 0,\n   \"flash_shards_limit\": 100,\n   \"shards_limit\": 400\n }\n}\n...\n<MD5 hash of the entire response>",
      "section_id": "get-response"
    }
  ]
}