Credits and rate limits
Two independent limits: credits cap what you use in a month, and the rate limit caps how fast you use it.
What a credit buys
A credit is one billable unit of work. Cheap lookups cost less than expensive aggregations, so you are charged for what a query actually costs to serve rather than for how many HTTP calls you happened to make.
| Operation | Notes | Cost |
|---|---|---|
| Card lookup by id | REST or GraphQL, any game | 1 |
| Search or filter | Per page of up to 100 results | 2 |
| Card with price history | Includes the full daily series | 3 |
| Set or catalog listing | Sets, formats, rarities | 1 |
| Bulk export | Per game, per download | 250 |
| Image delivery | Never metered, on any plan | Free |
| Cached response (304) | Send If-None-Match and pay nothing | Free |
In GraphQL, each root field is billed separately. A query aliasing three games costs three searches, not one.
Per-plan allowances
| Plan | Credits / month | Credits / day | Rate limit | Overage |
|---|---|---|---|---|
| Starter | 25,000 | 2,500 credits | 60 req/min | $12 per 10,000 |
| Growth | 150,000 | 15,000 credits | 300 req/min | $6 per 10,000 |
| Scale | 750,000 | 75,000 credits | 1,000 req/min | $3 per 10,000 |
Overage costs more per credit than the plan it extends, and stops at your plan price — so the most a month can ever cost is double. If you are paying overage two months running, the next plan up is cheaper.
Response headers
Every response reports your remaining budget, so you never have to guess.
TCGGraph-Credits-Limit: 150000
TCGGraph-Credits-Remaining: 149187
TCGGraph-Credits-Reset: 1788220800
TCGGraph-Cost: 2
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299Hitting the cap
- Rate limit exceeded —
429with aRetry-Afterheader in seconds. Back off and retry. - Daily cap reached —
429until midnight UTC. The daily ceiling is a tenth of the monthly allowance on every plan, which is well clear of normal traffic and tight enough that a loop with a bug in it costs you a day rather than a month. - Monthly credits exhausted — requests keep succeeding and overage is drawn from your balance, stopping once it reaches your plan price. A runaway loop cannot produce an unbounded invoice.
- Hard cap reached —
429until the monthly reset, for accounts that opted into a cap instead of overage.
You can set a hard cap on any plan if you would rather fail than be billed. See pricing for the full breakdown.
What is never metered
- Card images from the CDN, on every plan.
- Responses served from your own cache — send
If-None-Matchand a304costs nothing. - Requests that fail with a 4xx or 5xx.