Cluster API

REST API endpoints for managing Qdrant cluster operations and distributed deployment

When running Qdrant in distributed mode, these endpoints help you manage the cluster, monitor peer health, and perform cluster operations.

Get Cluster Status

Retrieve information about the current state and composition of the cluster.

curl -X GET 'http://localhost:6333/cluster'

Response

result · object

status · string

Overall cluster status: enabled or disabled

peer_id · integer

Current peer’s ID

peers · object

Map of peer IDs to peer information

uri · string

Peer’s URI

raft_info · object

Raft consensus information

term · integer

Current Raft term

commit · integer

Last committed log index

pending_operations · integer

Number of pending operations

leader · integer

Current leader peer ID

role · string

This peer’s role: Leader, Follower, or Candidate

is_voter · boolean

Whether this peer is a voting member

consensus_thread_status · object

Status of the consensus thread

consensus_thread_status · string

Status: working, stopped, or stopped_with_err

last_update · string

ISO 8601 timestamp of last update

message_send_failures · object

Map of peer IDs to message send failure counts

Get Cluster Telemetry

Collect detailed telemetry data from the cluster perspective, including peers info, collections info, shard transfers, and resharding status.

curl -X GET 'http://localhost:6333/cluster/telemetry'

Query Parameters

details_level · integer

Level of detail to include in the response. Higher values include more detailed information.

timeout · integer

Timeout for this request in seconds. Default is 60.

Response

result · object

Comprehensive telemetry data including:

peers · object

Information about all peers in the cluster

collections · object

Collection-level telemetry for all collections

shards · object

Shard distribution and status across the cluster

transfers · array

Active and pending shard transfer operations

Remove Peer from Cluster

Remove a peer from the cluster. The operation will fail if the peer has active shards.

curl -X DELETE 'http://localhost:6333/cluster/peer/{peer_id}'

Path Parameters

peer_id · integer · required

ID of the peer to remove

Query Parameters

force · boolean

If true, removes peer even if it has shards/replicas on it. Default is false. Use with caution as this can lead to data loss.

timeout · integer

Wait for operation commit timeout in seconds. If timeout is reached, request returns with service error.

Response

result · boolean

Returns true if peer was removed successfully

Recover Current Peer

Attempt to recover the current peer’s Raft state. This operation should only be used in recovery scenarios when the cluster consensus is broken.

curl -X POST 'http://localhost:6333/cluster/recover'

Response

result · boolean

Returns true if recovery operation was initiated successfully

Collection Cluster Info

Get cluster-specific information for a particular collection, including shard distribution and replication status.

curl -X GET 'http://localhost:6333/collections/{collection_name}/cluster'

Path Parameters

collection_name · string · required

Name of the collection

Response

result · object

peer_id · integer

Current peer ID

shard_count · integer

Total number of shards for this collection

local_shards · array

Shards located on the current peer

shard_id · integer

Shard identifier

points_count · integer

Number of points in this shard

state · string

Shard state: Active, Dead, Partial, Initializing, or Listener

remote_shards · array

Shards located on other peers

shard_id · integer

Shard identifier

peer_id · integer

ID of the peer hosting this shard

state · string

Shard state

shard_transfers · array

Active shard transfer operations

shard_id · integer

Shard being transferred

from · integer

Source peer ID

to · integer

Destination peer ID

sync · boolean

Whether transfer is synchronous

Update Collection Cluster Setup

Perform cluster operations on a collection, such as moving shards, creating replicas, or aborting transfers.

curl -X POST 'http://localhost:6333/collections/{collection_name}/cluster' \
  -H 'Content-Type: application/json' \
  -d '{
    "move_shard": {
      "shard_id": 0,
      "from_peer_id": 1,
      "to_peer_id": 2
    }
  }'

Path Parameters

collection_name · string · required

Name of the collection

Query Parameters

timeout · integer

Wait for operation commit timeout in seconds

Request Body

One of the following operations:

move_shard · object

Move a shard from one peer to another

shard_id · integer · required

ID of the shard to move

from_peer_id · integer · required

Source peer ID

to_peer_id · integer · required

Destination peer ID

method · string

Transfer method: stream_records or snapshot. Default is stream_records.

replicate_shard · object

Create a replica of a shard on another peer

shard_id · integer · required

ID of the shard to replicate

from_peer_id · integer · required

Source peer ID

to_peer_id · integer · required

Destination peer ID

method · string

Transfer method

abort_transfer · object

Abort an ongoing shard transfer

shard_id · integer · required

ID of the shard

from_peer_id · integer · required

Source peer ID

to_peer_id · integer · required

Destination peer ID

drop_replica · object

Remove a replica from a peer

shard_id · integer · required

ID of the shard

peer_id · integer · required

Peer ID to remove replica from

Response

result · boolean

Returns true if cluster operation was initiated successfully