Skip to main content

Pagination

Most list endpoints return every matching item in one response; a few cap it with limit and offer no next page. Those few stop at their default limit even when you do not send one, so raise it when you need more:

EndpointDefault limitHighest limit
List projects — GET /api/projects5002000
List worktrees — GET /api/worktrees5002000
Get node disk events — GET /api/nodes/{node_id}/disk-events50200
List comments — GET /api/tasks/{task_id}/comments200500
List ticket comments — GET /api/support/tickets/{ticket_id}/comments200500
Get inbox — GET /api/inbox50200
List credential owners — GET /api/credentials/owners20, once you send q or limit50
Search project tracker issues — GET /api/projects/{project_id}/tracker-issues1550
List unmatched messages — GET /api/triggers/unmatched50200

List credential owners is capped only when you send q, ids or limit; with none of them it returns every owner. Sending ids alone returns every owner it names; more than 50 ids is a 422.

Search project tracker issues counts limit across all the project's linked trackers, taking their results in turn so one tracker does not fill the list.

The two comment lists keep the most recent comments, returned oldest first. Get inbox returns newest first, at most limit items in all. Get node disk events returns the most recent events, newest first. For the comment lists and Get inbox, a limit outside its range is moved to the nearest end rather than refused: below 1 it is 1, above the highest it is the highest.

Eight lists take no limit and offer no next page, so they always stop at a fixed number:

  • List control messages (GET /api/tasks/{task_id}/control-messages) returns at most the 200 most recent messages, oldest first.
  • List conversations (GET /api/support/conversations) returns at most your 100 most recently updated Help assistant conversations, newest first.
  • List invoices (GET /api/org/billing/invoices) returns at most your organization's 100 most recent invoices, newest first.
  • Get Jaah AI usage (GET /api/org/jaah-ai/usage) returns at most 200 rows in groups, biggest spend first. When more groups had spend, the first 199 come as their own rows and the last row, with key others, sums the rest; folded says how many it holds (0 when none were folded), so total still adds up.
  • List principals (GET /api/access/principals) returns at most 50 users and 50 groups, each in name order. Narrow it with q to find one past the first 50.
  • List tracker events (GET /api/tracker-connections/{connection_id}/events) returns at most a tracker connection's 50 most recent events, newest first.
  • List templates (GET /api/templates) and List templates to manage (GET /api/templates/manage) each return at most 200 templates: with q, the best matches first; otherwise grouped by purpose, then by name. Narrow them with q (or purpose on List templates) to reach one past the first 200.

The thirty-five below return a page at a time. They page in one of three ways:

  • By cursor — the response gives you a value that marks the last item you were sent; send it back to get the next page. A list that changes while you read it does not shift every later page.
  • By page number — page and per, with a total so you can count the pages.
  • By offset — limit and offset, a count of items to skip.
