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 | null  // opaque token. Pass back as `?cursor=…` for the next page; null on the last
  hasMore: boolean       // true when more rows exist
}

Where it appears (read mode):

type ListResponse<Row> = {
  data: Array<Row>     // the rows for this page, always under `data`
  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	100	100	The brand’s contacts, newest first. Filterable on search, audienceId; order with sort + order.
POST /v1/contacts/search	50	100	Structured contact search. Filterable + sortable (search, sort, order, logic, filters, audienceId) in the JSON body. With include: ["openProfile"] a page holds at most 10 contacts, and pagination.limit reports the size read.
GET /v1/fields	100	100	Custom contact-field definitions for the brand. ?include=coverage adds per-field fill stats.
GET /v1/audiences	100	100	Saved audiences for the brand.
GET /v1/domains	100	100	All sending domains; ?sendableOnly=true for verified-only, ?sendingPurpose= to split marketing from transactional.
GET /v1/emails	100	100	Latest version per emailId. Filterable on status, groupId, and a from/to window on whichever timestamp sortBy=updatedAt|createdAt names.
GET /v1/email-groups	100	100	Named email folders for the brand.
GET /v1/emails/{emailId}/comments	100	100	One design’s open comment threads, newest activity first. With include=messages a page holds at most 3 threads, and each thread pages its own older messages with messagesCursor (see Cursor Semantics).
GET /v1/templates	100	100	Public template catalog; each row is a full template (html + previewImage + title/category/brand). Filterable on brand, category, semantic.
GET /v1/flows	100	100	Public email flows: one brand’s real multi-step sequence per row (brand, type, category, emailCount, spanDays, previewImages). Filterable on brand, category, type, semantic; order with sort=newest|emails|span|remixes. Each page also carries total (every flow the query matches, across all pages) and isTotalExact (false when the read was cut at 500 flows, so total is a floor). A semantic search that cannot run is 503.
GET /v1/brand/images	100	100	The brand’s logos and images, newest first. Filterable on kind; order with sort=newest|oldest. With q, a semantic search in relevance order that costs 1 credit for its first page.
GET /v1/automations	100	100	Latest version per automationId, newest first; lean by default. Read one with GET /v1/automations/{automationId}. ?search= keeps the name matches, still newest first.
GET /v1/automations/triggers	100	100	Integration-provisioned, API-created, and Brew-event triggers.
GET /v1/automations/runs	100	100	Filterable on automationId, triggerEventId, triggerInstanceId, status, mode, from, to.
GET /v1/automations/audience-runs	100	100	Manual-audience launches. Filterable on automationId, status.
GET /v1/automations/trigger-instances	100	100	Fired-trigger audit log. Filterable on triggerEventId.
GET /v1/sends	100	100	Sends + lifetime stats. Filterable on status, emailId, kind, messageClass, from, to, plus a join filter (automationId, automationRunId, audienceRunId, triggerInstanceId) that switches to the per-recipient automation grain.
GET /v1/analytics/events	100	100	Unified event explorer. Filterable on recipient, eventType, automationId, sendId, emailId, from, to, and more.
GET /v1/insights	100	100	Brew Insights findings, most severe first. Filterable on state and severity. At most 200 findings are in view, so at the default limit a full walk is at most two pages. A cursor is refused once the findings above it change (see Cursor Semantics).
GET /v1/chats	100	100	The brand’s chats, most recently active first.
GET /v1/notifications	100	100	The notifications bell, newest first. Filterable on type. A page can hold fewer rows than limit while hasMore is true.

These are the HTTP limits. The MCP tools read smaller pages; see MCP page sizes.

MCP Page Sizes

An MCP tool result must fit the host’s response budget. A list page that doesn’t fit is refused whole with RESPONSE_TOO_LARGE: no rows and no cursor, so repeating the call with the same cursor and a smaller limit skips nothing. The MCP tools therefore page in smaller steps than HTTP:

MCP tool	Default limit	Max limit
search_contacts	10	25 (10 with include: ["openProfile"])
search_templates	8	20
list_insights	10	10
list_email_comments	10	25 (3 with include: ["messages"])
get_email_analytics, sends report	10	10
get_email_analytics, events report	15	15
Every other list_* / search_* tool	25	25

A contact carries every custom field it has, so a search_contacts page is as wide as your brand’s field list. Raise limit toward 25 only when your contacts carry few custom fields.

list_insights is the one list that trims instead of refusing. It shortens long text on each finding and cuts the report, suggestions, and memo where its budget ends. A truncated array names each cut section as { section, shown, total }: items shown of the total for report and suggestions, and characters of its markdown for memo. Every finding on the page stays, so the cursor still continues after the last one. The HTTP read always answers whole.

Single-Resource Reads (Identity in the Path)

Every collection has a real detail read at /{collection}/{id}. It returns the bare row, not a list envelope, so there is no data[0] unwrap and no pagination object. ?include= opt-ins embed the heavier detail:

Read	include opt-ins
GET /v1/emails/{emailId} (carries previewImage)	html, versions
GET /v1/email-groups/{groupId}	none
GET /v1/audiences/{audienceId}	count, build
GET /v1/automations/{automationId}	graph, versions
GET /v1/automations/runs/{automationRunId}	logs
GET /v1/automations/audience-runs/{audienceRunId}	none
GET /v1/automations/triggers/{triggerEventId}	skill
GET /v1/automations/trigger-instances/{triggerInstanceId}	none
GET /v1/sends/{sendId}	events
GET /v1/domains/{domainId}	none
GET /v1/domains/{domainId}/health	scoreHistory, scoreRuns
GET /v1/contacts/{email}	openProfile (needs the emails scope as well)
GET /v1/insights/{insightId}	none
GET /v1/fields/{fieldName}	none
GET /v1/emails/{emailId}/inbox-placement-tests/{testId}	none
GET /v1/flows/{slug} (adds anchor and steps[]: subject, dayOffset, delayDays, category, previewImage, emailId, none of which appear on a list card)	html (best-effort per step)

Passing an id as a list filter is retired. GET /v1/emails?emailId=, ?audienceId=, ?automationId=, ?automationRunId=, ?triggerEventId=, ?sendId=, ?triggerInstanceId= and ?domainId= are no longer accepted query keys and return 400 INVALID_REQUEST with param naming the key. Use the path read above. The one place an id still filters a list is a deliberate join: GET /v1/sends accepts automationId, automationRunId, audienceRunId or triggerInstanceId to list the per-recipient sends that run produced, and GET /v1/automations/runs accepts automationId, triggerEventId or triggerInstanceId for the same reason.

When the id misses, each detail read returns a resource-specific 404: EMAIL_NOT_FOUND, AUDIENCE_NOT_FOUND, SEND_NOT_FOUND, DOMAIN_NOT_FOUND, AUTOMATION_RUN_NOT_FOUND, TRIGGER_INSTANCE_NOT_FOUND, CONTACT_NOT_FOUND, FLOW_NOT_FOUND, INSIGHT_NOT_FOUND. Check the endpoint in the generated reference for its exact code, and see Errors for the envelope.

Canonical Iteration Loop

This is the standard cursor pattern. The contact read is a POST with a JSON body, so the cursor rides in the body (GET lists put cursor in the query instead):

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)

