Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

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, 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.

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.