Pagination

Every paginated list endpoint in the Bird API uses the same cursor-based contract: the same request parameters, the same response envelope, the same cursor semantics. Learn it once on GET /v1/email/messages and it applies everywhere.

A small number of bounded collections (for example, billing plans) return a plain {"data": [...]} array with no pagination fields at all. An endpoint either implements this contract in full or not at all, never partially.

Request parameters

Parameter	Type	Description
limit	integer	Maximum items per page. Between 1 and 100; defaults to 25.
starting_after	string	Cursor from the next_cursor field of a previous response. Returns items immediately after that position.
ending_before	string	Cursor from the prev_cursor field of a previous response. Returns items immediately before that position.
include_total	boolean	When true, the response includes a total count. Defaults to false. Available on management endpoints only. High-volume data endpoints (messages, events, suppressions) do not accept it.

Cursors are opaque: they are not resource IDs, they encode the sort position internally, and their format can change at any time. Receive them in responses and pass them back unchanged. A malformed or expired cursor returns a 422 with code E01012 InvalidCursor. Restart pagination without a cursor.

Most list endpoints also accept resource-specific sort and order parameters; the per-endpoint reference documents the allowed sort fields. Changing the sort invalidates cursors from the previous sort order.

Response envelope

कोड उदाहरण

{
  "data": [{ "...": "..." }],
  "next_cursor": "WyIyMDI2LTA2LTEwVDA5OjE0OjAzWiIsICJtc2dfMDFr...",
  "prev_cursor": null,
  "refresh_cursor": "WyIyMDI2LTA2LTEwVDEyOjAwOjAwWiIsICJtc2dfMDFr...",
  "total": 1432
}

Field	Description
data	The page of items.
next_cursor	Pass back as starting_after to fetch the next page. null when no next page exists, which is the signal to stop.
prev_cursor	Pass back as ending_before to step backward. null when no previous page exists (always null on the first page).
refresh_cursor	A refresh anchor: save it, then pass it back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty.
total	Total items matching the request's filters across all pages. Present only when include_total=true was passed; otherwise null/absent.

next_cursor and prev_cursor are independent: each is null exactly when its own direction has no further page. Check next_cursor to decide whether to fetch again.

Paging through results

The first request carries no cursor. Every one after it passes the previous response's next_cursor as starting_after, and you stop when that comes back null.

Every Bird SDK exposes list endpoints in two modes: lazy iteration that fetches pages transparently as you consume items, and a single-page accessor for manual cursor control.

for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}

for message in client.email.list(status="delivered"):
    print(message.id)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

bird email list

curl -X GET "https://{region}.platform.bird.com/v1/email/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Rate limits

List endpoints share the list rate-limit group, separate from reads of individual resources and from writes. Paginating through a large collection never consumes your send or management quota. Lazy iteration issues one request per page, so a tight loop over a large collection draws down the list group at one request per limit items; use limit=100 for bulk reads.

Email messages: a representative paginated list endpoint
SDK concepts: iteration and single-page accessors across the SDKs
Rate limits: groups, headers, and handling 429s

Pagination

Request parameters

Response envelope

Paging through results

Rate limits

Related