EndpointPages byNext page
List tasks — GET /api/taskscursorX-Next-Cursor header → after
List tickets — GET /api/support/ticketscursornext_cursor → cursor
List all schedule runs — GET /api/crons/runscursornext_before → before
Get Jaah AI ledger — GET /api/org/jaah-ai/ledgercursorlast entry → before and before_id
Get guard activity — GET /api/compliance/guard/activitycursornext → before
Browse the audit log — GET /api/auditcursornext_cursor → cursor
Read session events — GET /api/tasks/{task_id}/sessions/{agent_session_id}/eventscursorlast_seq → after
Browse credential tree — GET /api/credentials/treecursornext_cursor → cursor
List deployments — GET /api/deploymentscursornext_cursor → cursor
List incidents — GET /api/incidentscursornext_cursor → cursor
List release history — GET /api/projects/{project_id}/release/historycursornext_cursor → cursor
List pipeline history — GET /api/projects/{project_id}/pipeline/historycursornext_cursor → cursor
List merge lane rows across projects — GET /api/merge-lane/rowscursornext_cursor → cursor
List memory units across projects — GET /api/memory/unitscursornext_cursor → cursor
List webhook deliveries — GET /api/webhooks/{webhook_id}/deliveriescursornext_cursor → cursor
Get pipeline items — GET /api/projects/{project_id}/pipeline/itemscursorX-Next-Cursor header or next_cursor → after
Get pipeline release page — GET /api/projects/{project_id}/pipeline/release-pagecursorolder_than → before
List users — GET /api/userspage numberpage + 1
List groups — GET /api/groupspage numberpage + 1
List group members — GET /api/groups/{group_id}/memberspage numberpage + 1
List nodes page — GET /api/nodes/pagepage numberpage + 1
List hosts — GET /api/hostspage numberpage + 1
List credentials — GET /api/credentialspage number, or cursorpage + 1, or next_cursor → cursor
List sessions — GET /api/sessionspage numberpage + 1
List intents — GET /api/nodes/intentspage numberpage + 1
Get command log — GET /api/command-logpage numberpage + 1
List tenant email sends — GET /api/orgs/{org_id}/email/sendspage numberpage + 1
List automation dedup entries — GET /api/automations/{automation_id}/dedupoffsetoffset + limit
List automation runs — GET /api/automations/{automation_id}/runsoffsetoffset + limit
List merge lane queue — GET /api/projects/{project_id}/merge-lane/queueoffsetoffset + limit
List merge lane history — GET /api/projects/{project_id}/merge-lane/historyoffsetoffset + limit
List merge lane runs — GET /api/projects/{project_id}/merge-lane/runsoffsetoffset + limit
List merge lane certificates — GET /api/projects/{project_id}/merge-lane/certificatesoffsetoffset + limit
List merge lane flaky tests — GET /api/projects/{project_id}/merge-lane/flakesoffsetoffset + limit
List merge lane quarantined tests — GET /api/projects/{project_id}/merge-lane/quarantineoffsetoffset + limit

Unless a section below says otherwise, a limit, per, page or offset outside its range is refused with 422 and the list-shaped detail described in Errors, and a page past the end returns an empty list. Treat every cursor as opaque: send it back unchanged, never build or edit one.

The task list​

List tasks (GET /api/tasks) pages its top-level tasks.

ParameterMeaning
limitHow many tasks to return, from 1 to 500. A larger value is treated as 500 and a smaller one as 1. Leave it out to get 500.
afterThe cursor from the previous page's X-Next-Cursor header. Leave it out for the first page.

When more tasks remain, the response carries an X-Next-Cursor header. Send its value back unchanged as after, with the same filters, to get the next page. On the last page the header is absent.

GET /api/tasks?limit=50
→ 200, X-Next-Cursor: W1si…

GET /api/tasks?limit=50&after=W1si…
→ 200, no X-Next-Cursor: this was the last page
  • Order. Tasks whose number contains the digits of a numbered q come first; a pasted task link puts that task first. Then the tasks you pinned, then unfinished tasks before finished ones, then the most recently updated, then the highest id. With section=stopped or section=in_progress, unfinished tasks are also sorted by why they stopped or how far they have got; with section=draft, plain drafts come before Jaah's suggestions. With focus=true, unfinished tasks that are queued come last among the unfinished. With order=section and no section, tasks come in the board's screen order first after the named row — Stopped, In progress, Draft, then Done — and in the order above within each.
  • A cursor belongs to its ordering. A change between pages that changes the order refuses the old cursor with 400 and {"detail": "after is not a cursor this listing issued"}: turning focus on or off, switching to or from section=stopped, section=in_progress or section=draft, adding or removing order=section while no section is set, adding or removing a numbered q or a pasted task link, or, with order=section set, adding or removing any section, done included. Any other change is accepted, and the cursor carries on through the new results. Start again without after whenever you change a filter.
  • Live data. A task updated while you page may move: it can appear twice or not at all. Reload from the first page when you need an exact snapshot.
  • Children are not paged. With parent_id, the endpoint returns every child of that parent you can see, except archived ones, ordered by id; limit and after do not apply.

