Pagination

​

The Pagination Envelope

type Pagination = {
  limit: number          // page size used for this response
  cursor: string | null  // opaque token. Pass back as `?cursor=…` for the next page; null on the last
  hasMore: boolean       // true when more rows exist
}

type ListResponse<Row> = {
  data: Array<Row>     // the rows for this page, always under `data`
  pagination?: Pagination
}

​

Endpoints That Paginate

​

MCP Page Sizes

​

Single-Resource Reads (Identity in the Path)

​

Canonical Iteration Loop

async function* paginateAllContacts() {
  let cursor: string | undefined
  while (true) {
    const res = await fetch('https://brew.new/api/v1/contacts/search', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.BREW_API_KEY!}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ limit: 100, ...(cursor ? { cursor } : {}) }),
    })
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
    const body = (await res.json()) as {
      data: Array<{ email: string }>
      pagination: { limit: number; cursor?: string; hasMore: boolean }
    }

    for (const contact of body.data) yield contact
    if (!body.pagination.hasMore) return
    cursor = body.pagination.cursor
  }
}

for await (const contact of paginateAllContacts()) {
  console.log(contact.email)
}

​

SDK Pagination (TypeScript)

import { createBrewClient } from '@brew.new/sdk'

const brew = createBrewClient({ apiKey: process.env.BREW_API_KEY! })

let cursor: string | undefined
do {
  const page = await brew.contacts.search({ limit: 100, cursor })
  for (const contact of page.data) {
    console.log(contact.email)
  }
  cursor = page.pagination?.hasMore ? page.pagination.cursor : undefined
} while (cursor)

​

Filter Combinations

POST /v1/contacts/search
{ "search": "jane", "sort": "createdAt", "order": "desc", "limit": 50 }

POST /v1/contacts/search
{ "logic": "and", "filters": [{ "field": "plan", "operator": "equals", "value": "pro" }], "limit": 100 }

GET /v1/automations/runs?automationId=auto_abc&status=completed&from=2026-04-01T00:00:00.000Z&to=2026-04-08T00:00:00.000Z&limit=100

​

Cursor Semantics

• Opaque. Cursors are server-generated tokens. Don’t parse them; don’t synthesize them. The format may change between releases.
• Safe to change the list while you walk it. A cursor names the last row it returned, not a position, and the next page is the rows that sort after it. Deleting the rows you have read (for example, every audience that matches a search, page by page) skips nothing, and a row created during the walk is never returned twice. A row created where the walk has already passed is not returned; start a new walk to see it.
• Sort by a field the walk doesn’t change. Lists ordered by updatedAt (emails by default, automations, triggers) move a row to the front when it is edited, so a row edited ahead of the cursor during your walk moves behind it. For a walk that edits what it reads, page emails with sortBy=createdAt, or collect the ids first and then act on them.
• Catalogs page by position. GET /v1/fields, GET /v1/flows, GET /v1/templates and GET /v1/integrations page by offset. Deleting custom fields mid-walk shifts their pages, so collect first, then act.
• Brand images page two ways. Browsing GET /v1/brand/images without q continues after the last asset the previous page returned, so uploads and deletes during a walk don’t repeat or skip an asset. A browse cursor keeps its sort and kind: sending it with a different one is a 400 INVALID_REQUEST. A search with q pages its ranked results by position, and its cursor is signed: it only continues the same q and kind, and any other pair is a 400 INVALID_REQUEST.
• 24-hour TTL. Cursors don’t expire on a strict clock today, but treat them as if they’re good for ~24h, and re-start with no cursor if a job pauses overnight.

​

See Also

• Rate limits: a tight pagination loop can burn through 100/min quickly; consider parallelizing across keys or honoring X-RateLimit-Remaining.
• Batch operations: for writing lots of rows fast (POST /v1/contacts accepts up to 1000 rows per request).
• Errors: 404 on a get-one lookup; 400 INVALID_REQUEST on bad cursors or a retired id filter.
• Migrating to the cleaned-up v1 surface: every route, field, and status rename in one grep-able table.

​

Need Help?