Pagination and list endpoints
Every list endpoint returns one page of results and a marker that points to the next page. Your client follows the marker until has_more turns false.
The list envelope
{
"object": "list",
"url": "/v1/charges",
"has_more": true,
"data": [
{ "id": "ch_3Rsx4dDtWMrPDtgt1", "object": "charge", "amount": 2120 }
]
}
| Field | Meaning |
|---|---|
data | The objects on this page. |
has_more | true when another page exists. |
url | The endpoint path that produced this page. |
The newest object appears first. Order stays stable across pages because the cursor points at an object, not at a numeric offset.
Set the page size
limit controls the page size and accepts 1 to 100. The default is 10, which suits an interactive dashboard and wastes round trips in a batch job.
curl -s -G https://api.stripe.com/v1/charges \
-u "$STRIPE_SECRET_KEY:" \
-d limit=100 | jq '.data | length, .has_more'
A larger page reduces request count and total latency. It also raises the memory cost and the blast radius of a failed request, so 100 fits most sync jobs.
Follow the cursor
Read the id of the last object on the page and pass it as starting_after. Repeat until has_more is false.
curl -s -G https://api.stripe.com/v1/charges \
-u "$STRIPE_SECRET_KEY:" \
-d limit=100 \
-d starting_after=ch_3Rsx4dDtWMrPDtgt1
async function listAllCharges() {
const charges = [];
let startingAfter;
while (true) {
const url = new URL("https://api.stripe.com/v1/charges");
url.searchParams.set("limit", "100");
if (startingAfter) url.searchParams.set("starting_after", startingAfter);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});
if (!response.ok) throw new Error(`Stripe returned ${response.status}`);
const page = await response.json();
charges.push(...page.data);
if (!page.has_more) break;
startingAfter = page.data.at(-1).id;
}
return charges;
}
The official libraries ship an auto-pagination helper. Use stripe.charges.listAutoPaging() in Node, stripe.Charge.listAutoPaging() in Java, or stripe.charge.list(auto_paging=True) in Python instead of writing the loop.
Filter on the server
A filter narrows the result set before Stripe paginates it. Filtering in the client after the fetch forces you to read the whole collection.
| Filter | Example | Scope |
|---|---|---|
| Time range | created[gte]=1735689600&created[lt]=1738368000 | Charges, refunds, balance transactions |
| Status | status=available | Balance transactions |
| Customer | customer=cus_QyJ8... | Charges, payment intents, invoices |
| Payout | payout=po_1N... | Balance transactions in one payout |
Combine filters to keep a reconciliation job inside one page. A daily job that reads yesterday's charges with a created range rarely needs a second page.
Why the cursor beats an offset
Offset pagination asks for page 2 at row 100. The database shifts when a new charge arrives between requests, so row 100 becomes row 101 and one record appears twice. A cursor names the last object you saw, so a new charge lands ahead of the cursor and never disturbs the walk.
Two behaviors follow from the design:
- No page number. Stripe offers no
page=2and nototal_count. Count results with your own store if you need a total. - No random access. Jump forward with
starting_afterand backward withending_before. Neither gives you page 40 of 200.
Search endpoints paginate differently
The search endpoints accept a query string and return a next_page token instead of an object cursor.
curl -s -G https://api.stripe.com/v1/charges/search \
-u "$STRIPE_SECRET_KEY:" \
-d query='amount>1000 AND status:"succeeded"' | jq '.next_page'
Pass the token back as page to read the next page. A response with next_page: null marks the end. Search has no starting_after, so keep the two pagination models apart in your client.
| Endpoint type | Cursor parameter | End signal |
|---|---|---|
| Standard list | starting_after | has_more: false |
| Search | page | next_page: null |
Keep bulk reads inside rate limits
A backfill over a year of charges can issue thousands of requests. Spread the load and back off when Stripe pushes back.
- Read one page at a time. Parallel walks over the same collection trip the concurrency limit.
- Honor the
Retry-Afterheader on a429. See Errors and retries. - Cache the last cursor in durable storage so a restart resumes instead of starting over.
- Prefer a narrow
createdrange over a full-collection walk.
Next steps
- Expanding nested objects to enrich a page without extra requests.
- Errors and retries for the backoff policy behind bulk reads.
- Retrieve a balance transaction for the attribute list behind each row.