CockroachDB v2 API (2.0)

License: Business Source License

REST API for querying information about CockroachDB cluster health, nodes, ranges, sessions, and other meta information. For additional details, see cockroachlabs.com/docs/stable/cluster-api.

List databases

List all databases on this cluster.

query Parameters

limit	integer Maximum number of results to return in this call.
offset	integer Continuation token for results after a past limited run.

Responses

Response Schema: application/json

databases	Array of strings
next	integer <int64> The continuation token, for use in the next paginated call in the `offset` parameter.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/databases/?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE'

Response samples

200

Content type

application/json

{"databases": ["string"
],
"next": 0
}

Get database descriptor ID

Retrieve the database's descriptor ID.

path Parameters

database

required

string

Name of the database being looked up.

Responses

Response Schema: application/json

descriptor_id

integer <int64>

An identifier used to uniquely identify this database. It can be used to find events pertaining to this database by filtering on the target_id field of events.

Request samples

Shell + Curl

curl --request GET \
  --url https://localhost/api/v2/databases/%7Bdatabase%7D/

Response samples

200

Content type

application/json

{"descriptor_id": 0
}

List grants on a database

Retrieve grants on a database. Grants are the privileges granted to users on this database.

path Parameters

database

required

string

Name of the database being looked up.

query Parameters

limit	integer Maximum number of grants to return in this call.
offset	integer Continuation token for results after a past limited run.

Responses

Response Schema: application/json

	Array of objects (DatabaseDetailsResponse_Grant) Grants are the privileges granted to users on this database.
next	integer <int64> The continuation token, for use in the next paginated call in the `offset` parameter.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/databases/%7Bdatabase%7D/grants/?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE'

Response samples

200

Content type

application/json

{"grants": [{"privileges": ["string"
],
"user": "string"
}
],
"next": 0
}

List tables on a database

List names of all tables in the database. The names of all responses will be schema-qualified.

path Parameters

database

required

string

Name of the database being looked up.

query Parameters

limit	integer Maximum number of tables to return in this call.
offset	integer Continuation token for results after a past limited run.

Responses

Response Schema: application/json

next	integer <int64> The continuation token, for use in the next paginated call in the `offset` parameter.
table_names	Array of strings The names of all tables in this database. Note that all responses will be schema-qualified (schema.table) and that every schema or table that contains a "sql unsafe character" such as uppercase letters or dots will be surrounded with double quotes, such as "Naughty schema".table.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/databases/%7Bdatabase%7D/tables/?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE'

Response samples

200

Content type

application/json

{"next": 0,
"table_names": ["string"
]
}

Get table details

Retrieve details about a table.

path Parameters

database required	string Name of the database being looked up.
table required	string Name of table being looked up. Table may be schema-qualified (schema.table) and each name component that contains sql unsafe characters such as . or uppercase letters must be surrounded in double quotes like "Naughty schema".table.

Responses

Response Schema: application/json

	Array of objects (TableDetailsResponse_Column)
configure_zone_statement	string The output of "SHOW ZONE CONFIGURATION FOR TABLE" for this table. It is a SQL statement that would re-configure the table's current zone if executed.
create_table_statement	string The output of "SHOW CREATE" for this table; it is a SQL statement that would re-create the table's current schema if executed.
descriptor_id	integer <int64> An identifier used to uniquely identify this table. It can be used to find events pertaining to this table by filtering on the `target_id` field of events.
	Array of objects (Grant is an entry from SHOW GRANTS.)
	Array of objects (TableDetailsResponse_Index)
range_count	integer <int64> The size of the table in ranges. This provides a rough estimate of the storage requirements for the table.
	object (ZoneConfig holds configuration that applies to one or more ranges.) For internal use only.
zone_config_level	integer <int32> (ZoneConfigurationLevel indicates, for objects with a Zone Configuration, the object level at which the configuration is defined. This is needed because objects without a specifically indicated Zone Configuration will inherit the configuration of their 'parent'. Valid levels are unknown (0), cluster (1), database (2), or table (3).) The object level at which the configuration is defined. This is needed because objects without a specifically indicated Zone Configuration will inherit the configuration of their "parent".

Request samples

Shell + Curl

