Pagination

List endpoints paginate. Awardee uses two styles depending on the resource: offset for catalog resources, cursor for high-volume streams. Both cap page_size/limit at 100 and default to 25.

Offset pagination

Used by catalog resources like /chatbots, /articles, /products, /objects, /qr-groups. Pages are 1-indexed. Query parameters

Param	Type	Default	Cap	Notes
`page`	integer	`1`	—	1-indexed.
`page_size`	integer	`25`	`100`	Number of items per page.

Response envelope

{
  "object": "list",
  "total": 137,
  "page": 1,
  "page_size": 25,
  "data": [
    /* … */
  ]
}

total is the filtered count, so it changes when you pass query filters. Use Math.ceil(total / page_size) for the page count.

curl "https://api.awardee.com/v1/chatbots?page=2&page_size=50" \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

async function* walkChatbots() {
  let page = 1
  while (true) {
    const res = await fetch(
      `https://api.awardee.com/v1/chatbots?page=${page}&page_size=100`,
      {
        headers: {
          Authorization: "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
        },
      }
    )
    const { data, total, page_size } = await res.json()
    for (const item of data) yield item
    if (page * page_size >= total) return
    page += 1
  }
}

for await (const chatbot of walkChatbots()) {
  // …
}

import requests

def walk_chatbots():
    page = 1
    while True:
        res = requests.get(
            "https://api.awardee.com/v1/chatbots",
            params={"page": page, "page_size": 100},
            headers={
                "Authorization": "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
            },
        )
        body = res.json()
        for item in body["data"]:
            yield item
        if page * body["page_size"] >= body["total"]:
            return
        page += 1

for chatbot in walk_chatbots():
    pass

Offset pagination is not stable under concurrent inserts. If new resources are created between page fetches, you may see the same item twice (or skip one) at page boundaries. For high-mutation feeds, prefer cursor pagination — it’s stable.

Cursor pagination

Used by high-volume streams: /conversations, /conversations/{id}/messages, /qr-codes/{id}/scans, /submissions, /articles (when sorted by created_at descending), and similar feeds. Cursors are opaque base64url strings — never parse, predict, or hand-construct one. Query parameters

Param	Type	Default	Cap	Notes
`cursor`	string	absent	—	Pass `next_cursor` from the previous response. Omit on the first page.
`limit`	integer	`25`	`100`	Number of items in this page.

Response envelope

{
  "object": "list",
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yM1QxMDoxNDozM1oiLCJpZCI6IjFiNGM0ZjVkLTllOGEtN2MzYi0yYTFkLTBmOWU4ZjNhOWQyZSJ9",
  "data": [
    /* … */
  ]
}

When has_more is false, next_cursor is null and you’re done.

# First page
curl "https://api.awardee.com/v1/conversations?limit=100" \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

# Subsequent page (paste next_cursor verbatim, URL-encoded)

curl "https://api.awardee.com/v1/conversations?limit=100&cursor=eyJjcmVhdGVkX2F0Ijoi..." \
 -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

async function* walkConversations() {
  let cursor = null
  while (true) {
    const url = new URL("https://api.awardee.com/v1/conversations")
    url.searchParams.set("limit", "100")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, {
      headers: {
        Authorization: "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e",
      },
    })
    const { data, has_more, next_cursor } = await res.json()
    for (const item of data) yield item
    if (!has_more) return
    cursor = next_cursor
  }
}

import requests

def walk_conversations():
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "https://api.awardee.com/v1/conversations",
            params=params,
            headers={
                "Authorization": "Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
            },
        )
        body = res.json()
        for item in body["data"]:
            yield item
        if not body["has_more"]:
            return
        cursor = body["next_cursor"]

Invalid cursors

Tampered or corrupted cursors return:

{
  "error": "invalid_cursor",
  "message": "Pagination cursor is malformed.",
  "request_id": "req_8fK2x9aLp0qR"
}

Cursors are stable across deploys and signed. If a value that worked yesterday stops working, it was likely truncated in transit. Pass the entire next_cursor string verbatim, including any trailing = characters (URL-encode them — %3D).

Which style does an endpoint use?

The OpenAPI spec is authoritative. As a heuristic: anything that emits webhook events at high volume (conversation.created, qr_code.scanned, page.submission.created, etc.) uses cursor pagination. Everything else uses offset.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

Invalid cursors

Which style does an endpoint use?

​Offset pagination

​Cursor pagination

​Invalid cursors

​Which style does an endpoint use?

Offset pagination

Cursor pagination

Invalid cursors

Which style does an endpoint use?