The official @brew.new/sdk returns the raw { data, 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.search({ limit: 100, cursor })
  for (const contact of page.data) {
    console.log(contact.email)
  }
  cursor = page.pagination?.hasMore ? page.pagination.cursor : undefined
} while (cursor)

For automation runs, swap brew.contacts.search → brew.automations.runs.list with the same shape (runs use a GET list, so its filters are query params). To read one run, call brew.automations.runs.get(automationRunId) instead: a detail read is not a one-row page.

Filter Combinations

POST /v1/contacts/search takes search + sort + filter in one JSON body:

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 supports time-range and status filters:

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

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 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. Comment threads order by their latest message the same way, so a reply during the walk moves its thread to the front.
• 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.
• Insights refuse a stale cursor. GET /v1/insights ranks its findings again on every request, and its cursor remembers which findings it already returned. A change below the cursor is served when its page comes. A finding added or removed above the cursor, or re-ranked across it, makes the next page 400 INVALID_REQUEST with param: "cursor" rather than skip or repeat findings, so read again from the first page without cursor, with the same state and severity. A walk that reaches its last page has returned every finding exactly once, as the list stands then. A cursor sent with a different state or severity is refused the same way.
• A short page is not the last page. GET /v1/notifications reads a bounded slice of stored rows per page and leaves out the rows your key can’t see, so a page can hold fewer rows than limit, even none, while hasMore is true. Stop when hasMore is false, never because a page came back short. A type filter your credential can’t see answers an empty page rather than an error.
• A comment thread pages its own messages. With include=messages, a thread whose older messages didn’t fit carries a messagesCursor. Send it back with that thread’s commentId (not with cursor) for the next older slice, until it comes back null. See Comments.
• 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.

Related

• 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?

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.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

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.