Reading the Swapcard API rate limits before you build the nightly pull

The integration ticket says pull the attendee list every night and land it in the warehouse. Somebody has looked at the docs, seen a GraphQL endpoint, and estimated two days. On day one the query for 8,000 attendees comes back with an error about query cost, and nobody on the team has a mental model for what that means, because every rate limit anyone has met before was measured in requests per second.

The Swapcard API rate limits are not measured that way, and the difference changes how you write the loop. Swapcard's developer documentation prices each query by complexity and then meters those prices against a budget, which means the answer to how many calls you can make is a question about your field selection.

What the points budget actually meters

Swapcard (2026) documents a cost-based limit set "By default, this limit is set to 60,000 points per minute", with the price of a query built from a published table: "A mutation is 1,000 points, an object is 2 points, a scalar is 1 point, depth factor applied is 1.5x". A single query may cost at most 10,000 points.

Two ceilings, then, doing different jobs. The 10,000 point cap governs the shape of any one request. The 60,000 points per minute cap governs how fast you may repeat it. A pull can be legal on one and illegal on the other, and the failure modes look nothing alike: a query over the per-query cap fails immediately and always, while a loop over the per-minute cap runs fine for the first few pages and then starts failing at a point that moves depending on what else is calling the API with the same credentials.

This is the same family of design GitHub uses for its own GraphQL endpoint, where the documentation gives users "5,000 points per hour per user" and Enterprise Cloud users "10,000 points per hour" (GitHub, 2026), with a separate structural cap because "Individual calls cannot request more than 500,000 total nodes". Two vendors, two very different numbers, one shared idea: a GraphQL server cannot price a request until it has read the request, so the meter has to run on the query rather than on the verb.

What does one attendee query cost?

Price it before you write it. Take an attendee record with the fields a warehouse actually wants: identifier, first name, last name, email, company, job title and country. That is one object at 2 points plus seven scalars at 1 point each, so 9 points per attendee before any nesting.

Now ask for 8,000 of them in one query. Eight thousand objects at 2 points is 16,000 points on the objects alone, which is already 60 per cent above the 10,000 point ceiling with no fields selected at all. Add the scalars and you are at 72,000 points for a single request, seven times over the cap and above a whole minute of budget.

The arithmetic is worth sitting with, because it explains why the naive query fails on the first attempt rather than degrading. There is no page size at which 8,000 attendee objects with seven fields each fits in one request. Ten thousand points divided by 9 points per attendee is 1,111 attendees, and that is the theoretical maximum before you account for the wrapper object, the connection, and the depth factor.

Splitting 8,000 attendees into pages that fit

Round down hard. A page of 1,000 attendees costs roughly 9,000 points, leaving 1,000 points of headroom for the query wrapper and any nesting you add later. Eight pages covers the 8,000 records.

Against the minute budget, each page spends 9,000 of the 60,000 points available, so six pages fit inside one minute with 6,000 points spare. Sixty seconds divided by 6.67 pages per minute puts one request every nine seconds as the sustainable pace, and the whole 8,000 record pull finishes in about 72 seconds of wall clock.

Compare that with the version somebody would write without reading the limits: 80 pages of 100 records, each costing about 900 points, which is 72,000 points in total and a pull that cannot complete inside one minute either. Same total cost, eight times the round trips, and a much higher chance of tripping the per-minute cap during a burst. Page size is a lever on request count and barely a lever on points spent, so the correct move is the largest page that fits comfortably under 10,000 points.

Scale it once more, because a portfolio pull is where this stops being academic. Forty thousand attendees across five events at 9 points each is 360,000 points, which is six full minutes of budget with nothing else running. If your nightly window also refreshes sessions, exhibitors and meetings against the same credentials, the budget is shared and the sum is what matters. Which pages you request and in what order sits with how to page a feed that is still moving.

Why is the depth factor the part that catches people?

Because it turns a small convenience into a large bill without changing the number of records you asked for.

Suppose that instead of pulling attendees flat, you pull events, then attendees inside each event, then that attendee's meetings inside each attendee. The record count has not changed. The nesting has, and Swapcard's documented depth factor of 1.5x means the deeper selection prices higher than the same fields would have priced at the top level. Three levels of nesting on a query that was comfortably under the cap can put it over.

The honest advice is to measure rather than predict. The exact application of a depth factor to a specific query shape is the kind of thing that is easy to get wrong on paper and trivial to establish empirically: send the query with a page size of 1, read the cost header, and multiply. That gives you a real price per record for your real field selection, which is worth more than any estimate in a design document.

Nesting also runs into a separate ceiling. Swapcard documents a maximum of 20 levels of nested objects, plus a maximum of 50 aliases and 2,000 tokens in a single query. The alias cap is the one that bites teams who have discovered the trick of aliasing twenty small queries into one request to save round trips. That trick works until the aliased request either exceeds 50 aliases or, far sooner, exceeds 10,000 points, and the request body itself must not exceed one megabyte.

Reading the headers instead of guessing

Swapcard returns five response headers: X-RateLimit-Cost, X-RateLimit-Used, X-RateLimit-Remaining, X-RateLimit-Limit and X-RateLimit-Reset, the last carrying the epoch time at which the window resets. GitHub's GraphQL endpoint exposes the same shape under lowercase names.

Log all five on every call, into a table, with the query name and the page number. It costs almost nothing and it converts the entire class of "the nightly pull failed sometimes" tickets into a chart. You get the real cost of each query shape rather than your estimate of it, you get the actual remaining budget at the moment things started failing, and you get the reset time, which tells you whether waiting is the correct response or whether you are simply asking for too much.

The header to act on during a run is X-RateLimit-Remaining. A pull that checks it before each page and pauses until the reset when it drops below the cost of the next page will never trip the limit, which is a considerably better position than retrying after a failure. What to do once you are already being refused is a different discipline, covered in a backoff strategy that holds up on the busiest day of the sale.

Where this stops

Costing a query tells you what the API will charge you. It tells you nothing about whether the data is any good, and there are two places where careful budgeting still leaves you short.

The first is that the documented default is a default. Swapcard notes that a temporary change to the rate limit can be applied without notice for abuse prevention, so a pull sized to consume 59,000 of 60,000 points per minute is a pull with no margin. Design for roughly half the published budget and you have somewhere to go when a second integration appears on the same credentials, which it will.

The second is that field selection drives both cost and completeness, and those pull in opposite directions. The cheapest query is the one that asks for three columns, and the query your warehouse needs in eighteen months is the one that asked for fifteen. Trimming fields to fit the budget is a decision to re-run the whole extraction later, and re-running it later means paying for history you could have taken the first time. Pull the wide version at a slow pace rather than the narrow version at a fast one, and if the same reasoning needs applying to another meetings platform, the equivalent pull against Brella has its own shape.

The concrete first step takes fifteen minutes. Send your intended attendee query with a page size of 1, read X-RateLimit-Cost off the response, multiply by your record count, and divide by 60,000. That gives you the number of minutes your nightly pull will occupy of the whole budget, and if it is above two, the design needs revisiting before anyone writes the scheduler. The rest of what an integration owes the stack around it is covered across this cluster.