Pagination

The Moonbase API uses cursor-based pagination for list endpoints that return multiple items. These endpoints return one page of results per API call. Each page contains up to 20 results by default.

Response structure

The API returns items in the data property of the response. Refer to the individual endpoints for the ordering of items since they vary based on the endpoint. Example: First page (with more results)

{
  "type": "list",
  "data": [
    {
      "id": "1CLJt2ub4MavjpDF6NV14F",
      "type": "item",
      "values": {
        "name": {"type": "value/text/single_line", "data": "OrbGrid"},
        "updated_at": {"type": "value/datetime", "data": "2025-02-17T16:00:00.000Z"}
      }
    },
    {
      "id": "1CLJt2ub4MavjpDF6NV14G",
      "type": "item",
      "values": {
        "name": {"type": "value/text/single_line", "data": "TechStart Inc"},
        "updated_at": {"type": "value/datetime", "data": "2025-02-17T16:00:00.000Z"}
      }
    },
    {
      "id": "1CLJt2ub4MavjpDF6NV14H",
      "type": "item",
      "values": {
        "name": {"type": "value/text/single_line", "data": "Global Systems"},
        "updated_at": {"type": "value/datetime", "data": "2025-02-17T16:00:00.000Z"}
      }
    }
    ...
  ],
  "meta": {
    "cursors": {
      "next": "eyJpZCI6IjFDUDY0dkc2SkhuSkhLUEpLTDVpblcifQ"
    }
  }
}

Example: Middle page (both prev and next)

{
  "type": "list",
  "data": [ /* items omitted for brevity */ ]
  "meta": {
    "cursors": {
      "prev": "eyJpZCI6IjFDUzY4Ykp0Z3k5ZGFzOGFzYTg3bmV3OTJuMHE4a2w4MWpBIn0",
      "next": "eyJpZCI6IjFDUDY0dkc2SkhuSkhLUEpLTDVpblcifQ"
    }
  }
}

The next cursor will not be present if there are no more pages to fetch. prev cursor appears when previous pages exist. Enables bidirectional navigation.

Do not pass both before and after in the same request. Cursors are opaque strings—do not parse or modify them—and should be URL-encoded when used in query parameters.

Pagination parameters

Control pagination using these query parameters:

limit: (Integer) — Maximum number of items to return per page. Must be between 1 and 100. Defaults to 20 if not specified.
after: (String) — Returns results starting immediately after the item identified by this cursor. Use the next cursor from a previous response to fetch the next page.
before: (String) — Returns results starting immediately before the item identified by this cursor. Use the prev cursor from a previous response to fetch the previous page.

Cursors do not expire and remain valid indefinitely. Using an invalid cursor will return a 400 Bad Request error.

Navigating pages

Auto-pagination (recommended)

Moonbase SDKs provide methods to automatically iterate through all items across all pages:

async function fetchAllItems(params) {
  const allItems = [];
  // Automatically fetches more pages as needed.
  for await (const item of moonbase.collections.items.list('people', { limit: 5 })) {
    allItems.push(item);
  }
  return allItems;
}

iter := client.Collections.Items.ListAutoPaging(
	context.TODO(),
	"people",
	moonbase.CollectionItemListParams{
		Limit: moonbase.Int(5),
	},
)
// Automatically fetches more pages as needed.
for iter.Next() {
	item := iter.Current()
	fmt.Printf("%+v\n", item)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

page = moonbase.collections.items.list("people", limit: 5)

# Fetch single item from page.
item = page.data[0]
puts(item.id)

# Automatically fetches more pages as needed.
page.auto_paging_each do |item|
  puts(item.id)
end

from moonbase import Moonbase

moonbase = Moonbase()

all_items = []
# Automatically fetches more pages as needed.
for item in moonbase.collections.items.list(
    collection_id="people",
    limit=5,
):
    # Do something with item here
    all_items.append(item)
print(all_items)

# Or, asynchronously:

import asyncio
from moonbase import AsyncMoonbase

moonbase = AsyncMoonbase()

async def main() -> None:
    all_items = []
    # Iterate through items across all pages, issuing requests as needed.
    async for item in moonbase.collections.items.list(
        collection_id="people",
        limit=5,
    ):
        all_items.append(item)
    print(all_items)


asyncio.run(main())

Single page requests

Request one page at a time:

let page = await moonbase.collections.items.list('people', { limit: 5 });
for (const item of page.data) {
  console.log(item);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

people, err := client.Collections.Items.List(
	context.TODO(),
	"people",
	moonbase.CollectionItemListParams{
		Limit: moonbase.Int(5),
	},
)
for page != nil {
	for _, item := range page.Data {
		fmt.Printf("%+v\n", item)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	panic(err.Error())
}

page = moonbase.collections.items.list("people", limit: 5)

if page.next_page?
  new_page = page.next_page
  puts(new_page.data[0].id)
end

first_page = await moonbase.collections.items.list(
    collection_id="people",
    limit=5,
)
if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Remove `await` for non-async usage.

Manual pagination with cURL

Make an initial API call to list items

  curl https://api.moonbase.ai/v0/collections/organizations/items \
  --header 'Authorization: Bearer <token>'

For authentication details, see the Moonbase authentication guide.

Check for pagination cursors in the response

If meta.cursors.next is missing, all items have been retrieved
If the next cursor is present, use it with the after parameter to fetch the next page
If the prev cursor is present, use it with the before parameter to fetch the previous page

Fetch next page:

  curl https://api.moonbase.ai/v0/collections/organizations/items?after=eyJpZCI6IjFDUDY0dkc2SkhuSkhLUEpLTDVpblcifQ \
  --header 'Authorization: Bearer <token>'

Fetch previous page:

  curl https://api.moonbase.ai/v0/collections/organizations/items?before=eyJpZCI6IjFDUDY0dkc2SkhuSkhLUEpLTDVpblcifQ \
  --header 'Authorization: Bearer <token>'

Repeat until all required data is processed

Continue using the cursors from each response to navigate forward or backward through results.

⌘I

Introduction

Core Concepts

API Reference

Response structure

Navigating pages

Single page requests

​Response structure

​Pagination parameters

​Navigating pages

​Auto-pagination (recommended)

​Single page requests

​Manual pagination with cURL

Response structure

Pagination parameters

Navigating pages

Auto-pagination (recommended)

Single page requests

Manual pagination with cURL