Some top-level API resource have support for retrieval via “search” API methods. For example, you can search charges, search customers, and search subscriptions.
Stripe’s search API methods utilize cursor-based pagination via the page request parameter and next_ response parameter. For example, if you make a search request and receive "next_ in the response, your subsequent call can include page=pagination_ to fetch the next page of results.
Our client libraries offer auto-pagination helpers to easily traverse all pages of a search result.
Search request format
- queryrequired
The search query string. See search query language.
- limitoptional
A limit on the number of objects returned. Limit can range between 1 and 100, and the default is 10.
- pageoptional
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the
next_value returned in a previous response to request subsequent results.page
Search response format
- objectstring, value is "search_result"
A string describing the object type returned.
- urlstring
The URL for accessing this list.
- has_
moreboolean Whether or not there are more elements available after this set. If
false, this set comprises the end of the list. - dataarray
An array containing the actual response elements, paginated by any request parameters.
- next_
pagestring A cursor for use in pagination. If
has_is true, you can pass the value ofmore next_to a subsequent call to fetch the next page of results.page - total_
countoptional positive integer or zero The total number of objects that match the query, only accurate up to 10,000. This field isn’t included by default. To include it in the response, expand the
total_field.count
{ "object": "search_result", "url": "/v1/customers/search", "has_more": false, "data": [ { "id": "cus_4QFJOjw2pOmAGJ", "object": "customer", "address": null, "balance": 0, "created": 1405641735, "currency": "usd", "default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5", "delinquent": false, "description": "someone@example.com for Coderwall", "discount": null, "email": null, "invoice_prefix": "7D11B54", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": { "foo": "bar" }, "name": "fakename", "next_invoice_sequence": 25, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none", "test_clock": null } ]}Our libraries support auto-pagination. This feature allows you to easily iterate through large lists of resources without having to manually perform the requests to fetch subsequent pages.
Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard.
To expedite the resolution process, provide the request identifier when you contact us about a specific request.
Each major release, such as Acacia, includes changes that aren’t backward-compatible with previous releases. Upgrading to a new major release can require updates to existing code. Each monthly release includes only backward-compatible changes, and uses the same name as the last major release. You can safely upgrade to a new monthly release without breaking any existing code. The current version is 2025-08-27.basil. For information on all API versions, view our API changelog.
You can upgrade your API version in Workbench. As a precaution, use API versioning to test a new API version before committing to an upgrade.
This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account.
The top-level available and pending comprise your “payments balance.”
Related guide: Balances and settlement time, Understanding Connect account balances