Skip to content

Pagination

List endpoints return one page at a time and a cursor for the next one. Pages stay consistent when items are added or change between requests: you never see an item twice or miss one.

GET /v1/conversations, GET /v1/conversations/{id}/items and GET /v1/agent_results answer:

{
"object": "list",
"data": [ ... ],
"has_more": true,
"next_cursor": "eyJlZGdlX3VwZGF0ZWRfYXQiOi..."
}
  • data is the page of items.
  • has_more says whether another page follows.
  • next_cursor fetches it. It is null when has_more is false.

Pass next_cursor back as the cursor query parameter, together with the same filters:

curl -s "https://app-api.marvin-labs.com/v1/conversations?limit=50&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $MARVIN_API_KEY"
  • limit sets the page size: 1 to 100, default 20. On /v1/conversations/{id}/items, limit counts turns, and each turn gives two items: the question and the answer.
  • A cursor is opaque. Don’t parse it or build one yourself: its contents can change at any time. A cursor the API can no longer read is a 400 with the code bad_request. Start again from the first page.

A full walk in Python:

import os
import httpx
client = httpx.Client(
base_url="https://app-api.marvin-labs.com",
headers={"Authorization": f"Bearer {os.environ['MARVIN_API_KEY']}"},
)
params = {"limit": 100}
while True:
page = client.get("/v1/conversations", params=params).json()
for conversation in page["data"]:
print(conversation["id"], conversation["title"])
if not page["has_more"]:
break
params["cursor"] = page["next_cursor"]

POST /v1/tools/documents/list pages the same way, with the parameters in the JSON body: send limit (1 to 50, default 10) and the previous answer’s next_cursor as cursor. Its answer has documents and next_cursor, which is null on the last page.