Pagination

Every list endpoint returns results a page at a time, in a stable order, with an opaque cursor for the next page.

Response


{
  "data": [ { "id": "4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1", "...": "..." } ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjRjYmZkYjUwIn0",
    "has_more": true
  }
}

Parameters

page[limit]integer

How many records to return. Defaults to 50, maximum 100.

page[after]string

The next_cursor from the previous page. Omit it for the first page.

Response fields

dataarrayRequired

The records on this page, in stable order.

pagination.next_cursorstring or nullRequired

Pass as page[after] to get the next page. null on the last page.

pagination.has_morebooleanRequired

Whether another page exists.

Ordering

Results are ordered by creation time, oldest first, with the ID as a tiebreaker. The order never changes between requests, so retrying a page is always safe and never skips or repeats records.

Fetch every page

cURL

Request


curl "https://api.bloomtext.com/v1/conversations/e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0/messages?page[limit]=100&page[after]=eyJpZCI6IjRjYmZkYjUwIn0" \
  -H "Authorization: Bearer $BLOOMTEXT_API_KEY"

JavaScript

paginate.mjs


async function* listAll(path) {
  let cursor = null
  do {
    const url = new URL(`https://api.bloomtext.com/v1${path}`)
    url.searchParams.set('page[limit]', '100')
    if (cursor) url.searchParams.set('page[after]', cursor)
 
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}` },
    })
    if (!response.ok) throw new Error(`BloomText API error: ${response.status}`)
 
    const { data, pagination } = await response.json()
    yield* data
    cursor = pagination.has_more ? pagination.next_cursor : null
  } while (cursor)
}
 
for await (const message of listAll('/conversations/e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0/messages')) {
  console.log(message.id)
}

Python

paginate.py


import os
 
import requests
 
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BLOOMTEXT_API_KEY']}"
 
 
def list_all(path):
    params = {"page[limit]": 100}
    while True:
        response = session.get(f"https://api.bloomtext.com/v1{path}", params=params)
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if not page["pagination"]["has_more"]:
            return
        params["page[after]"] = page["pagination"]["next_cursor"]
 
 
for message in list_all("/conversations/e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0/messages"):
    print(message["id"])

Go

paginate.go


type page struct {
	Data       []json.RawMessage `json:"data"`
	Pagination struct {
		NextCursor *string `json:"next_cursor"`
		HasMore    bool    `json:"has_more"`
	} `json:"pagination"`
}
 
func listAll(path string) ([]json.RawMessage, error) {
	var all []json.RawMessage
	params := url.Values{"page[limit]": {"100"}}
	for {
		req, _ := http.NewRequest("GET", "https://api.bloomtext.com/v1"+path+"?"+params.Encode(), nil)
		req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
		res, err := http.DefaultClient.Do(req)
		if err != nil {
			return nil, err
		}
		var p page
		err = json.NewDecoder(res.Body).Decode(&p)
		res.Body.Close()
		if err != nil {
			return nil, err
		}
		all = append(all, p.Data...)
		if !p.Pagination.HasMore {
			return all, nil
		}
		params.Set("page[after]", *p.Pagination.NextCursor)
	}
}

Ruby

paginate.rb


require "net/http"
require "json"
 
def list_all(path)
  Enumerator.new do |yielder|
    params = { "page[limit]" => 100 }
    loop do
      uri = URI("https://api.bloomtext.com/v1#{path}")
      uri.query = URI.encode_www_form(params)
      request = Net::HTTP::Get.new(uri)
      request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
 
      page = JSON.parse(response.body)
      page["data"].each { |record| yielder << record }
      break unless page["pagination"]["has_more"]
 
      params["page[after]"] = page["pagination"]["next_cursor"]
    end
  end
end
 
list_all("/conversations/e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0/messages").each { |message| puts message["id"] }

Tips

Treat cursors as opaque. Don’t parse, build, or store them long-term. A cursor is valid for 24 hours.
Use the biggest page you need. page[limit]=100 means fewer requests against your rate limit.
Sync incrementally. To pick up new messages, keep the last next_cursor you saw and resume from it, or use webhooks instead of polling.