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

​
Parameters

ParameterTypeDefaultDescription
limitinteger100Items per page. Clamped to the range 1–1000.
pageinteger1Page number, starting at 1. Maximum 100.
ltstring—Cursor: return items whose id is less than this value.
sortstring_idField to sort by.
directionstringdescSort 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.
1

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"
2

Take the last id

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

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"
4

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.