Pagination

Every list works the same way. Ask for a page with limit, and you get { data, next }. next is a cursor: pass it back as after to get the following page. When next is null, you have them all.

Page through a list

curl "https://api.boxline.dev/v1/agent/runs?limit=50" \  -H "x-api-key: $BOXLINE_API_KEY"# {"data": [...], "next": "eyJvIjoiY3JlYXRlZF9kZXNjIiwidCI6…"}curl "https://api.boxline.dev/v1/agent/runs?limit=50&after=eyJvIjoiY3JlYXRlZF9kZXNjIiwidCI6…" \  -H "x-api-key: $BOXLINE_API_KEY"

// One page: await the list.const page = await bx.agent.list({ limit: 50 });console.log(page.data.length, page.next);// The following page, with the same filters.if (page.hasNextPage()) {  const second = await page.getNextPage();  console.log(second.data.length);}// Every item: iterate the list, and the SDK follows next for you.for await (const run of bx.agent.list({ limit: 50 })) console.log(run.id, run.status);

# One page: the list call returns it.page = bx.agent.list(limit=50)print(len(page.data), page.next)# The following page, with the same filters.if page.has_next_page():    second = page.get_next_page()    print(len(second.data))# Every item: iterate the list, and the SDK follows next for you.for run in bx.agent.list(limit=50):    print(run["id"], run["status"])

Rules

• next is opaque: do not build or change it. Send it back with the same filters and sort as the page it came from. A cursor from another list, or changed, gets 400 invalid_cursor.
• New items do not shift the pages you are reading, as offsets would.
• Lists that return total (sessions, profiles) still do. There is no offset: a list takes after only, and offset is 400 invalid_request.
• The session event log also returns nextAfter, the last event’s number. Keep it to poll for new events later: there, next becomes null once you have caught up.

Every list

In the SDKs

Every list method of the SDKs takes limit and after and returns the first page, with data, next, and total where the list has it. Iterate it (Node: for await, Python: for, async Python: async for) to go through every item: the SDK asks for the following pages as you go. A crawl’s pages have their own helper, bx.crawl.pages(id).