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:

LimitWhat it counts
Burst rateCalls per second, per region. It is the plan rate and always applies.
Sustained rateThe 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

MethodOperatorBlade RunnerNexus
BurstSustainedBurstSustainedBurstSustained
sendTransaction (staked)1 rps0.25 rps5 rps2 rps20 rps5 rps
getSignaturesForAddress (older signatures)————30 rps2 rps
getTransaction (older transactions)————100 rps3 rps
getTransactionsForAddress (signatures)————30 rps3 rps
getTransactionsForAddress (full)————5 rps3 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

RequestGoes upstream
sendTransaction on a staked hostnameThe staked path. See Staked endpoints.
getSignaturesForAddressSignatures past the region's ledger window. See Historical lookups.
getTransactionTransactions past the region's ledger window. See Historical lookups.
getTransactionsForAddressAddress history past the region's ledger window. See Historical lookups.
getBlockBlocks 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.

DayAllowed 24-hour average
Start12 per second
110.6 per second
29.3 per second
38.2 per second
47.3 per second
56.4 per second
65.7 per second
75 per second

What happens when a key is slowed

Calls over the key's allowed rate are slowed, never stopped.

RequestOver 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.
getTransactionsForAddressWaits 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.

On this page