CiteFoundry Docs
Open dashboard

Pagination

Cursor pagination across every list endpoint. Opaque cursors, page sizes, and the patterns to use.

Every list endpoint paginates with an opaque cursor. Cursors are forward-only, sized 1–100, and stable under inserts (you won’t see duplicates if rows are added mid-iteration).

Request

Pagination is controlled by two query params:

  • limit — items per page. 1 to 100. Defaults to 25.
  • cursor — the nextCursor from a previous response. Omit on the first request.
GET /v1/projects/proj_01J.../runs?limit=50
Authorization: Bearer …

Response shape

{
  "items": [ /* … */ ],
  "nextCursor": "eyJpZCI6InJ1bl8wMUo...iLCJ0cyI6...",
  "limit": 50
}
  • items — the page.
  • nextCursor — pass back as cursor= on the next request. Absent (or null) when there are no more pages.
  • limit — echoes the limit used (which may differ from what you asked for if it was clamped).

There is no total count. Counting is expensive on cursor-paginated backends; if you need a count, see aggregations below.

Walking a list

import { DefaultService } from "@citefoundry/api-client";


let cursor: string | undefined;
do {
  const page = await DefaultService.listRuns({
    projectId,
    limit: 100,
    cursor,
  });
  for (const run of page.items) {
    // process run
  }
  cursor = page.nextCursor;
} while (cursor);

Stability

Cursors point to a position in a sorted stream, not to a row ID. New rows inserted at the head while you’re iterating will be visible on the next call only if you re-start; cursors won’t go back to pick them up. This is the standard “forward-only” trade-off and is what you want for most batch use cases.

Errors

Passing a malformed cursor returns a validation problem:

{
  "type":   "https://citefoundry.com/problems/validation",
  "title":  "Validation failed",
  "status": 400,
  "detail": "Cursor is malformed."
}

If a cursor is well-formed but from a different list (e.g. you reused a runs cursor against the prompts endpoint), you’ll get the same validation problem. Don’t share cursors across endpoints.

Counting

When you actually need a count (e.g. “how many monitors does this project have”), use the resource’s dedicated aggregation endpoint or metrics endpoint rather than iterating. Most resources have one.

Page size

100 is the maximum. Stick to a size that matches your batch latency: 50–100 is fine for server-to-server, 25 is comfortable for an interactive UI. Smaller pages don’t make individual requests faster beyond the network round-trip; if you need to render in chunks, fetch 100 and chunk client-side.