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:
| Endpoint | Default limit | Highest limit |
|---|---|---|
List projects — GET /api/projects | 500 | 2000 |
List worktrees — GET /api/worktrees | 500 | 2000 |
Get node disk events — GET /api/nodes/{node_id}/disk-events | 50 | 200 |
List comments — GET /api/tasks/{task_id}/comments | 200 | 500 |
List ticket comments — GET /api/support/tickets/{ticket_id}/comments | 200 | 500 |
Get inbox — GET /api/inbox | 50 | 200 |
List credential owners — GET /api/credentials/owners | 20, once you send q or limit | 50 |
Search project tracker issues — GET /api/projects/{project_id}/tracker-issues | 15 | 50 |
List unmatched messages — GET /api/triggers/unmatched | 50 | 200 |
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 ingroups, biggest spend first. When more groups had spend, the first 199 come as their own rows and the last row, withkeyothers, sums the rest;foldedsays how many it holds (0 when none were folded), sototalstill adds up. - List principals (
GET /api/access/principals) returns at most 50 users and 50 groups, each in name order. Narrow it withqto 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: withq, the best matches first; otherwise grouped by purpose, then by name. Narrow them withq(orpurposeon 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 —
pageandper, with atotalso you can count the pages. - By offset —
limitandoffset, a count of items to skip.
| Endpoint | Pages by | Next page |
|---|---|---|
List tasks — GET /api/tasks | cursor | X-Next-Cursor header → after |
List tickets — GET /api/support/tickets | cursor | next_cursor → cursor |
List all schedule runs — GET /api/crons/runs | cursor | next_before → before |
Get Jaah AI ledger — GET /api/org/jaah-ai/ledger | cursor | last entry → before and before_id |
Get guard activity — GET /api/compliance/guard/activity | cursor | next → before |
Browse the audit log — GET /api/audit | cursor | next_cursor → cursor |
Read session events — GET /api/tasks/{task_id}/sessions/{agent_session_id}/events | cursor | last_seq → after |
Browse credential tree — GET /api/credentials/tree | cursor | next_cursor → cursor |
List deployments — GET /api/deployments | cursor | next_cursor → cursor |
List incidents — GET /api/incidents | cursor | next_cursor → cursor |
List release history — GET /api/projects/{project_id}/release/history | cursor | next_cursor → cursor |
List pipeline history — GET /api/projects/{project_id}/pipeline/history | cursor | next_cursor → cursor |
List merge lane rows across projects — GET /api/merge-lane/rows | cursor | next_cursor → cursor |
List memory units across projects — GET /api/memory/units | cursor | next_cursor → cursor |
List webhook deliveries — GET /api/webhooks/{webhook_id}/deliveries | cursor | next_cursor → cursor |
Get pipeline items — GET /api/projects/{project_id}/pipeline/items | cursor | X-Next-Cursor header or next_cursor → after |
Get pipeline release page — GET /api/projects/{project_id}/pipeline/release-page | cursor | older_than → before |
List users — GET /api/users | page number | page + 1 |
List groups — GET /api/groups | page number | page + 1 |
List group members — GET /api/groups/{group_id}/members | page number | page + 1 |
List nodes page — GET /api/nodes/page | page number | page + 1 |
List hosts — GET /api/hosts | page number | page + 1 |
List credentials — GET /api/credentials | page number, or cursor | page + 1, or next_cursor → cursor |
List sessions — GET /api/sessions | page number | page + 1 |
List intents — GET /api/nodes/intents | page number | page + 1 |
Get command log — GET /api/command-log | page number | page + 1 |
List tenant email sends — GET /api/orgs/{org_id}/email/sends | page number | page + 1 |
List automation dedup entries — GET /api/automations/{automation_id}/dedup | offset | offset + limit |
List automation runs — GET /api/automations/{automation_id}/runs | offset | offset + limit |
List merge lane queue — GET /api/projects/{project_id}/merge-lane/queue | offset | offset + limit |
List merge lane history — GET /api/projects/{project_id}/merge-lane/history | offset | offset + limit |
List merge lane runs — GET /api/projects/{project_id}/merge-lane/runs | offset | offset + limit |
List merge lane certificates — GET /api/projects/{project_id}/merge-lane/certificates | offset | offset + limit |
List merge lane flaky tests — GET /api/projects/{project_id}/merge-lane/flakes | offset | offset + limit |
List merge lane quarantined tests — GET /api/projects/{project_id}/merge-lane/quarantine | offset | offset + 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.
| Parameter | Meaning |
|---|---|
limit | How 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. |
after | The 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
qcome 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. Withsection=stoppedorsection=in_progress, unfinished tasks are also sorted by why they stopped or how far they have got; withsection=draft, plain drafts come before Jaah's suggestions. Withfocus=true, unfinished tasks that are queued come last among the unfinished. Withorder=sectionand nosection, 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
400and{"detail": "after is not a cursor this listing issued"}: turningfocuson or off, switching to or fromsection=stopped,section=in_progressorsection=draft, adding or removingorder=sectionwhile nosectionis set, adding or removing a numberedqor a pasted task link, or, withorder=sectionset, adding or removing anysection,doneincluded. Any other change is accepted, and the cursor carries on through the new results. Start again withoutafterwhenever 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;limitandafterdo not apply.
The ticket list
List tickets (GET /api/support/tickets) returns its page in the
body: {"items": […], "next_cursor": "…"}.
| Parameter | Meaning |
|---|---|
scope | mine (the default): the tickets you opened. org: every ticket of your organization; Org admins only, anyone else gets 403. |
limit | How many tickets to return, from 1 to 200; default 50. |
sort | updated (the default): most recently updated first. age: oldest first. priority: highest priority first, then most recently updated. |
cursor | The 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.
| Parameter | Meaning |
|---|---|
limit | How many runs to return, from 1 to 200; default 50. |
before | The 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.
| Parameter | Meaning |
|---|---|
limit | How many decisions to return, from 1 to 100; default 50. |
before | The 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", …}.
| Parameter | Meaning |
|---|---|
limit | How many entries to return, from 1 to 200; default 50. |
cursor | The 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_kind | total is |
|---|---|
exact | The number of matching entries. |
at_least | A 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.
| Parameter | Meaning |
|---|---|
limit | How many entries to return, from 1 to 100; default 25. |
before | The created_at of the previous page's last entry. |
before_id | The 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.
| Parameter | Meaning |
|---|---|
after | The 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.
| Parameter | Meaning |
|---|---|
cursor | The previous response's next_cursor. Leave it out for the first page. |
- Keep going until
next_cursorisnull, not until a page is empty. With a filter set, a page can come back short, even empty, and still carry anext_cursor: ask again with it. - A folder pages its child folders first, then its credentials. Pages carry
foldersuntil the last child folder, and the page that ends them already startsleaves, so a small folder is one response. - A cursor belongs to its listing. Send the same
level,org_id,home,pathand filters with every page; a cursor from any other listing is refused with422and{"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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 200; default 50. |
cursor | The 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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 200; default 50. |
cursor | The 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.
| Parameter | Meaning |
|---|---|
limit | How many items to return: merge lane rows from 1 to 100, default 20; memory units from 1 to 200, default 50. |
cursor | The 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": "…"}.
| Parameter | Meaning |
|---|---|
limit | How many deliveries to return, from 1 to 200; default 50. |
cursor | The 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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 200; default 100. |
after | The 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.
| Parameter | Meaning |
|---|---|
before | The 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.
| Parameter | Meaning |
|---|---|
page | Which 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. |
per | How 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 —
sortnames a field anddir(asc, the default, ordesc) its direction; an item without a value for that field comes last either way. Withoutsort: 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. Asortthe list does not offer is refused with422. Nodes and hosts also takegroup_by, which keeps each group together across pages and sorts within it; an item with no value for the group comes last. - Credentials —
sortisnewest(the default),oldest,name,typeororg; any other is refused with422. The list also pages by cursor: sendpaging=keysetfor the first page, then each response'snext_cursorascursor, which isnullon the last page. A cursor belongs to itssort,perand filters: change any of them and it is refused with422and{"detail": "This page link is out of date. Reload the list."}.cursororpagingtogether with apageother than 1 is refused with422. Paged by cursor,totalstops counting at 10000 andtotal_cappedturnstruewhen more match. - Sessions — by default, running sessions first, then the most recently started;
sortanddir(descby default) change the order, and asortthe list does not offer is refused with422. The list covers only sessions started in the last 24 hours, plus any still running, unless you passwindow:24h(the default),7d,30dorall.totalcounts within that window;total_unfilteredignores it. - Intents — pending intents oldest first; with
set=retired, newest first. - Command log — newest first.
- Email sends — newest first.
sort=created_atsorts by send time indir's order (asc, oldest first, by default); any othersortis refused with422.
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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 500; default 50. |
offset | How 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.
| Parameter | Meaning |
|---|---|
limit | How many runs to return, from 1 to 200; default 50. |
offset | How many runs to skip, from 0; default 0. |
targets_limit | How 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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 100; default 20. |
offset | How many items to skip, from 0; default 0. |
sort | Runs 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. |
dir | With 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.