curl --request GET \
  --url https://localhost/api/v2/databases/%7Bdatabase%7D/tables/%7Btable%7D/

Response samples

200

Content type

application/json

{"columns": [{"default_value": "string",
"generation_expression": "string",
"hidden": true,
"name": "string",
"nullable": true,
"type": "string"
}
],
"configure_zone_statement": "string",
"create_table_statement": "string",
"descriptor_id": 0,
"grants": [{"privileges": ["string"
],
"user": "string"
}
],
"indexes": [{"column": "string",
"direction": "string",
"implicit": true,
"name": "string",
"seq": 0,
"storing": true,
"unique": true
}
],
"range_count": 0,
"zone_config": {"constraints": [{"constraints": [{"key": "string",
"type": 0,
"value": "string"
}
],
"num_replicas": 0
}
],
"gc": {"ttl_seconds": 0
},
"global_reads": true,
"inherited_constraints": true,
"inherited_lease_preferences": true,
"lease_preferences": [{"constraints": [{"key": "string",
"type": 0,
"value": "string"
}
]
}
],
"null_voter_constraints_is_empty": true,
"num_replicas": 0,
"num_voters": 0,
"range_max_bytes": 0,
"range_min_bytes": 0,
"subzone_spans": [{"end_key": [0
],
"key": [0
],
"subzone_index": 0
}
],
"subzones": [{"config": { },
"index_id": 0,
"partition_name": "string"
}
],
"voter_constraints": [{"constraints": [{"key": "string",
"type": 0,
"value": "string"
}
],
"num_replicas": 0
}
]
},
"zone_config_level": 0
}

List events

List the latest event log entries, in descending order.

query Parameters

type	string Type of events to filter for (e.g., "create_table"). Only one event type can be specified at a time.
targetID	integer Filter for events with this targetID. Only one targetID can be specified at a time.
limit	integer Maximum number of results to return in this call.
offset	integer Continuation token for results after a past limited run.

Responses

Response Schema: application/json

	Array of objects (EventsResponse_Event)
next	integer <int64> The continuation token, for use in the next paginated call in the `offset` parameter.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/events/?type=SOME_STRING_VALUE&targetID=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE'

Response samples

200

Content type

application/json

{"events": [{"event_type": "string",
"info": "string",
"reporting_id": 0,
"target_id": 0,
"timestamp": "2019-08-24T14:15:22Z",
"unique_id": [0
]
}
],
"next": 0
}

Check node health

Check for node health. If ready is true, also check if this node is fully operational and ready to accept SQL connections. Otherwise, this endpoint always returns a successful response (if the API server is up).

query Parameters

ready

boolean

If true, check whether this node is ready to accept SQL connections. If false, this endpoint always returns success, unless the API server itself is down.

Responses

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/health/?ready=SOME_BOOLEAN_VALUE'

Log in

Create an API session for use with API endpoints that require authentication.

Request Body schema: application/x-www-form-urlencoded

Credentials for login.

password required	string
username required	string

Responses

Response Schema: application/json

session

string

Session string for a valid API session. Specify this in header for any API requests that require authentication.

Request samples

Shell + Curl

curl --request POST \
  --url https://localhost/api/v2/login/ \
  --header 'content-type: application/x-www-form-urlencoded'

Response samples

200

Content type

application/json

{"session": "string"
}

Log out

Log out, invalidating the API session token.

Authorizations:

api_session

Responses

Response Schema: application/json

logged_out

boolean

Indicates whether logout was succeessful.

Request samples

Shell + Curl

curl --request POST \
  --url https://localhost/api/v2/logout/ \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"logged_out": true
}

List nodes

List all nodes on this cluster.

Client must be logged in as a user with admin privileges.

Authorizations:

api_session

query Parameters

limit	integer Maximum number of results to return in this call.
offset	integer Continuation offset for results after a past limited run.

Responses

Response Schema: application/json

next	integer <int64> Continuation offset for the next paginated call, if more values are present. Specify as the `offset` parameter.
	Array of objects (Status about a node.) Status of nodes.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/nodes/?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"next": 0,
