> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through large collections with page, limit, and cursor parameters.

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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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"
```

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="Fetch the first page">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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"
    ```
  </Step>

  <Step title="Take the last id">
    Read the `id` of the final item in the `data` array.
  </Step>

  <Step title="Request the next page">
    Pass that `id` as `lt`.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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"
    ```
  </Step>

  <Step title="Repeat until empty">
    Continue until a page returns fewer than `limit` items.
  </Step>
</Steps>

## Example loop

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
```

<Note>
  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.
</Note>


## Related topics

- [MCP tools reference](/mcp/tools-reference.md)
- [Search companies, deals, people, documents, and activities](/guides/search.md)
- [API reference](/api-reference/introduction.md)
- [List companies](/api-reference/companies/list-companies.md)
- [Data model](/concepts/data-model.md)