The ticket list​

List tickets (GET /api/support/tickets) returns its page in the body: {"items": […], "next_cursor": "…"}.

ParameterMeaning
scopemine (the default): the tickets you opened. org: every ticket of your organization; Org admins only, anyone else gets 403.
limitHow many tickets to return, from 1 to 200; default 50.
sortupdated (the default): most recently updated first. age: oldest first. priority: highest priority first, then most recently updated.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. A cursor is valid only for the same sort; any other is refused with 400 and {"detail": "cursor is not one this listing issued"}.

Schedule runs​

List all schedule runs (GET /api/crons/runs) pages the runs of every schedule, optionally filtered by cron and outcome. It returns the runs newest first in runs, with the cursor for the next page in next_before, or null at the end.

ParameterMeaning
limitHow many runs to return, from 1 to 200; default 50.
beforeThe previous response's next_before. Leave it out for the newest runs.

Send the same filters with every page: the cursor continues the filtered list. A before value the endpoint did not issue is refused with 422 and a detail that starts with before:. The response has no total count.

Guard activity​

Get guard activity (GET /api/compliance/guard/activity) pages the Architectural Guard's decisions on the projects you can view, newest first, in items, with the cursor for the next page in next, or null at the end. The first page also carries rules, the rules the guard enforces; later pages leave it out. Where the guard is not available it answers 404.

ParameterMeaning
limitHow many decisions to return, from 1 to 100; default 50.
beforeThe previous response's next. Leave it out for the newest decisions.

Send the same project_id, pack_id, rule_key and decision with every page: the cursor continues the filtered list. The response has no total count.

The audit log​

Browse the audit log (GET /api/audit) returns its page in the body, newest first: {"items": […], "next_cursor": "…", "total": 12, "total_kind": "exact", …}.

ParameterMeaning
limitHow many entries to return, from 1 to 200; default 50.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. Send the same filters with every page: the cursor continues the filtered list, and entries recorded while you page never shift it. A cursor this endpoint did not issue is refused with 422.

total_kind says what total is:

total_kindtotal is
exactThe number of matching entries.
at_leastA floor: 10,000 when more entries match than the count goes to, or, when counting takes too long, this page's entries plus one if more follow. Show it with a "+", as in "10,000+".

any_visible is false only when the log holds no entry you may see, whatever your filters.

The Jaah AI ledger​

Get Jaah AI ledger (GET /api/org/jaah-ai/ledger) returns the ledger between from and to, newest first: {"entries": […], "has_more": true}. It has no cursor field of its own; the last entry of a page is the cursor.

ParameterMeaning
limitHow many entries to return, from 1 to 100; default 25.
beforeThe created_at of the previous page's last entry.
before_idThe id of the previous page's last entry.

While has_more is true, send the same from, to and tz with before and before_id taken from the last entry to get the next page. Send both or neither: one without the other is refused with 422 and {"detail": "Give both before and before_id, or neither"}.

Session events​

Read session events (GET /api/tasks/{task_id}/sessions/{agent_session_id}/events) returns an agent session's events oldest first, in seq order: {"events": […], "last_seq": 1500, "more": true, …}. A page holds at most 500 events and about 4 MB, but always at least one event when any is waiting.

ParameterMeaning
afterThe previous response's last_seq. Leave it out, or send 0, for the first events.

While more is true, ask again at once with after set to last_seq. more is false once you have every event stored so far; a running session keeps adding events, so to follow it, keep asking with the latest last_seq until status is no longer running (it becomes ended, or unknown when nobody saw the session end) and a page comes back empty. A page with no events returns your after as last_seq. To get the whole stream in one response, use Download session events instead.

The credential tree​

Browse credential tree (GET /api/credentials/tree) returns one level of the credentials tree: {"homes": […], "folders": […], "leaves": […], "next_cursor": "…"}, with only the lists that level fills non-empty. It takes no limit: a page holds at most 100 homes, or 100 child folders and 100 credentials.

