{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/bdbs/availability",
  "title": "Database availability requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/availability/",
  "summary": "REST API requests to check database availability",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-07-21T11:19:25-05:00",
  "page_type": "content",
  "content_hash": "7ee223820c77c3595079b2fb5acfdfa673511f59c4d337d8f4198c3db478dc05",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-db-endpoint-availability) | `/v1/local/bdbs/{uid}/endpoint/availability` | Verifies local database endpoint availability |\n| [GET](#get-db-availability) | `/v1/bdbs/{uid}/availability` | Verifies database availability |"
    },
    {
      "id": "get-db-endpoint-availability",
      "title": "Get database endpoint availability",
      "role": "content",
      "text": "[code example]\n\nVerifies the local database endpoint is available. This request does not redirect to the primary node."
    },
    {
      "id": "permissions",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [view_bdb_info](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_bdb_info) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "get-endpoint-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP requests\n\nTo check database endpoint availability without any additional checks:\n\n[code example]\n\nTo perform a lag-aware database endpoint availability check using the cluster's default lag tolerance threshold:\n\n[code example]\n\nTo perform a lag-aware database endpoint availability check and override the cluster's default lag tolerance threshold:\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\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The unique ID of the database. |\n\n#### Query parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| extend_check | list of comma-separated strings | List of additional availability checks to perform (optional)<br />Values:<br />**lag**: Enables lag-aware checks to assess replication health. Determines if a replica is sufficiently synced with the primary for failover/failback scenarios. |\n| availability_lag_tolerance_ms | integer | Overrides the cluster's default lag tolerance threshold when using `extend_check=lag`. Recommended value: 100 milliseconds. |"
    },
    {
      "id": "get-endpoint-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns the status code `200 OK` if the local database endpoint is available.\n\nIf the local database endpoint is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields."
    },
    {
      "id": "get-endpoint-error-codes",
      "title": "Error codes",
      "role": "errors",
      "text": "When errors are reported, the server may return a JSON object with\n`error_code` and `description` fields that provide additional information.\nThe following are possible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| no_quorum | Master healthcheck failed (no quorum in the cluster) |\n| db_not_found | Database does not exist in the cluster |\n| bdb_endpoint_unavailable | Local database endpoint is not available |"
    },
    {
      "id": "get-endpoint-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database endpoint is available. |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Invalid schema. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database not found. |\n| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database endpoint is unavailable. |"
    },
    {
      "id": "get-db-availability",
      "title": "Get database availability",
      "role": "content",
      "text": "[code example]\n\nGets the availability status of a database.\n\n- If the OSS Cluster API is enabled, verifies all endpoints for this database are available.\n\n- Otherwise, verifies the database has at least one available endpoint."
    },
    {
      "id": "permissions-1",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [view_bdb_info](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_bdb_info) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "get-db-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP requests\n\n\nTo check database availability without any additional checks:\n\n[code example]\n\nTo perform a lag-aware database availability check using the cluster's default lag tolerance threshold:\n\n[code example]\n\nTo perform a lag-aware database availability check and override the cluster's default lag tolerance threshold:\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\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The unique ID of the database. |\n\n#### Query parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| extend_check | list of comma-separated strings | List of additional availability checks to perform (optional)<br />Values:<br />**lag**: Enables lag-aware checks to assess replication health. Determines if a replica is sufficiently synced with the primary for failover/failback scenarios. |\n| availability_lag_tolerance_ms | integer | Overrides the cluster's default lag tolerance threshold when using `extend_check=lag`. Recommended value: 100 milliseconds. |"
    },
    {
      "id": "get-db-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns the status code `200 OK` if the database is available.\n\nIf the database is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields."
    },
    {
      "id": "get-db-error-codes",
      "title": "Error codes",
      "role": "errors",
      "text": "When errors are reported, the server may return a JSON object with\n`error_code` and `description` fields that provide additional information.\nThe following are possible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| no_quorum | Master healthcheck failed (no quorum in the cluster) |\n| db_not_found | Database does not exist in the cluster |\n| bdb_unavailable | Database is not available. The `error_code` identifies why: it appends `_shard_unreachable` when a primary (master) shard is unreachable and `_port_unbound` when the endpoint's listener port is not bound. For example, `bdb_unavailable_shard_unreachable`, `bdb_unavailable_port_unbound`, or `bdb_unavailable_shard_unreachable_port_unbound`. The `description` names the same reasons, for example `Endpoint error status: shard unreachable, port unbound`. |"
    },
    {
      "id": "get-db-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database is available. |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Invalid schema. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database not found. |\n| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database is unavailable or doesn't have quorum. |"
    }
  ],
  "examples": [
    {
      "id": "get-db-endpoint-availability-ex0",
      "language": "sh",
      "code": "GET /v1/local/bdbs/{uid}/endpoint/availability",
      "section_id": "get-db-endpoint-availability"
    },
    {
      "id": "get-endpoint-request-ex0",
      "language": "sh",
      "code": "GET /v1/local/bdbs/1/endpoint/availability",
      "section_id": "get-endpoint-request"
    },
    {
      "id": "get-endpoint-request-ex1",
      "language": "sh",
      "code": "GET /v1/local/bdbs/1/endpoint/availability?extend_check=lag",
      "section_id": "get-endpoint-request"
    },
    {
      "id": "get-endpoint-request-ex2",
      "language": "sh",
      "code": "GET /v1/local/bdbs/1/endpoint/availability?extend_check=lag&availability_lag_tolerance_ms=100",
      "section_id": "get-endpoint-request"
    },
    {
      "id": "get-db-availability-ex0",
      "language": "sh",
      "code": "GET /v1/bdbs/{uid}/availability",
      "section_id": "get-db-availability"
    },
    {
      "id": "get-db-request-ex0",
      "language": "sh",
      "code": "GET /v1/bdbs/1/availability",
      "section_id": "get-db-request"
    },
    {
      "id": "get-db-request-ex1",
      "language": "sh",
      "code": "GET /v1/bdbs/1/availability?extend_check=lag",
      "section_id": "get-db-request"
    },
    {
      "id": "get-db-request-ex2",
      "language": "sh",
      "code": "GET /v1/bdbs/1/availability?extend_check=lag&availability_lag_tolerance_ms=100",
      "section_id": "get-db-request"
    }
  ]
}