## Overview

A custom HTTP tool lets the Robô call your API. When that API returns lists, it almost always returns
them in **pages** — and without configuring this the Robô reads only the first one and answers with
part of the data, unaware that the rest exists.

**Pagination** fixes that. You tell it which kind it is, where the items live in the response, and
how many pages to walk. And, optionally, **how many items to ask for per page**.

## Prerequisites

- A Robô with at least one custom HTTP tool configured.
- Knowing how your API paginates: by page number or by cursor.
- Account administrator access.

## Step by step

1. Open **Settings → Robôs** and edit the Robô.
2. Go to **Custom tools** and open the tool.
3. Under **Pagination**, pick the type: **No pagination**, **Page number** or **Cursor**.
4. Fill in the pagination fields (see the table below).
5. Save.

## Settings & options

| Field | What it is for |
|---|---|
| Type | **No pagination**, **Page number** or **Cursor** |
| Page/cursor param | The parameter name your API uses to advance (`page`, `cursor`…) |
| Items path (array) | Where the result list sits in the response |
| Next cursor path | Where the next page's cursor comes back (cursor type only) |
| Start page | Which page to begin from |
| Max pages | Ceiling on how many pages one call walks |
| **Page size param** | Your API's page-size parameter name (`per_page`, `limit`…) |
| **Items per page** | The value sent in that parameter |

The last two are **optional and travel together**: leaving them empty means the parameter is not
sent, and the API decides the size.

## Use cases

- **An API that defaults to 100 items per page**: set `per_page` = 20. Each page becomes a chunk
  that fits comfortably in context, and **Max pages** controls how far to go.
- **An API that returns everything at once**: if it accepts a limit parameter, use it. One huge
  response eats the model's context and leaves little room for reasoning and for the reply.
- **A cursor API**: fill in **Next cursor path**; the page size still applies.

## Tips, limits & best practices

- Start modest (10 to 25) and raise it only if answers come back incomplete.
- A smaller page size with a larger **Max pages** usually beats one giant page: the Robô can stop
  once it has found what it needed.
- The parameter must exist in your API. A name it does not know is usually ignored silently — and
  you are left thinking the setting had no effect.
- Leaving it empty is a valid choice when the API's own default is already reasonable.

## Troubleshooting

**The Robô answers with partial data.** Either pagination is set to **No pagination**, or **Max
pages** is too low for the volume the query returns.

**The tool is slow.** Every page is one HTTP call. Lower **Max pages**, or raise items per page to
fetch the same volume in fewer round trips.

**I changed items per page and nothing changed.** Confirm the parameter name against your API's
docs — `per_page`, `limit`, `page_size` and `pageSize` are all common, and only one is right.

**The list comes back empty.** The **Items path** is not pointing at the right array in the response.

## See also

- [Advanced model settings](/hc/ajuda/articles/maestro-brain-ajustes-avancados-do-modelo-en)
- [Maestro tools by module](/hc/ajuda/articles/maestro-brain-ferramentas-maestro-por-modulo-en)