> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveinspect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Pagination: Page Through Long Lists With a Cursor

> Hive Inspect API lists return up to 200 records per page. Pass the next_cursor value back as cursor to fetch the next page until it comes back null.

<Note>
  **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon. To ask for early access, message us from the chat bubble in your dashboard.
</Note>

List endpoints return one page at a time. Each response has three parts:

* `data`: the records on this page
* `next_cursor`: a value to fetch the next page, or `null` when there are no more
* `total`: how many records match your filters across all pages

## Page through a list

<Steps titleSize="h3">
  <Step title="Request the first page">
    Set how many records you want with `limit`. The default is 50 and the maximum is 200.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl "https://api.hiveinspect.com/v1/contacts?limit=200" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Pass the cursor back">
    Take `next_cursor` from the response and send it as `cursor`. Keep every other parameter the same.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl "https://api.hiveinspect.com/v1/contacts?limit=200&cursor=NEXT_CURSOR_VALUE" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Stop when the cursor is null">
    Repeat until `next_cursor` is `null`. That page is the last one.
  </Step>
</Steps>

## Things to know

* **A page can be shorter than `limit`.** With some filters a page holds fewer records even though more pages follow. Always check `next_cursor`, not the page size.
* **A cursor belongs to its request.** Use a cursor only with the same filters and the same `sort` it came from. A cursor from a different sort returns `400`.
* **Treat the cursor as opaque.** Its format can change. Pass it back exactly as you received it.
* **`total` counts every page.** It is the number of records that match your filters, not the size of this page. To get only a count, send `limit=1` and read `total`.

## Fetch several records by id

Contacts, agencies and inspections accept an `ids` parameter. Send up to 200 ids, separated by commas, to fetch them in one request:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/contacts?ids=CONTACT_ID_1,CONTACT_ID_2,CONTACT_ID_3" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

* An id that is not in your account is left out. It does not cause an error.
* Other filters still apply, so `ids` together with `role=agent` returns only the agents among those ids.
* On inspections, `ids` also returns canceled inspections. Deleted inspections need `include_deleted=true`.
* Contact stats use `contact_ids` instead of `ids`.

## Sorting

Most lists accept a `sort` parameter. Add a `-` in front for descending order, for example `sort=-scheduled_for` for the newest inspections first. Each endpoint's reference page lists the fields you can sort by.

## Sync only what changed

To keep another system in sync, store the time of your last sync and ask only for newer records with `updated_since`:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/inspections?updated_since=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This is faster than downloading everything each time, and it keeps you well inside the rate limit.

### Pick up deleted inspections

A deleted inspection drops out of the normal list, so a sync would never learn it is gone. Add `include_deleted=true` to get deleted inspections too. Each one has `deleted: true` and a `deleted_at` time:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/inspections?updated_since=2026-09-01T00:00:00Z&include_deleted=true&include_canceled=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When you see `deleted: true`, remove that inspection from your own system.

### Overlap your sync window

Start each sync a few minutes before the last one ended. A record saved while your previous sync was running can otherwise be missed. Records you receive twice have the same `id`, so they are safe to save again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.