ParameterMeaning
cursorThe previous response's next_cursor. Leave it out for the first page.
  • Keep going until next_cursor is null, not until a page is empty. With a filter set, a page can come back short, even empty, and still carry a next_cursor: ask again with it.
  • A folder pages its child folders first, then its credentials. Pages carry folders until the last child folder, and the page that ends them already starts leaves, so a small folder is one response.
  • A cursor belongs to its listing. Send the same level, org_id, home, path and filters with every page; a cursor from any other listing is refused with 422 and {"detail": "This page link is out of date. Reload the list."}.
  • Order. Credentials by name; child folders by name within a page. Homes within a page come shared first, then system, project and personal.

Deployments and incidents​

List deployments (GET /api/deployments) and List incidents (GET /api/incidents) return their page in the body: {"items": […], "next_cursor": "…"}, newest first, from the projects you may view.

ParameterMeaning
limitHow many items to return, from 1 to 200; default 50.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. Send the same filters with every page. A cursor from any other listing, including the other of these two, is refused with 422 and {"detail": "'cursor' is not one this listing issued — send back a next_cursor unchanged, or leave it out"}.

Releases​

List release history (GET /api/projects/{project_id}/release/history) returns its page in the body: {"items": […], "next_cursor": "…"}, newest first.

ParameterMeaning
limitHow many items to return, from 1 to 200; default 50.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. A cursor this list did not issue is refused with 422 and {"detail": "'cursor' is not one this listing issued — send back a next_cursor unchanged, or leave it out"}.

List pipeline history (GET /api/projects/{project_id}/pipeline/history) pages a project's pipeline saves the same way, newest first, with the same limit, cursor and 422.

Merge lane rows and memory units​

List merge lane rows across projects (GET /api/merge-lane/rows) and List memory units across projects (GET /api/memory/units) return their page in the body: {"items": […], "next_cursor": "…"}, from every project you may view. Each item names its project. Merge lane rows come in order of their latest change, newest first; memory units newest first. A project whose organization's plan leaves out project memory adds no memory units.

ParameterMeaning
limitHow many items to return: merge lane rows from 1 to 100, default 20; memory units from 1 to 200, default 50.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. Send the same project_id (and, for merge lane rows, state) with every page. A cursor from any other listing, including the other of these two, is refused with 422 and {"detail": "'cursor' is not one this listing issued: send back a next_cursor unchanged, or leave it out"}. One exception: when no project you may view has project memory, List memory units answers any cursor with an empty page. The responses have no total count. To page one project's merge lane by offset instead, use the six per-project merge lane lists.

Webhook deliveries​

List webhook deliveries (GET /api/webhooks/{webhook_id}/deliveries) returns one endpoint's deliveries newest first: {"items": […], "next_cursor": "…"}.

ParameterMeaning
limitHow many deliveries to return, from 1 to 200; default 50.
cursorThe previous response's next_cursor. Leave it out for the first page.

next_cursor is null on the last page. A cursor that is not well formed is refused with 422 and the list-shaped detail described in Errors. The response has no total count.

Pipeline items​

Get pipeline items (GET /api/projects/{project_id}/pipeline/items) returns one project's pipeline items in screen order: {"rows": […], "total": 120, "folded": {"12": 3}, "next_cursor": "…"}. total counts every item that matches, not only this page's. folded counts, per stage or bucket, the matching items folded away under Automatic.

ParameterMeaning
limitHow many items to return, from 1 to 200; default 100.
afterThe previous page's X-Next-Cursor header, or its next_cursor: the two hold the same value. Leave it out for the first page.

When more items remain, the response carries both the X-Next-Cursor header and next_cursor. On the last page both are absent. Send the same stage, group and filters with every page. An after that is not well formed is refused with 422 and {"detail": "after is not a cursor this listing issued"}. For a release stage, only the first page carries releases and next_release.

Pipeline releases​

Get pipeline release page (GET /api/projects/{project_id}/pipeline/release-page) returns a project's arrived releases 50 at a time, newest first: {"releases": […], "older_than": 812}. It takes no limit.

