Pagination & Sorting

Search endpoints return paginated results. You control the page size, navigate through pages, and optionally sort by one or more fields.

Pagination Parameters

Include these in your search request body:

1234{
  "page": 1,
  "per_page": 25
}

Parameter	Type	Default	Min	Max	Description
`page`	integer	`1`	`1`	—	The page number to retrieve
`per_page`	integer	`25`	`1`	`250`	Number of results per page

Both parameters are optional. If omitted, the defaults apply.

Pagination Response

Every search response includes a pagination object alongside the data array:

1234567891011{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_results": 1847,
    "total_pages": 74,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Field	Type	Description
`page`	integer	Current page number
`per_page`	integer	Results per page (as requested)
`total_results`	integer	Total number of matching records
`total_pages`	integer	Total number of pages
`has_next_page`	boolean	`true` if there are more pages after this one
`has_previous_page`	boolean	`true` if there are pages before this one

Sorting

Sort results by one or more fields using the sort array:

12345{
  "sort": [
    { "field_id": "estimated_value", "direction": "desc" }
  ]
}

Key	Type	Required	Description
`field_id`	string	Yes	The field to sort by
`direction`	string	Yes	`"asc"` (ascending) or `"desc"` (descending)

Multi-column sorting

Pass multiple sort objects to sort by multiple fields. They are applied in order — the first entry is the primary sort, the second breaks ties, and so on.

123456{
  "sort": [
    { "field_id": "state", "direction": "asc" },
    { "field_id": "estimated_value", "direction": "desc" }
  ]
}

This sorts by state alphabetically, then by estimated value (highest first) within each state.

Default sort

If you omit the sort parameter, the server applies a default sort order. The default varies by endpoint but generally returns the most relevant results first.

Sortable fields

Not all fields support sorting. Use the List Fields endpoint to check which fields are available, then refer to the endpoint documentation for sorting constraints.

Attempting to sort by a non-sortable field returns a validation_error.

Iterating Through All Pages

To retrieve all results, loop through pages until has_next_page is false.

12345678910111213141516171819# Page 1
curl -X POST "https://api.v2.dealmachine.com/v1/properties/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [...],
    "page": 1,
    "per_page": 250
  }'

# Page 2
curl -X POST "https://api.v2.dealmachine.com/v1/properties/search" \
  -H "Authorization: Bearer dm_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [...],
    "page": 2,
    "per_page": 250
  }'

Performance Tips

Use smaller pages for faster responses

Smaller per_page values return faster. Use per_page: 25 for interactive UIs and per_page: 250 for batch processing.

Only fetch what you need

Use the fields parameter to request only the fields you need. Fewer fields means smaller payloads and faster responses.

Avoid deep pagination

Requesting very high page numbers (e.g., page 500) is slower than early pages. If you need to process large result sets, consider narrowing your filters instead.

Sort deliberately

Sorting by indexed fields is faster. If performance matters, avoid multi-column sorts on non-indexed fields.