# Pagination

The Occuspace API uses cursor-based pagination to navigate through large result sets. Cursors are more efficient and reliable than traditional page-number pagination, especially for real-time data that may change between requests.

### How It Works

When a response contains more results than the requested `limit`, the API returns a cursor in the `pagination` object that you can use to fetch the next or previous page of results. Pagination is supported on all endpoints that return lists or time-series data.

<table><thead><tr><th width="155.0546875">Field</th><th width="109.59375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>has_more</code></td><td>boolean</td><td><code>true</code> if additional results are available beyond the current page</td></tr><tr><td><code>next_cursor</code></td><td>string</td><td>Pass this value as the <code>cursor</code> parameter to fetch the next page. <code>null</code> if there are no more results.</td></tr><tr><td><code>prev_cursor</code></td><td>string</td><td>Pass this value as the <code>cursor</code> parameter to fetch the previous page. <code>null</code> if you are on the first page.</td></tr></tbody></table>

### Request Parameters

The following query parameters control pagination behavior and are supported on all paginated endpoints:

<table><thead><tr><th width="117.0859375">Parameter</th><th width="102.79296875">Type</th><th width="106.72265625">Required</th><th width="98.3203125">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>integer</td><td>No</td><td>1000</td><td>The maximum number of results to return per page. Must be between 1 and 1000.</td></tr><tr><td><code>cursor</code></td><td>string</td><td>No</td><td>-</td><td>The cursor value from a previous response's <code>next_cursor</code> or <code>prev_cursor</code> field. Omit this parameter on your first request.</td></tr></tbody></table>

### Paginating Forward

To paginate forward through results, pass the `next_cursor` value from the current response as the `cursor` parameter in your next request. Keep paginating until `has_more` is `false`.

{% hint style="info" %}
**Always check `has_more` first.** Rather than checking whether `next_cursor` is null, use `has_more` as your primary signal for whether more results are available. This is the most reliable way to detect the end of a result set.
{% endhint %}

```bash
# Step 1 — First request, no cursor needed
curl -X GET "https://api.occuspace.io/v2/locations?limit=3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": true,
#     "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0",
#     "prev_cursor": null
# }

# Step 2 — Pass next_cursor to fetch the next page
curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2MX0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": true,
#     "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2NH0",
#     "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU1OX0"
# }

# Step 3 — Continue until has_more is false
curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2NH0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": false,
#     "next_cursor": null,
#     "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0"
# }
```

### Paginating Backward

To paginate backward through results, pass the `prev_cursor` value from the current response as the `cursor` parameter in your next request. `prev_cursor` is `null` when you are on the first page of results.

```bash
# To go back to the previous page, pass prev_cursor as the cursor parameter
curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU1OX0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": true,
#     "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0",
#     "prev_cursor": null
# }
```

### Pagination With Metric Endpoints

Pagination works the same way on the Metric endpoints (`/occupancy`, `/traffic`, `/dwell_time`, `/availability`). The `limit` parameter controls how many data points are returned per page, and `cursor` is used to navigate between pages of time-series data.

```bash
# First page of occupancy data
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Next page using next_cursor from the response
curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&limit=10&cursor=eyJsb2NhdGlvbl9pZCI6MTU2MCwidGltZXN0YW1wIjoiMjAyNS0xMi0xMFQwMDowMDowMFoiLCJkaXJlY3Rpb24iOiJuZXh0In0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

{% hint style="info" %}
**Include all original parameters when paginating.** When fetching subsequent pages of metric data, always include the same `start_date`, `end_date`, and `interval` parameters alongside your `cursor`. Omitting them may produce unexpected results.
{% endhint %}

### Pagination With Child Locations

When using `include=children` on the `/locations/{id}` or `/locations/{id}/now` endpoints, the `limit` and `cursor` parameters apply to the child locations returned in `children_data`, not the parent location. The parent location is always returned regardless of pagination.

```bash
# First page of children
curl -X GET "https://api.occuspace.io/v2/locations/1559?include=children&limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Next page of children
curl -X GET "https://api.occuspace.io/v2/locations/1559?include=children&limit=5&cursor=eyJsb2NhdGlvbl9pZCI6MTU2NH0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```