> For the complete documentation index, see [llms.txt](https://developer.abacum.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.abacum.ai/essentials/concepts/pagination.md).

# Pagination

How to page through results on the endpoints that return lists.

Two endpoints paginate their results: `GET /public-api/search` with a single `type`, and `GET /public-api/spaces`. The other list endpoints take no pagination parameters.

| Parameter   | Default | Limit                               | Meaning             |
| ----------- | ------- | ----------------------------------- | ------------------- |
| `page`      | `1`     | Starts at `1`                       | The page to return. |
| `page_size` | `25`    | `100`; a larger value becomes `100` | Items on each page. |

A `page_size` that is not a positive integer is ignored, and the default applies. An invalid `page` is an error: see [A page beyond the last](#a-page-beyond-the-last).

```bash
curl "https://api.abacum.io/public-api/spaces?page=2&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Read the pagination details

The response carries the details in `metadata.pagination`:

| Field         | Meaning                                           | Search | Spaces |
| ------------- | ------------------------------------------------- | ------ | ------ |
| `count`       | Total number of matches.                          | Yes    | Yes    |
| `next`        | URL of the next page, or `null` on the last page. | Yes    | Yes    |
| `previous`    | URL of the previous page, or `null` on the first. | Yes    | Yes    |
| `page`        | The page you requested.                           | Yes    | No     |
| `page_size`   | Items on each page.                               | Yes    | No     |
| `total_pages` | Number of pages.                                  | Yes    | No     |

To read every result, request page `1`, then follow `next` until it is `null`.

## Search with `type=all`

With `type=all`, the response is not paginated. It returns up to 5 results for each entity type, and it ignores `page` and `page_size`.

## A page beyond the last

A `page` that is not a positive integer, or that is past the last page, returns `404`. The body is `{"detail": "Invalid page."}`.

## Read every page

This loop reads every Space. It uses the `headers` from Code samples.

```python
import requests

url = "https://api.abacum.io/public-api/spaces"
params = {"page": 1, "page_size": 100}
spaces = []

while True:
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    body = response.json()
    spaces.extend(body["data"])
    if not body["metadata"]["pagination"]["next"]:
        break
    params["page"] += 1
```

Keep each request inside the rate limits. The default limit is 20 requests per minute.