"nodes": [{"ServerVersion": {"internal": 0,
"major_val": 0,
"minor_val": 0,
"patch": 0
},
"address": {"address_field": "string",
"network_field": "string"
},
"attrs": {"attrs": ["string"
]
},
"build_tag": "string",
"cluster_name": "string",
"liveness_status": 0,
"locality": {"tiers": [{"key": "string",
"value": "string"
}
]
},
"metrics": {"property1": 0,
"property2": 0
},
"node_id": 0,
"num_cpus": 0,
"sql_address": {"address_field": "string",
"network_field": "string"
},
"started_at": 0,
"total_system_memory": 0,
"updated_at": 0
}
]
}

List node ranges

List information about ranges on a specified node. If a list of range IDs is specified, only information about those ranges is returned.

Client must be logged-in as a user with admin privileges.

Authorizations:

api_session

path Parameters

node_id

required

integer

ID of node to query, or local for local node.

query Parameters

ranges	Array of integers IDs of ranges to return information for. All ranges returned if unspecified.
limit	integer Maximum number of results to return in this call.
offset	integer Continuation offset for results after a past limited run.

Responses

Response Schema: application/json

next	integer <int64> Continuation token for the next limited run. Use in the `offset` parameter.
	Array of objects (Info related to a range.) Info about retrieved ranges.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/nodes/%7Bnode_id%7D/ranges/?ranges=SOME_ARRAY_VALUE&limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE' \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"next": 0,
"ranges": [{"desc": {"end_key": [0
],
"queries_per_second": 0,
"range_id": 0,
"start_key": [0
],
"store_id": 0
},
"error_message": "string",
"lease_history": [{"acquisition_type": 0,
"deprecated_start_stasis": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"epoch": 0,
"expiration": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"proposed_ts": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"replica": {"node_id": 0,
"replica_id": 0,
"store_id": 0,
"type": 0
},
"sequence": 0,
"start": {"logical": 0,
"synthetic": true,
"wall_time": 0
}
}
],
"problems": {"leader_not_lease_holder": true,
"no_lease": true,
"no_raft_leader": true,
"overreplicated": true,
"quiescent_equals_ticking": true,
"raft_log_too_large": true,
"unavailable": true,
"underreplicated": true
},
"quiescent": true,
"source_node_id": 0,
"source_store_id": 0,
"span": {"end_key": "string",
"start_key": "string"
},
"stats": {"queries_per_second": 0,
"writes_per_second": 0
},
"ticking": true
}
]
}

List hot ranges

List information about hot ranges. If a list of range IDs is specified, only information about those ranges is returned.

Client must be logged in as a user with admin privileges.

Authorizations:

api_session

query Parameters

node_id	integer ID of node to query, or `local` for local node. If unspecified, all nodes are queried.
limit	integer Maximum number of results to return in this call.
start	string Continuation token for results after a past limited run.

Responses

Response Schema: application/json

next	string Continuation token for the next paginated call. Use as the `start` parameter.
	object
	Array of objects (responseError)

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/ranges/hot/?node_id=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE' \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"next": "string",
"ranges_by_node_id": {"property1": [{"end_key": [0
],
"queries_per_second": 0,
"range_id": 0,
"start_key": [0
],
"store_id": 0
}
],
"property2": [{"end_key": [0
],
"queries_per_second": 0,
"range_id": 0,
"start_key": [0
],
"store_id": 0
}
]
},
"response_error": [{"error_message": "string",
"node_id": 0
}
]
}

Get range details

Retrieve more information about a specific range.

Client must be logged in as a user with admin privileges.

Authorizations:

api_session

path Parameters

range_id

required

integer

Responses

Response Schema: application/json

object

Request samples

Shell + Curl

curl --request GET \
  --url https://localhost/api/v2/ranges/%7Brange_id%7D/ \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"responses_by_node_id": {"property1": {"error": "string",
