Querying API Results with Parameters

Use query parameters to filter, sort, and page through GET request results from the Deliverect API.

Query parameters

Use the parameters below when you only need specific data from a GET request. For larger data sets, use cursor to keep a consistent sort order across paged responses.

Parameter	Purpose	Example
`where`	Pass a string containing a JavaScript expression.	`/locations?where={"account":"5f327*****f5cd5"}`
`max_results`	Set the maximum number of results to return. The maximum value is `500`. If you do not set this parameter, the API returns `25` results.	`?max_results=500`
`sort`	Specify the order in which the query returns results. Add `-` for descending order, such as `sort=-_created`. Omit `-` for ascending order, such as `sort=_created`.	`?sort=-_created`
`cursor`	Page through results from the same cursor point.	`?cursor=new`
`$eq`	Match records where the specified field is equal to a specified value.
`$gte`	Match records where the specified field is greater than or equal to a specified value.	`"$gte": "YYYY-MM-DDTHH:mm:ss.SSSSSSZ"`
`$lte`	Match records where the specified field is less than or equal to a specified value.	`"$lte": "YYYY-MM-DDTHH:mm:ss.SSSSSSZ"`
`$size`	Match an array with a specified number of elements.	`{"$size": 5}`
`$in`	Match records where the specified field is equal to any value in the specified array.	`"$in": [1, 2]`
`$ne`	Match records where the specified field is not equal to a specified value.	`"$ne": "5be9*********46d4"`
`$exists`	Filter records based on whether a value exists.	`"$exists": true`

Cursor

When you send a query that returns paged results without sorting, Deliverect returns this warning:

{
  "warning": "For more correct paged results, please use sort, cursor or preference"
}

When you page through results, the database may not always return data in the same order. You can use ?sort=-_created to return a consistent order, but Deliverect recommends &cursor=new for more reliable pagination.

Here is an example Get Locations query:

GET https://api.deliverect.com/locations?where={"account":"61*********34"}&cursor=new&max_results=500

The first page of results includes a cursor ID in the _meta object:

{
  "_meta": {
    "page": 1,
    "max_results": 500,
    "total": 584,
    "cursor": "e8c9b36f***ccfbeff08fe"
  }
}

Pass this ID as &cursor={CURSOR_STRING_FROM_META} in subsequent calls to retrieve data from the same cursor point.

To page through to the next set of results, send the next request with the cursor ID and page=2:

GET https://api.deliverect.com/locations?where={"account":"61******34"}&cursor=e8c9b36f****eff08fe&max_results=500&page=2