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:
| Parameter | Meaning |
|---|---|
limit | How many items to return. The default and the maximum depend on the endpoint (table below). |
offset | How many items to skip. offset=0, the default, is the first page. |
| Endpoint | Default limit | Maximum |
|---|---|---|
| Workspaces, workspace users, projects, browse | 10 | 100 |
| Datasets, automations | 50 | 100 |
Views (/dataviews) | 50 | none set |
| Trash | 50 | 500 |
| Automation runs | 50 | 100 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
- Errors and exit codes: how failures are reported, and what is worth retrying.
- Command contract: every capability with its CLI, SDK and API forms.