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.
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 ~500 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 meta 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 up to a maximum of 1,000. However, we recommend requesting no more than 500 results in a single API call — larger pages can result in a 502 Bad Gateway error due to memory overload while processing large amounts of data.
For example, the following request asks for 500 results:
{
"searchCriteria": {
"query": "Phoenix, AZ"
},
"options": {
"skip": 0,
"take": 500
}
}
If the take value exceeds 1,000, the request is rejected:
{
"status": {
"code": 400,
"text": "Bad Request",
"message": "Invalid request. Take option should not be greater than 1000"
}
}
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.