> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth API pagination

> Mammoth list endpoints page with limit and offset and return a next URL. Defaults and caps per endpoint, a loop that ends, and cursor endpoints.

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](https://mammoth.io/docs/build/#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:

```json
{
  "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.

```bash
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.

```bash
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.

> **Check the parameter before you write a cursor loop**
>
> A cursor loop against an endpoint that takes no `cursor` never advances: the endpoint ignores the parameter and returns the first page every time. The OpenAPI document lists each operation's parameters; see [the REST reference](https://mammoth.io/docs/build/#rest-reference).

## Next up

- [Errors and exit codes](https://mammoth.io/docs/build/errors/): how failures are reported, and what is worth retrying.
- [Command contract](https://mammoth.io/docs/build/): every capability with its CLI, SDK and API forms.

---
Source: https://mammoth.io/docs/build/pagination.md · Updated: 2026-11-02
