Pagination

List endpoints return results one 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

Number of 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 may exist. A page with no records always has has_more: false, except when partial is true.

pagination.partialboolean

Only on a filtered message read (q) that ran out of time, about 2 seconds, before finding a match. data is empty but the range isn’t finished: follow next_cursor. This is the only case where an empty page isn’t the end. Absent otherwise.

A filtered read keeps looking until its page has at least one match or the range runs out, so a sparse search doesn’t hand you empty pages. A page with matches can still be shorter than page[limit], with has_more: true; keep following the cursor.

Ordering

Each list endpoint documents its order. Messages are newest first unless you pass order=asc, and group_by=conversation groups them by conversation. Conversations are ordered by latest activity, and members by name. Ties break on ID.

A cursor keeps the order your first request saw, so you can retry a page safely. You never skip or repeat records, even when new messages arrive while you page.

Fetch every page

cURL

Request


curl -g "https://api.bloomtext.com/v1/patient-messages?after=2026-09-21&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}`) // path may include ?q=…
    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('/patient-messages?after=2026-09-21')) {
  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, **query):
    params = {**query, "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("/patient-messages", after="2026-09-21"):
    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, params url.Values) ([]json.RawMessage, error) {
	var all []json.RawMessage
	params.Set("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, query = {})
  Enumerator.new do |yielder|
    params = query.merge("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("/patient-messages", "after" => "2026-09-21").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.
Request large pages. page[limit]=100 uses fewer requests against your rate limit.
Follow new messages with after, not cursors. Request again with after set to the newest message you’ve seen. See Read messages.