Skip to content
Build with Mammoth: open the docs menu

Mammoth API pagination

Almost every list endpoint pages with limit and offset. A handful use a cursor instead. Apart from Trash, no list returns a total count, so a loop has to stop on what the page itself says.

Offset pagination

A list endpoint takes two query parameters:

ParameterMeaning
limitHow many items to return. The default and the maximum depend on the endpoint (table below).
offsetHow many items to skip. offset=0, the default, is the first page.
EndpointDefault limitMaximum
Workspaces, workspace users, projects, browse10100
Datasets, automations50100
Views (/dataviews)50none set
Trash50500
Automation runs50100 accepted, but at most 50 runs come back

A limit above the maximum is refused with 400 and "error_code": "4GENR007" (VALIDATION_ERROR). Another list's limits are in the OpenAPI document; see the REST reference.

The response carries the items under the resource's own name, the limit and offset it used, and next, the URL of the next page:

{
  "datasets": [{"id": 303686, "name": "Multi-Store Retail Sales"}],
  "limit": 100,
  "offset": 0,
  "next": "https://app.mammoth.io/api/v2/workspaces/11/projects/10/datasets?limit=100&offset=100"
}

next carries only limit and offset. It drops every other query parameter you sent, such as fields or sort, so add them again when you follow it.

Only the Trash list returns a total; no other list does. Do not stop on next alone either: some lists (datasets, projects, trash, workspaces) return an empty next after the last page, but others, such as views and workspace users, fill it on every page. Stop when a page returns fewer items than you asked for.

LIMIT=100
OFFSET=0
while : ; do
  BODY=$(curl -sS "https://app.mammoth.io/api/v2/workspaces/$WS/projects/$P/datasets?limit=$LIMIT&offset=$OFFSET" \
    -H "Authorization: Bearer $MAMMOTH_API_TOKEN")
  echo "$BODY" | jq -c '.datasets[]?'
  COUNT=$(echo "$BODY" | jq '.datasets | length')
  [ "$COUNT" -lt "$LIMIT" ] && break
  OFFSET=$((OFFSET + LIMIT))
done

The loop ends on a short or empty page, including an error body, which has no datasets array. Replace datasets with the list key of the endpoint you call: projects, dataviews, automations, and so on, and keep LIMIT at or below that endpoint's maximum.

In the SDK, client.projects.list, client.datasets.list and client.dataviews.list take limit and offset (both default to limit=100, offset=0) and return the same body. client.datasets.list_all follows the pages for you.

Paging through the CLI

mammoth view data get, mammoth view export list and mammoth view pipeline items page with offset and limit in --input. The offset is 0-based and counts the rows to skip: offset: 0 is the first page. The response reports the limit and offset it used in a paging block with next_command and previous_command, ready to run. Each is null when there is no such page.

mammoth view data get 1039 --project 180 --input '{"offset": 0, "limit": 50}'

Follow paging.next_command until it is null. A script that passed 1 for the first page must now pass 0.

Cursor pagination

A few endpoints take a cursor instead of an offset:

GET /workspaces/<workspace_id>/resources
GET /workspaces/<workspace_id>/projects/<project_id>/resources
GET /agents/sessions/<session_id>/runs/<run_id>/units

The two Resources endpoints take limit (default 50) and return {"resources": [...], "next_cursor": "...", "has_more": true}. Pass next_cursor back as cursor on the next request, and stop when has_more is false.

The run units endpoint belongs to the AI Agent (available on Enterprise plans). It returns pages of 50 units, oldest first, as {"units": [...], "next_cursor": 1234}, with no has_more. Pass next_cursor back as cursor, and stop when it is null.

Next up

Report an issue · support@mammoth.io