ParameterMeaning
beforeThe previous response's older_than: only releases older than this release id. Leave it out for the first page.

older_than is null on the last page. Send the same stage and filters with every page. When a filter narrows the list, a page can be empty and still carry an older_than: keep paging until it is null.

Page-numbered lists​

List users, List groups, List group members, List nodes page, List hosts, List credentials, List sessions, List intents, Get command log and List tenant email sends page by number.

ParameterMeaning
pageWhich page, from 1; default 1. At most 10000 for the command log, 100000 for users, groups, group members, nodes, hosts and email sends, and 1000000 for the others.
perHow many items a page holds, from 1 to 200; default 50 for users, groups, group members, nodes, hosts, email sends and the command log, 25 for the others.

Each returns its page in items and the number of items matching your filters in total, so the last page is ceil(total / per). All but the command log also echo page and per; sessions and intents add total_unfiltered: for sessions the count before any filter or window, for intents the count within set and node only. Because these pages are counted rather than marked by a cursor, an item added or removed while you page shifts every later page by one.

  • Users, groups, group members, nodes and hosts — sort names a field and dir (asc, the default, or desc) its direction; an item without a value for that field comes last either way. Without sort: users by email, groups and members by name, nodes and hosts by name. On the host list, the entry for your nodes on shared machines always comes last. A sort the list does not offer is refused with 422. Nodes and hosts also take group_by, which keeps each group together across pages and sorts within it; an item with no value for the group comes last.
  • Credentials — sort is newest (the default), oldest, name, type or org; any other is refused with 422. The list also pages by cursor: send paging=keyset for the first page, then each response's next_cursor as cursor, which is null on the last page. A cursor belongs to its sort, per and filters: change any of them and it is refused with 422 and {"detail": "This page link is out of date. Reload the list."}. cursor or paging together with a page other than 1 is refused with 422. Paged by cursor, total stops counting at 10000 and total_capped turns true when more match.
  • Sessions — by default, running sessions first, then the most recently started; sort and dir (desc by default) change the order, and a sort the list does not offer is refused with 422. The list covers only sessions started in the last 24 hours, plus any still running, unless you pass window: 24h (the default), 7d, 30d or all. total counts within that window; total_unfiltered ignores it.
  • Intents — pending intents oldest first; with set=retired, newest first.
  • Command log — newest first.
  • Email sends — newest first. sort=created_at sorts by send time in dir's order (asc, oldest first, by default); any other sort is refused with 422.

Offset lists​

List automation dedup entries (GET /api/automations/{automation_id}/dedup) returns the items an event automation has acted on in items, newest first, with total. On an automation that runs on a schedule it is refused with 409.

ParameterMeaning
limitHow many items to return, from 1 to 500; default 50.
offsetHow many items to skip, from 0; default 0.

List automation runs (GET /api/automations/{automation_id}/runs) returns one automation's runs in items, newest first, and echoes limit and offset. It has no total count: a page shorter than limit is the last one.

ParameterMeaning
limitHow many runs to return, from 1 to 200; default 50.
offsetHow many runs to skip, from 0; default 0.
targets_limitHow many of each run's targets to include, from 1 to 500; default 50. targets_total on each run says how many it has.

The six merge lane lists — queue, history, runs, certificates, flaky tests, quarantined tests (GET /api/projects/{project_id}/merge-lane/{list}) — each return one page of a project's merge lane in items, with total: queue and history most recently changed first, runs newest filed first, certificates and flaky tests newest first, quarantined tests by their newest flake.

ParameterMeaning
limitHow many items to return, from 1 to 100; default 20.
offsetHow many items to skip, from 0; default 0.
sortRuns only. merge lists just the runs that merged something, by the time from the run's start to its last merge. Without it, the runs come newest first.
dirWith sort=merge: desc (the default) puts the slowest first, asc the fastest.

Like the page-numbered lists, an item added or removed while you page shifts every later page by one.