> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cluster API v2.0

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The CockroachDB Cluster API is a REST API that provides information about a cluster and its nodes. The API offers programmatic access to much of the information available in the <InternalLink path="ui-overview">DB Console</InternalLink> user interface, enabling you to monitor and troubleshoot your cluster using your choice of tooling.

The Cluster API is hosted by all nodes of your cluster and provides information about all nodes. The API is available on the same port that is listening for HTTP connections to the DB Console. This defaults to `8080` and can be specified using `--http-addr={server}:{port}` when configuring your node.

## Resources

The following endpoints are available as URLs under the `/api/v2` base path (for example, `https://localhost:8080/api/v2/health/`). For more information about the support policies for endpoints, see <InternalLink path="api-support-policy">API Support Policy</InternalLink>.

Each listed endpoint links to its full <InternalLink version="api" path="cluster/v2">API reference documentation</InternalLink>.

| Endpoint                                                                                                              | Name                 | Description                                                                                                                                                                                                                                                                                              | Support  |
| --------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| <InternalLink version="api" path="cluster/v2/list-databases">`/databases`</InternalLink>                              | List databases       | Get all databases in the cluster.                                                                                                                                                                                                                                                                        | Stable   |
| <InternalLink version="api" path="cluster/v2/get-database-descriptor-id">`/databases/{database}`</InternalLink>       | Get database details | Get the descriptor ID of a specified database.                                                                                                                                                                                                                                                           | Stable   |
| <InternalLink version="api" path="cluster/v2/list-grants-on-a-database">`/databases/{database}/grants`</InternalLink> | List database grants | List all [privileges](security-reference/authorization.html#managing-privileges) granted to users for a specified database.                                                                                                                                                                              | Stable   |
| <InternalLink version="api" path="cluster/v2/list-tables-on-a-database">`/databases/{database}/tables`</InternalLink> | List database tables | List all tables in a specified database.                                                                                                                                                                                                                                                                 | Stable   |
| <InternalLink version="api" path="cluster/v2/get-table-details">`/databases/{database}/tables/{table}`</InternalLink> | Get table details    | Get details on a specified table, including schema, grants, indexes, range count, and <InternalLink path="configure-replication-zones">zone configurations</InternalLink>.                                                                                                                               | Stable   |
| <InternalLink version="api" path="cluster/v2/list-events">`/events`</InternalLink>                                    | List events          | List the latest <InternalLink path="eventlog">events</InternalLink> on the cluster, in descending order.                                                                                                                                                                                                 | Unstable |
| <InternalLink version="api" path="cluster/v2/check-node-health">`/health`</InternalLink>                              | Check node health    | Determine if the node is running and ready to accept SQL connections.                                                                                                                                                                                                                                    | Stable   |
| <InternalLink version="api" path="cluster/v2/list-nodes">`/nodes`</InternalLink>                                      | List nodes           | Get details on all nodes in the cluster, including node IDs, software versions, and hardware.                                                                                                                                                                                                            | Stable   |
| <InternalLink version="api" path="cluster/v2/list-node-ranges">`/nodes/{node_id}/ranges`</InternalLink>               | List node ranges     | Get details on the ranges on a specified node.                                                                                                                                                                                                                                                           | Unstable |
| <InternalLink version="api" path="cluster/v2/list-hot-ranges">`/ranges/hot`</InternalLink>                            | List hot ranges      | Get information on ranges receiving a high number of reads or writes.                                                                                                                                                                                                                                    | Stable   |
| <InternalLink version="api" path="cluster/v2/get-range-details">`/ranges/{range_id}`</InternalLink>                   | Get range details    | Get detailed technical information on a range. Typically used by Cockroach Labs engineers.                                                                                                                                                                                                               | Unstable |
| <InternalLink version="api" path="cluster/v2/list-sessions">`/sessions`</InternalLink>                                | List sessions        | Get SQL session details of all current users or a specified user.                                                                                                                                                                                                                                        | Unstable |
| <InternalLink version="api" path="cluster/v2/list-users">`/users`</InternalLink>                                      | List users           | List all SQL users on the cluster.                                                                                                                                                                                                                                                                       | Stable   |
| <InternalLink version="api" path="cluster/v2/log-in">`/login`</InternalLink>                                          | Log in               | Authenticate as a <InternalLink path="create-role#create-a-role-that-can-log-in-to-the-database">SQL role</InternalLink> that is a member of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> to retrieve a session token to use with further API calls. | Stable   |
| <InternalLink version="api" path="cluster/v2/log-out">`/logout`</InternalLink>                                        | Log out              | Invalidate the session token.                                                                                                                                                                                                                                                                            | Stable   |

## Requirements

All endpoints except `/health` and `/login` require authentication using a session token. To obtain a session token, you will need:

* A <InternalLink path="create-role">SQL role</InternalLink> that is a member of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> and has login permissions and a password.

To connect with the API on a secure cluster, you will need:

* The CA cert used by the cluster or any intermediary proxy server, either in the client's cert store as a trusted certificate authority or as a file manually specified by the HTTP request (for example, using curl's [cacert](https://curl.se/docs/manpage.html#--cacert)).

<a id="license-expiration-message" />

## Authentication

To create and manage web sessions and authentication tokens to the Cluster API from the command line, use the <InternalLink path="cockroach-auth-session">`cockroach auth-session`</InternalLink> CLI command.

Alternatively, you may also request a token directly from the `/login` endpoint using the following instructions:

1. Request a session token using the `/login` endpoint. For example:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   curl -d "username=user&password=pass" \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   https://localhost:8080/api/v2/login/
   ```

2. Record the token (`session` value) that is returned.

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   {"session":"CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow=="}
   ```

3. Pass the token with each call using the `X-Cockroach-API-Session` header. For example:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   curl -H "X-Cockroach-API-Session: CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow==" \
   https://localhost:8080/api/v2/nodes/
   ```

## Versioning and stability

The Cluster API version is defined in the request path. For example: `<cluster/api/v2/health`.

Future versions of CockroachDB may provide multiple API versions and will continue to provide access to this v2.0 API until it is deprecated.

All endpoint paths and payloads will remain available within a major API version number (`v2.x`). Patch versions could add new endpoints but will not remove existing endpoints. For more information, see <InternalLink path="api-support-policy">API Support Policy</InternalLink>.