Pagination

In order to paginate through a large list response, you can use our cursor-based pagination using
the id field of a given object in the list.

A list response holds 20 objects by default, ordered ascending by ID. So, you can get to items
after the last one in the list, by taking the last item's ID and submitting it in a list request
as the value of an after URL parameter. For example:

# The first 20 contacts are returned without any pagination nor ordering params:
$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts' \
--header 'Authorization: Bearer ...' \
--header 'User-Agent: YourAppYourOrg'

# Result output:
[{"id": 1, "email_address": "[email protected]" ...}, {"id": 4, ...} ... {"id": 55, "email_address": "[email protected]", ...}]

$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts?after=55' \
  --header 'Authorization: Bearer ...' \
  --header 'User-Agent: YourAppYourOrg'

# Result output:
[{"id": 56, ...}] # There is one more record after ID 55.

The after param always acts as if you are "turning the next page". So if you order in a descending
order, you will also use after to get to the next records:

$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts?sort_order=desc' \
--header 'Authorization: Bearer ...' \
--header 'User-Agent: YourAppYourOrg'

# Result output:
[{"id": 56, ...},  {"id": 55, ...}, {"id": 4, ...}] # All contacts in descending order.

$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts?sort_order=desc&after=4' \
--header 'Authorization: Bearer ...' \
--header 'User-Agent: YourAppYourOrg'

# Result output:
[{"id": 1, ...}] # There is one more contact on the next page after ID 55.

You can also use the Pagination-Next header to get the last ID value directly:

# Example header.
Pagination-Next: 55

And you can use the Link header to get the next page directly without needing to calculate it
yourself:

# Example header.
Link: <https://localteam.myclickfunnels.com/api/v2/workspaces/3/contacts?after=55>; rel="next"

Bigger pages with per_page

For a bulk read, raise the page size up to 100 with per_page. The cursor works exactly the same
way, and the Link header's next-page URL carries the value, so a client that follows it keeps the
size it asked for:

$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts?per_page=100' \
--header 'Authorization: Bearer ...' \
--header 'User-Agent: YourAppYourOrg'

# Example header.
Link: <https://myteam.myclickfunnels.com/api/v2/workspaces/3/contacts?per_page=100&after=4812>; rel="next"

A value above 100 returns 100 records, and the cursor walk stays complete. Zero, a negative, or a
value that is not a whole number is a 422 rather than a silent fall-back to 20, so a sync that
asks for per_page=abc finds out on the first call.

One endpoint is unpaginated by default

The saved-filter registry (GET /api/v2/workspaces/:workspace_id/refine_filters) predates this
convention. Omit both after and per_page and it returns the complete registry in one payload with
no Pagination-Next header, so integrations written against the original behavior keep working.

To page it instead, send after=0 or a per_page size on the first request:

$ curl 'https://myteam.myclickfunnels.com/api/v2/workspaces/3/refine_filters?after=0' \
--header 'Authorization: Bearer ...' \
--header 'User-Agent: YourAppYourOrg'

On that endpoint after=0 is the opt-in itself rather than a row id (real ids start at 1). It
means "start at the beginning" in whichever direction sort_order asks for, so
after=0&sort_order=desc walks the registry newest-first. After the first page, follow
Pagination-Next exactly as above.