# Pagination & sync

Lists such as `GET /v1/leads` return one page:

```json
{ "object": "list", "data": [ { "object": "lead", "id": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy" } ], "has_more": true, "next_cursor": "lead_hz5ikyc3pnhkrhlb6p7elkx2qy" }
```

| Parameter | Meaning |
|---|---|
| `limit` | 1–100 items per page, default 25. |
| `starting_after` | An id from the previous page (use `next_cursor`): the next, older page. |
| `ending_before` | The first id of the current page: the newer page before it. |

Order is always newest first (`created_at`, then `id`), so pages stay stable while new leads arrive. `next_cursor` is the id to send as `starting_after` for the next, older page; it is `null` on the last page. With `ending_before`, `has_more` says whether there are still newer leads; to go further back, send the first id of that page as `ending_before` again.

- An id that is not one of your leads → [`400 invalid_cursor`](https://docs.creator-guard.com/errors/#invalid_cursor), with the parameter's name in `error.parameter`.
- `starting_after` and `ending_before` together, a `limit` outside 1–100, or the same parameter twice → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field).

## Filters

`GET /v1/leads` takes these filters; they combine with AND. Any other parameter → [`400 unknown_parameter`](https://docs.creator-guard.com/errors/#unknown_parameter), with its name in `error.parameter`. An invalid filter value → [`400 invalid_field`](https://docs.creator-guard.com/errors/#invalid_field).

| Filter | Example | Matches |
|---|---|---|
| `stage` | `stage=draft` | One [stage](https://docs.creator-guard.com/lead-lifecycle/). |
| `external_id` | `external_id=crm-000042` | Your reference, exactly. |
| `creator_ref` | `creator_ref=CR-1047` | Her creator number (`1047` works too). |
| `instagram_handle` | `instagram_handle=miacreates` | Normalised like on create, so `@MiaCreates` or a profile link find her too. |
| `q` | `q=mia` | Part of her name, ignoring case. |
| `created_since`, `updated_since` | `updated_since=2026-10-09T08:00:00Z` | RFC 3339 timestamps, inclusive. |
| `has_blockers` | `has_blockers=true` | Leads that still have (or, with `false`, have no) [blockers](https://docs.creator-guard.com/lead-lifecycle/#next-actions). |

## Keeping in sync

Every lead has `updated_at`, the last change to the lead or her listing. Remember the time of your last sync and ask for `GET /v1/leads?updated_since=<that time>`, following `next_cursor` with `starting_after` until `has_more` is `false`. Take the new sync time from **before** the first request, so a change during the sync is picked up next time.

A few stage changes can happen without a change to `updated_at` (an offer simply running out, for example), so re-read leads that are still in progress once a day as well. Or let us tell you: [webhooks](https://docs.creator-guard.com/webhooks/) deliver every change within seconds, and `GET /v1/events` keeps them for 30 days.
