Pagination & sync
Lists such as GET /v1/leads return one page:
{ "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, with the parameter's name inerror.parameter. starting_afterandending_beforetogether, alimitoutside 1–100, or the same parameter twice →400 invalid_field.
Filters
GET /v1/leads takes these filters; they combine with AND. Any other parameter → 400 unknown_parameter, with its name in error.parameter. An invalid filter value → 400 invalid_field.
| Filter | Example | Matches |
|---|---|---|
stage |
stage=draft |
One stage. |
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. |
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 deliver every change within seconds, and GET /v1/events keeps them for 30 days.