Plan your API usage: polling and streaming request math

This API meters plain requests. Each API call is one request, not a credit, which makes the arithmetic simple enough to do before you write any code. Doing it first can change which design you choose, because the two obvious designs have very different monthly costs.

The plans

Limits apply across all keys on an account, so a test script and a production job draw from one allowance. Valid authenticated requests count even if no rows match or a dataset is unavailable, and invalid queries authenticated before validation also count. A failing loop therefore spends allowance just as fast as a working one.

Polling, worked through

One page every five minutes is 8,640 requests in a thirty-day month. That fits inside Developer with room to spare, and it is far beyond Free. Free at 500 requests a month works out to about one page every 86 minutes, which suits exploration and occasional batch reads.

The limit parameter accepts up to 100 rows per page, so requesting the largest page you can use is usually the cheapest change you can make. Reading changes with the after cursor rather than refetching projections reduces the number of pages further. There is no conditional request to lean on: the API sets no ETag, so a repeat read always counts.

Streaming, worked through

Each stream connection lasts at most 55 seconds and costs one metered request. A client that reconnects without a gap makes about 47,128 requests in a thirty-day month. That is most of the Production allowance of 50,000, and it would use the Developer allowance of 10,000 in about 6.4 days.

So on Developer, plan the stream as something you connect to in windows, such as around the hours your product is busy, and catch up from your saved cursor afterward. The saved cursor means a gap between connections costs you latency, and it does not lose changes unless the cursor is later purged.

When you hit a limit

A 429 means the account quota was reached. Wait for the next UTC minute, day or calendar-month boundary for your account contract, then try once. The signed-in dashboard shows current usage and the reset time. It reads them with a session cookie, so a server job holding only an API key should count its own requests.

Before you pick a plan

• Count pages per run and runs per month, and add every environment that shares the account.
• Decide whether you need delivery at all. Streams start at Developer, and signed webhooks need Production.
• Cache shared reads on your server rather than calling the API once per end user.
• Check the pricing page for current terms before relying on these numbers.