# 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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.occuspace.io/api-reference/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.