Pagination

List endpoints return results in pages. Use query parameters to control page size, navigate pages, and sort results.

Parameters

Parameter	Type	Default	Description
`limit`	integer	`100`	Items per page. Clamped to the range 1 to 1000.
`page`	integer	`1`	Page number, starting at 1. Maximum 100.
`lt`	string	None	Cursor: return items whose `id` is less than this value.
`sort`	string	`id`	Field to sort by.
`direction`	string	`desc`	Sort direction: `asc` or `desc`.

By default, results are sorted by id descending (newest first).

Offset pagination

The simplest approach is page-based. Request successive pages until you receive fewer items than limit.

# First page of 50 companies
curl "https://api.metal.ai/v1/companies?limit=50&page=1" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

# Second page
curl "https://api.metal.ai/v1/companies?limit=50&page=2" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

Offset pagination is capped: page cannot exceed 100. To iterate beyond the first 100 pages, or to page reliably through a dataset that is changing, use cursor pagination instead.

Cursor pagination

Cursor pagination uses the lt (“less than”) parameter with the id of the last item you saw. Because results default to descending id order, passing the last id returns the next, older page. This is stable even as new records are created.

Fetch the first page

curl "https://api.metal.ai/v1/companies?limit=100" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

Take the last id

Read the id of the final item in the data array.

Request the next page

Pass that id as lt.

curl "https://api.metal.ai/v1/companies?limit=100&lt=665f1c2a9b1e4a0012a3b4c5" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

Repeat until empty

Continue until a page returns fewer than limit items.

Example loop

import os
import requests

headers = {
    "x-metal-client-id": os.environ["METAL_CLIENT_ID"],
    "x-metal-api-key": os.environ["METAL_API_KEY"],
}

url = "https://api.metal.ai/v1/companies"
params = {"limit": 100}
companies = []

while True:
    res = requests.get(url, headers=headers, params=params)
    res.raise_for_status()
    page = res.json()["data"]
    if not page:
        break
    companies.extend(page)
    params["lt"] = page[-1]["id"]
    if len(page) < params["limit"]:
        break

print(f"Fetched {len(companies)} companies")

Sorting

Override the default order with sort and direction:

curl "https://api.metal.ai/v1/companies?sort=canonicalName&direction=asc" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

When sorting by a field other than _id, prefer offset pagination. The lt cursor is based on id ordering and is most reliable with the default sort.

Core tasks

API essentials

Parameters

Example loop

Sorting

​Parameters

​Offset pagination

​Cursor pagination

​Example loop

​Sorting

Parameters

Offset pagination

Cursor pagination

Example loop

Sorting