Pagination

Cursor-based pagination conventions for list endpoints in the Brew Public API v1 — limits, cursors, hasMore, and the standard iteration loop.

Brew list endpoints use opaque cursor pagination. Every paginated response carries a pagination: { limit, cursor?, hasMore } envelope so callers can iterate without page-counting math.

The pagination envelope

type Pagination = {
  limit: number          // page size used for this response
  cursor?: string        // opaque token — pass back as `?cursor=…` to get the next page
  hasMore: boolean       // true when more rows exist
}

Where it appears (read mode):

type ListResponse<Row> = {
  [collectionName: string]: Array<Row>     // e.g. `contacts`, `runs`
  pagination?: Pagination
}

Endpoints that paginate

Every list endpoint accepts limit (1–100) + cursor and returns the pagination envelope. The default limit is 100 except where noted.

Endpoint	Default limit	Max limit	Notes
GET /v1/contacts	50	100	Filterable + sortable (search, sort, order, logic, filters).
GET /v1/automation/runs	25	100	Filterable on automationId, triggerEventId, status, mode, from, to. ?include=logs attaches per-node logs.
GET /v1/audiences	100	100	Saved audiences for the brand.
GET /v1/domains	100	100	All sending domains; ?sendableOnly=true for verified-only.
GET /v1/emails	100	100	Latest version per emailId. Filterable on emailType, status, createdAtFrom/To, updatedAtFrom/To.
GET /v1/templates	100	100	Public template catalog; lean by default (?include=html for emailHtml/emailPng). Filterable on brand, category, semantic.
GET /v1/triggers	100	100	Integration-provisioned + API-created triggers.
GET /v1/automations	100	100	Latest version per automationId; lean by default (?include=graph for nodes/connections).
GET /v1/sends	100	100	Campaign sends + stats. Filterable on status, from, to.
GET /v1/analytics/campaigns	100	100	Lifetime per-campaign KPIs.
GET /v1/analytics/events	50	100	Unified event explorer. Filterable on recipientEmail, eventType, automationId, from, to.

Endpoints that don’t paginate

GET /v1/fields returns the full set of custom contact-field definitions for the brand (usually ≤ 50) in a plain { fields } envelope with no pagination.

Single-row lookups (always a one-element list)

Several get-one endpoints return the same envelope as the list — a one-element array — so SDK code stays uniform whether you’re fetching a single row or many:

Endpoint	Body
GET /v1/triggers?triggerEventId=tri_xxx	{ triggers: [TriggerRow] }
GET /v1/automations?automationId=auto_xxx	{ automations: [AutomationRow] } (optionally automations[0].versions[] with ?include=versions)
GET /v1/automation/runs?automationRunId=run_xxx	{ runs: [AutomationRunRow], logs?: [...] } (optional logs[] with ?include=logs)
GET /v1/audiences?audienceId=aud_xxx	{ audiences: [AudienceRow] }
GET /v1/sends?emailId=eml_xxx	{ sends: [SendRow] } (404 SEND_NOT_FOUND on a miss)

Single-row lookups return the one-element array without a pagination envelope. When a lookup misses, you get 404 <RESOURCE>_NOT_FOUND — never an empty array.

Canonical iteration loop

The standard cursor pattern — works for contacts and automation runs:

async function* paginateAllContacts() {
  let cursor: string | undefined
  while (true) {
    const url = new URL('https://brew.new/api/v1/contacts')
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.BREW_API_KEY!}` },
    })
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
    const body = (await res.json()) as {
      contacts: Array<{ email: string }>
      pagination: { limit: number; cursor?: string; hasMore: boolean }
    }

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

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

SDK pagination (TypeScript)

The official @brew.new/sdk returns the raw { contacts, pagination } shape — pass the cursor back on the next call:

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.list({ limit: 100, cursor })
  for (const contact of page.contacts) {
    console.log(contact.email)
  }
  cursor = page.pagination?.hasMore ? page.pagination.cursor : undefined
} while (cursor)

For automation runs, swap brew.contacts.list → brew.automationRuns.list with the same shape.

Filter combinations

GET /v1/contacts supports search + sort + filter on the same call:

GET /v1/contacts?search=jane&sort=createdAt&order=desc&limit=50
GET /v1/contacts?logic=and&filters=[{"field":"plan","operator":"eq","value":"pro"}]&limit=100

GET /v1/automation/runs supports time-range and status filters:

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

See the per-endpoint pages under Public API v1 for the full filter parameter table.

Cursor semantics

• Opaque. Cursors are server-generated tokens. Don’t parse them; don’t synthesise them. The format may change between releases.
• Stable within a page. A cursor returned on page N points to “the next batch of rows that existed when N was rendered”. New rows inserted concurrently may show up; deleted rows may be skipped. This is fine for analytics / bulk export; if you need strict snapshot reads, freeze a time bound with ?from=&to=.
• 24-hour TTL. Cursors don’t expire on a strict clock today, but treat them as if they’re good for ~24h — 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.

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to analyze documentation with ChatGPT or Claude for deeper insights.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.