API Payload Calculator
Records times bytes — the response on disk, on the wire, and split across the pages you should be sending.
API Payload Calculator
Results recalculate instantly on every keystroke. Nothing you type is transmitted.
What this result does not account for
- Average-row arithmetic — no schema is parsed
- Wire estimate at a conservative 4:1, named
In short: Ten thousand records at 800 bytes each answer with 8.000000 MB of JSON. On the wire, gzip's repeated-key squeeze at a conservative 4:1 lands it near 2.000000 MB — JSON routinely compresses more. Split at 100 records a page it becomes 100 requests of 80.000000 KB each, which is the shape clients actually want: pages small enough to fail cheaply and render early.
Formula
MB = records × bytes ÷ 1,000,000 ··· wire ≈ MB ÷ 4 ··· pages = records ÷ page, rounded up
A JSON payload is records times serialized bytes — and its two real-world modifiers are compression and pagination. Repeated keys make JSON gzip beautifully, commonly 4:1 to 10:1; this page plans the conservative 4:1 so the wire estimate is a floor, not a hope. The page split exists because unbounded answers fail badly: documented APIs default to 20–100 records and hard-cap the maximum, keeping each response inside what a phone line and a patient user forgive.
Worked Example
- Enter the records one full answer would carry.
- Enter the average serialized bytes per record.
- Enter the page size you would document.
- Read the disk size, the wire size and the pages.
Defaults: 10,000 × 800 → 8.000000 MB, near 2.000000 MB on the wire, 100 pages of 80.000000 KB. Drive a million records at 1,200 bytes → 1,200.000000 MB unpaginated — the case for pages.
Strengths & Limits Of This Model
Where this engine is strong
- Disk, wire and page views from one entry
- Over-fetching tax named in doctrine
Where it stops
- Envelope and metadata overhead not modeled
Practical Use Cases
Endpoint design
page sizes that fail cheaply
Mobile budgets
what one sync costs a phone
Cost reviews
egress per thousand responses
Methodology & Editorial Standards
Computation runs in IEEE-754 double precision at full internal precision; rounding to two decimal places occurs strictly at the display layer, so no cumulative drift enters the result. All monetary outputs use accounting presentation — grouped thousands, two decimals, negatives in parentheses — so figures can be transcribed directly into a model or working paper. Division-by-zero and out-of-domain inputs return an em-dash rather than a misleading number.
This engine was reconciled against an independent reference implementation and hand-verified for the worked example above before release. Our full five-stage review process is published on the About Us page.
Disclaimer. This calculator is provided for informational and modelling purposes only and does not constitute financial, tax, legal, medical, or engineering advice. Verify all figures with a qualified professional before acting on them.
API Payload Calculator — 8 Expert FAQs
8 analyst-written answers to the questions practitioners actually ask — optimised for voice and answer-engine retrieval.
How big should an API response be?
Keep one page inside what a mobile line and a patient user forgive — roughly a megabyte or two uncompressed is a common ceiling. At 5–20 KB a record, that means tens of records for complex payloads and a few hundred for flat ones. The calculator turns your record size into the page count that stays inside the budget.
What page size should my API default to?
Published APIs cluster at 20–100 records per page with a hard maximum: GitHub defaults 30 and caps 100, Stripe defaults 10 and caps 100, Zendesk fixes 100. The cap matters as much as the default — it stops one consumer's unlimited page from becoming everyone's slow night.
How much does gzip shrink JSON?
Routinely 75–90% — a 4:1 to 10:1 squeeze — because the keys repeat on every record and gzip feeds on repetition. This page plans the conservative 4:1 so the wire figure is a floor. Serve the compressed bytes and let the client decompress; the CPU cost is usually far cheaper than the bytes saved.
Why is my payload bigger than records × bytes?
Serialization overhead: envelope objects, error wrappers, pagination metadata, ISO timestamps as strings, and numbers rendered as text all add bytes the row estimate missed. Measure a real response, divide by the record count, and enter that average — the page's arithmetic only works on honest inputs.
Should I paginate or just filter better?
Both: pagination bounds the blast radius of one request, filtering and field selection shrink every page. Over-fetching — returning every column to render three — is the silent payload tax, and clients on cellular pay it on every sync. Start with the page split here, then trim the record itself.
How do payloads affect rate limits?
Directly: bigger answers mean more pages, and every page is a request against the same quota. Shrinking records or raising the page size cuts the request count at the same data volume. The rate limit page prices the budget; this page supplies the demand side of that division.
What is a normal bytes-per-record for JSON APIs?
Flat records with a handful of fields land near 200–800 bytes; business records with nesting run 1–5 KB; deeply embedded documents can pass 20 KB. Measure yours from a real response rather than guessing — the field is free-entry for exactly that reason.
Does compression change the page size advice?
On the wire, yes — a 4:1 squeeze makes a 2 MB page travel like 500 KB, so some APIs ship larger pages to cut request overhead. But the client still parses and holds the full page in memory, so mobile budgets should stay set on the uncompressed size. The wire read and the page read answer different constraints on purpose.