Property Search API endpoint can potentially return thousands of matched properties. To avoid extraneous network load, this endpoint limits the number of records returned in the response and charges only for properties that are retrieved.
Each Property Search response reports two counts in results.meta.results. For the asynchronous endpoint, the counts are in the webhook payload. resultsFound is the number of properties that match your search. resultCount is the number of properties that were returned. When take is greater than 0, you are billed for the properties in resultCount, not for resultsFound. Contact enrichment ("skipTrace": true) adds a separate charge.
BatchData supports three paging approaches, and the right one depends on how many properties you need and whether you'll page across multiple requests over time:
You need to... | Use |
Retrieve fewer than ~100 properties in a single call |
|
Page through tens of thousands of results in one script run | Cursor pagination (read the full guide) |
Deliver properties incrementally across days, weeks, or months without re-delivering duplicates | Search Sessions (read the full guide) |
đĄ Recommendation: If you are paginating today with skip and take deeper than ~1,000 results, switch to cursor pagination. It is stable against background index updates, avoids duplicate billing on deep pages, and is faster.
The rest of this guide covers the original skip / take pattern, which remains supported.
How skip / take works
Property search API end-point, by default, limits the number of records returned in the response. In order to retrieve a small number of properties in one or two pages, the skip and take request parameters are used to implement paging.
Parameters
skipâ bypasses a specified number of search results, then returns the remaining results. Default value is0.takeâ specifies the number of search results to return. Default value is25.
Make a paginated request and iterate through the pages
You can set the number of results to return per page using the take parameter. If you don't specify take, the endpoint uses its default page limit of 25 results per page. You can also set other parameters in this request to narrow down your results.
The following example asks the property search endpoint for all properties that belong to AZ state, with a take of 25 properties per page:
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 0,
"take": 25
}
}
Since only 25 properties are returned at a time in your response, you can get the rest of the items in batches using the skip parameter in subsequent requests:
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 25,
"take": 50
}
}
đĄ Use the resultsFound parameter inside the response results.meta.results object to check the total count of matched properties for the given request.
Change the number of results for a specific page
Use the take parameter to change the page size. The maximum is 100 on the synchronous endpoint POST /api/v1/property/search, and 1,000 on the asynchronous endpoint POST /api/v1/property/search/async. If you need more than 100 properties from a single call, use the asynchronous endpoint, which delivers its results to a webhook.
For example, the following request asks for 25 results:
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 0,
"take": 25
}
}
If the take value exceeds the maximum for the endpoint you called, the request is rejected:
{
"status": {
"code": 400,
"text": "Bad Request",
"message": "The options.take must not be greater than 100."
}
}
When skip / take becomes a problem
The skip / take pattern works against the live property index. As BatchData ingests updates, the document at skip: 1000 can shift position â sometimes off the end of one page, sometimes onto the front of the next. The deeper your skip, the worse it gets:
A property that drifts across a page boundary gets returned (and billed) on two pages.
A property that shifts the other way can slip between pages and be missed.
The engine must count past every skipped row, so deep
skipvalues are meaningfully slower.
This is why we recommend cursor pagination for any paging run that goes deeper than ~1,000 results. The full guide is at Incremental Property Search: Cursor Pagination & Search Sessions.