How does API pagination work?

Question

Accepted Answer

List endpoints return paginated results. Use the `page` and `per_page` query parameters:

```bash
# Page 1 (default), 20 items
curl "https://api.matcraft.ai/api/v1/materials?elements=O&per_page=20&page=1"

# Page 2
curl "https://api.matcraft.ai/api/v1/materials?elements=O&per_page=20&page=2"
```

The response includes a `meta` object with pagination info:

```json
{
  "meta": {
    "total": 85432,
    "page": 1,
    "per_page": 20,
    "took_ms": 45
  }
}
```

- Maximum `per_page` value is 100
- Pages are 1-indexed
- `total` gives the full count of matching materials

For iterating through all results, loop through pages until `page * per_page >= total`.

Related Questions