Until now, rebalancing replicas and scaling your cluster meant clicking through the UI. Now you can do it from a script.
Three new API endpoints let you rebalance traffic weights, add replicas, and remove replicas. Same operations as the UI, but automatable.
The endpoints
We added three endpoints to manage replica topology and traffic distribution:
PUT /v0/organizations/{organization_id}/clusters/{cluster_id}/weightsto request a manual rebalance.POST /v0/organizations/{organization_id}/clusters/{cluster_id}/replicasto add a new replica and assign initial weights.DELETE /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas/{replica_name}to remove a replica and rebalance traffic.
Note that API calls require an old_weights field to prevent conflicts from concurrent modifications. You must first GET the current configuration from the /v0/organizations/<organization_id>/clusters-configuration endpoint and use the returned weights when you add, delete, or rebalance replicas.
Rebalance replica weights
Use this endpoint when you want to redistribute read/write traffic across existing replicas.
curl -X PUT \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
"https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/weights" \
-d '{
"old_weights": {
"copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
"writer": {"<replica-1-name>": 100, "<replica-2-name>": 0},
"reader": {"<replica-1-name>": 100, "<replica-2-name>": 0}
},
"new_weights": {
"copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
"writer": {"<replica-1-name>": 50, "<replica-2-name>": 50},
"reader": {"<replica-1-name>": 60, "<replica-2-name>": 40}
}
}'
Add a replica
Use this endpoint to scale out horizontally and assign traffic to the new replica in one request.
curl -X POST \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
"https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas" \
-d '{
"replica_size": "4-16",
"existing_replicas": {
"old_weights": {
"copyjob": {"<replica-1-name>": 1},
"writer": {"<replica-1-name>": 100},
"reader": {"<replica-1-name>": 100}
},
"new_weights": {
"copyjob": {"<replica-1-name>": 1},
"writer": {"<replica-1-name>": 70},
"reader": {"<replica-1-name>": 80}
}
},
"new_replica": {
"copyjob": 1,
"writer": 30,
"reader": 20
}
}'
Remove a replica
Use this endpoint to scale in and move traffic away from the replica being removed.
curl -X DELETE \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
"https://api.tinybird.co/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas/<replica_name>" \
-d '{
"old_weights": {
"copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1, "<replica-3-name>": 1},
"writer": {"<replica-1-name>": 50, "<replica-2-name>": 30, "<replica-3-name>": 20},
"reader": {"<replica-1-name>": 50, "<replica-2-name>": 30, "<replica-3-name>": 20}
},
"new_weights": {
"copyjob": {"<replica-1-name>": 1, "<replica-2-name>": 1},
"writer": {"<replica-1-name>": 60, "<replica-2-name>": 40},
"reader": {"<replica-1-name>": 60, "<replica-2-name>": 40}
}
}'
Why this matters
It's an API. You can script it. That means you can wire rebalancing into your runbooks, automate scale-out from your own control plane, or standardize cluster changes across organizations.
Availability
Cluster management via API is available for dedicated infrastructure where self-serve replica management is enabled.
If you already have access to cluster management in the UI, you can now use these API endpoints with the same permissions model.
For setup details, see cluster management documentation.