"range_info": {"desc": {"end_key": [0
],
"queries_per_second": 0,
"range_id": 0,
"start_key": [0
],
"store_id": 0
},
"error_message": "string",
"lease_history": [{"acquisition_type": 0,
"deprecated_start_stasis": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"epoch": 0,
"expiration": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"proposed_ts": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"replica": {"node_id": 0,
"replica_id": 0,
"store_id": 0,
"type": 0
},
"sequence": 0,
"start": {"logical": 0,
"synthetic": true,
"wall_time": 0
}
}
],
"problems": {"leader_not_lease_holder": true,
"no_lease": true,
"no_raft_leader": true,
"overreplicated": true,
"quiescent_equals_ticking": true,
"raft_log_too_large": true,
"unavailable": true,
"underreplicated": true
},
"quiescent": true,
"source_node_id": 0,
"source_store_id": 0,
"span": {"end_key": "string",
"start_key": "string"
},
"stats": {"queries_per_second": 0,
"writes_per_second": 0
},
"ticking": true
}
},
"property2": {"error": "string",
"range_info": {"desc": {"end_key": [0
],
"queries_per_second": 0,
"range_id": 0,
"start_key": [0
],
"store_id": 0
},
"error_message": "string",
"lease_history": [{"acquisition_type": 0,
"deprecated_start_stasis": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"epoch": 0,
"expiration": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"proposed_ts": {"logical": 0,
"synthetic": true,
"wall_time": 0
},
"replica": {"node_id": 0,
"replica_id": 0,
"store_id": 0,
"type": 0
},
"sequence": 0,
"start": {"logical": 0,
"synthetic": true,
"wall_time": 0
}
}
],
"problems": {"leader_not_lease_holder": true,
"no_lease": true,
"no_raft_leader": true,
"overreplicated": true,
"quiescent_equals_ticking": true,
"raft_log_too_large": true,
"unavailable": true,
"underreplicated": true
},
"quiescent": true,
"source_node_id": 0,
"source_store_id": 0,
"span": {"end_key": "string",
"start_key": "string"
},
"stats": {"queries_per_second": 0,
"writes_per_second": 0
},
"ticking": true
}
}
}
}

List sessions

List all sessions on this cluster. If a username is provided, only sessions from that user are returned.

Client must be logged in as a user with admin privileges.

Authorizations:

api_session

query Parameters

username	string Username of user to return sessions for; if unspecified, sessions from all users are returned.
limit	integer Maximum number of results to return in this call.
start	string Continuation token for results after a past limited run.

Responses

Response Schema: application/json

	Array of objects (An error wrapper object for ListSessionsResponse.) Any errors that occurred during fan-out calls to other nodes.
next	string The continuation token, for use in the next paginated call in the `start` parameter.
	Array of objects (Session represents one SQL session.) A list of sessions on this node or cluster.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/sessions/?username=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE' \
  --header 'X-Cockroach-API-Session: REPLACE_KEY_VALUE'

Response samples

200

Content type

application/json

{"errors": [{"message": "string",
"node_id": 0
}
],
"next": "string",
"sessions": [{"active_queries": [{"id": "string",
"is_distributed": true,
"phase": 0,
"progress": 0,
"sql": "string",
"sql_no_constants": "string",
"start": "2019-08-24T14:15:22Z",
"txn_id": [0
]
}
],
"active_txn": {"alloc_bytes": 0,
"deadline": "2019-08-24T14:15:22Z",
"id": [0
],
"implicit": true,
"is_historical": true,
"max_alloc_bytes": 0,
"num_auto_retries": 0,
"num_retries": 0,
"num_statements_executed": 0,
"priority": "string",
"read_only": true,
"start": "2019-08-24T14:15:22Z",
"txn_description": "string"
},
"alloc_bytes": 0,
"application_name": "string",
"client_address": "string",
"id": [0
],
"last_active_query": "string",
"last_active_query_no_constants": "string",
"max_alloc_bytes": 0,
"node_id": 0,
"start": "2019-08-24T14:15:22Z",
"username": "string"
}
]
}

List users

List SQL users on this cluster.

query Parameters

limit	integer Maximum number of results to return in this call.
offset	integer Continuation token for results after a past limited run.

Responses

Response Schema: application/json

next	integer <int64> The continuation token, for use in the next paginated call in the `offset` parameter.
	Array of objects (Username of the user.) A list of users for the CockroachDB cluster.

Request samples

Shell + Curl

curl --request GET \
  --url 'https://localhost/api/v2/users/?limit=SOME_INTEGER_VALUE&offset=SOME_INTEGER_VALUE'

Response samples

200

Content type

application/json

{"next": 0,
"users": [{"username": "string"
}
]
}