Rate limits + tokens

Two limits: tokens per month (your plan's allowance) and tokens per minute (your throttle).

Two limits

Every plan has:

Monthly token quota — total tokens you can spend in a billing cycle
Per-minute throttle — max tokens-per-minute burst allowed

Hit either and you get a 429 response with a Retry-After header.

Plan tiers

Plan	Price	Tokens / month	Throttle (TPM)
Free	$0	1,000	5
Starter	$49/mo	864,000	20
Growth	$119/mo	2,592,000	60
Pro	$429/mo	10,800,000	100
Scale	$819/mo	21,600,000	100
Business	$1,399/mo	43,200,000	100
Enterprise	$2,339+/mo	86.4M+	100

Throttle caps at 100 TPM in 2026 due to current upstream limits. Higher TPM ships when our backend supports it; talk to sales for early access.

Token costs per call

Call	Tokens
Base lookup (price history + stats + Bucket-1 facts + computed marketplace fees)	1
+ `include_cross_retailer` (cached cells for all retailers we have for this UPC, read-only)	+2
+ `include_seller_context` (live restriction + WFS eligibility state)	+3
+ `include_offers_reviews` (live sellers + review summary + top 5 reviews)	+5
`?retailer=<r>` (anchor response to one retailer)	1
`?retailer=<r>&force_refresh=true` (anchor + fresh scrape — only way to force fresh data)	1

Marketplace fees (referral_fee_usd, wfs_fee_usd) are computed from public rate cards and ride FREE on the base call — same model as Keepa's referralFeePercentage. include_seller_context pays only for the live-state fields (is_restricted, WFS eligibility) that require a richer upstream pull.

How throttle works

Sliding-window per minute. We allow brief bursts up to 2x the throttle for short periods, then enforce strict limits. Heavy bulk-loaders should pace themselves at 80% of their plan's throttle to leave headroom.

Response headers

X-RateLimit-Tokens-Remaining: 998     # tokens left this billing cycle
X-RateLimit-Throttle-Limit: 60        # max TPM
X-RateLimit-Throttle-Remaining: 47    # TPM remaining now
X-RateLimit-Reset: 2026-06-01T00:00Z  # when monthly quota resets

What happens when you exceed

Both limits return 429 Too Many Requests. Different Retry-After semantics:

Throttle — Retry-After is a few seconds. Back off and retry.
Monthly quota — Retry-After is the next renewal date. Either upgrade or wait.

Quota-exceeded calls do NOT auto-charge overage; we fail closed. If you want to pay for spillover, contact sales or upgrade plan.

Best practices

Check X-RateLimit-Tokens-Remaining after each call to track burn rate
For batch jobs, throttle yourself at 80% of plan TPM to leave headroom for ad-hoc calls
Cache responses client-side when appropriate (titles, brands, images rarely change)
For routine lookups, the base call (1 token) already includes price history, stats, Bucket-1 facts, and computed marketplace fees — only add include_offers_reviews=true when you need live sellers or full review data
Reseller workflows usually want include_cross_retailer=true&include_seller_context=true (6 tokens) — the full per-retailer + restriction + WFS picture