Skip to main content

Pagination

List endpoints return one page of records in data and paging details in page:

"page": {
  "has_more": true,
  "next_cursor": "EXAMPLE_OPAQUE_CURSOR",
  "next_page_url": "https://api.fieldtask.example/public/v1/jobs?page_size=25&cursor=EXAMPLE_OPAQUE_CURSOR"
}

Follow next_page_url​

The simplest way to read every page is to request page.next_page_url until it's null, sending the same Authorization header each time. The URL keeps your page size, ordering and filters.

url = f"{API_ORIGIN}/public/v1/customers?page_size=100"
while url:
    body = requests.get(url, headers=headers, timeout=30).json()
    process(body["data"])
    url = body["page"]["next_page_url"]

Page size and ordering​

  • page_size is 1–100. The default is 25.
  • ordering is created_at (oldest first, the default) or -created_at (newest first). Records created at the same moment are ordered by ID.

Some lists also have filters, documented on each endpoint.

Cursors​

If you build URLs yourself, pass page.next_cursor as the cursor parameter.

  • Treat cursors as opaque. Don't parse, store long-term or construct them.
  • Keep page_size, ordering and every filter unchanged while following a cursor. A cursor only works with the query, connection and permissions that produced it; otherwise the response is 400 invalid_cursor.
  • Cursors expire within 24 hours.
  • To change the query, start again without a cursor.

Lists are live​

Pages show current data, not a snapshot. A record created or changed while you page through may appear on a later page or not at all. To keep another system in sync, use the event feed or webhooks rather than repeatedly listing everything.

MCP list tools​

MCP list tools take the same page_size, ordering and cursor arguments and return the same page object. FieldTask tells AI clients to follow pages before concluding that a record doesn't exist.