Upstream limits
Staked sends and lookups past a region's ledger window have a burst rate and a sustained rate on each plan. A key over its sustained rate is slowed, never cut off.
Staked sends and lookups past a region's ledger window go upstream. For these, each plan has two limits:
| Limit | What it counts |
|---|---|
| Burst rate | Calls per second, per region. It is the plan rate and always applies. |
| Sustained rate | The key's average over the last 24 hours, all regions together. Only calls that go upstream count. |
A key at or under its sustained rate is never slowed. A key over it is slowed step by step, and never cut off.
Burst and sustained rates
| Method | Operator | Blade Runner | Nexus | |||
|---|---|---|---|---|---|---|
| Burst | Sustained | Burst | Sustained | Burst | Sustained | |
sendTransaction (staked) | 1 rps | 0.25 rps | 5 rps | 2 rps | 20 rps | 5 rps |
getSignaturesForAddress (older signatures) | — | — | — | — | 30 rps | 2 rps |
getTransaction (older transactions) | — | — | — | — | 100 rps | 3 rps |
getTransactionsForAddress (signatures) | — | — | — | — | 30 rps | 3 rps |
getTransactionsForAddress (full) | — | — | — | — | 5 rps | 3 rps |
Burst is per region. Sustained is the 24-hour average, all regions together. Both getTransactionsForAddress modes share one sustained rate.
getBlock for older blocks has a monthly allowance instead. See Cube Runner limits.
Which requests go upstream
| Request | Goes upstream |
|---|---|
sendTransaction on a staked hostname | The staked path. See Staked endpoints. |
getSignaturesForAddress | Signatures past the region's ledger window. See Historical lookups. |
getTransaction | Transactions past the region's ledger window. See Historical lookups. |
getTransactionsForAddress | Address history past the region's ledger window. See Historical lookups. |
getBlock | Blocks no region's cache or ledger holds, from long-term storage. See Long-term storage. |
How a key is slowed
- A key over its sustained rate is never cut at once. Its allowed 24-hour average goes down by the same percentage each day for 7 days, until it reaches the sustained rate.
- The allowed average is shared out between regions by where the key's calls go. Every region keeps at least 0.1 calls per second.
- A slowed key keeps its burst rate. It can save up to 1 hour of its allowed rate for a burst.
- When the key's 24-hour average stays at or under its sustained rate for 6 hours in a row, its limit comes back step by step.
Example: a key averages 12 calls per second, and its sustained rate is 5 per second.
| Day | Allowed 24-hour average |
|---|---|
| Start | 12 per second |
| 1 | 10.6 per second |
| 2 | 9.3 per second |
| 3 | 8.2 per second |
| 4 | 7.3 per second |
| 5 | 6.4 per second |
| 6 | 5.7 per second |
| 7 | 5 per second |
What happens when a key is slowed
Calls over the key's allowed rate are slowed, never stopped.
| Request | Over the allowed rate |
|---|---|
sendTransaction (staked) | Still sent, from constant-k's own nodes instead of the staked path. See When a staked send falls back. |
getSignaturesForAddress (older signatures) | Waits up to 3 s for the key's next turn. If the next turn is later, only the signatures the region's own ledger holds. No error. |
getTransaction (older transactions) | Waits up to 3 s for the key's next turn. If the next turn is later, null. No error. |
getTransactionsForAddress | Waits up to 5 s for the key's next turn. If the next turn is later, HTTP 429 with code -32005. The Retry-After header and error.data.retry_after give the seconds to the next turn. |
Your rates
The Upstream section of My Account shows, for each API key and method:
- A bar for each region: your rate over the last minute against your burst rate, with a mark at your 24-hour average.
- Your plan's sustained rate.
- A graph of your use over the past 24 hours, one line per region.
- When a key is slowed: a mark at its allowed 24-hour average on each bar, an alert, and a graph of the 7-day schedule that shows where the key is now, with a day-by-day table.
Cube Runner usage shows as one block per region: the blocks used this month against the plan's monthly allowance.