Cluster management is now scriptable

September 2026 update: Cluster Management now covers workload observability, UI-based capacity changes, and the complete resize workflow. Read Cluster Management: keep the controls, skip the cluster ops for the current product overview. This article covers the original Organizations API release.

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}/weights to request a manual rebalance.
POST /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas to 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.

All mutation requests require an old_weights field to prevent conflicts from concurrent modifications. Fetch the current weights from GET /v0/organizations/{organization_id}/clusters immediately before adding, deleting, or rebalancing replicas. The /clusters-configuration endpoint lists available regions, replica sizes, and roles. It does not return current weights.

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.