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

# Pagination and cutoffs

> How to page through lists, what a cut-off read means and how to ask for more with «read more».

On-chain queries read lists that can be huge. The API sets caps to answer in time and at a predictable cost, and it
always **declares** what was left out. There are two different mechanisms: paginated lists and capped reads.

## Paginated lists

Endpoints that return a long list of already computed results are paginated with `offset` and `limit`. For example,
`POST /v1/counterparties`, which returns **all** counterparties of an address, sorted by USD value:

```bash Request theme={null}
curl -X POST https://app.blockgence.com/v1/counterparties \
  -H "Authorization: Bearer $BKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x098b716b8aaf21512996dc57eb0615e2383e2f96", "direction": "both", "limit": 20}'
```

```json Response theme={null}
{
  "address": "0x098b…2f96",
  "chain": "ethereum",
  "direction": "both",
  "total": 186,
  "offset": 0,
  "returned": 20,
  "has_more": true,
  "next_offset": 20,
  "counterparties": [
    {
      "address": "0x1a2a…",
      "label": "Axie Infinity: Ronin Bridge",
      "category": "bridge",
      "direction": "in",
      "value_usd": 342000000.0,
      "value": 173600.0,
      "tx_count": 2,
      "asset": "ETH",
      "first_ts": 1648041417,
      "last_ts": 1648041420
    }
  ]
}
```

Ask for the next page with `offset = next_offset` until `has_more` is `false`. `limit` accepts up to 100.

> [!NOTE]
>
> Each page is a query and is charged. If the source cannot read the address, the response is
> `503 source_unavailable`, never «0 counterparties».

## Capped reads

To build a trace, the API reads each address's history from the data sources. That read has a **row cap per list**.
When an address has more activity than fits, part of its history is not read, and the response declares it in
`degraded_sources` and on the affected node (`coverage_gaps`):

| `stage` | What was left unread |
| - | - |
| `transfers.truncated` | A block range **inside** the trace. That address's inflows and outflows in that range are not in the result. |
| `transfers.truncated_outside` | A range **outside** the trace: before the traced funds arrived or after they left. It does not change the flows being followed. |
| `transfers.completion_failed` | The extra read meant to complete the trace's range failed. The reason is in `reason`. |
| `messages.truncated` | The scan of on-chain messages did not reach the oldest range. |

Each cutoff's message says which blocks of which list are missing. Whatever was left out is **not** «no movements».

> [!NOTE]
>
> The read focuses on the trace: on a cut-off node, it first reads from the block where the traced funds arrived
> forward (or from where they left, backward). That way the cap is spent on what matters for following the money, not
> on the address's newest activity.

## «Read more»

To keep reading a node that ended with `transfers.truncated`, request it again in `POST /v1/trace` as `address`, with
its `since` and with `read_more`:

**read\_more** `integer` (default: 0)

Extra read steps for the seed node: each step adds another row cap per list. It goes from 0 to 9; a larger value is
capped.

**forward** `boolean` (default: true)

With `false` it does not expand forward and only reads backward (`back_hops`): useful to re-read a parent.

```bash theme={null}
curl -X POST https://app.blockgence.com/v1/trace \
  -H "Authorization: Bearer $BKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x098b716b8aaf21512996dc57eb0615e2383e2f96", "chain": "ethereum", "since": 1648041417, "read_more": 1}'
```

Whatever was already read for that node in the last 15 minutes is not requested from the source again: each step only
costs its new reads. If the cutoff remains, raise `read_more` (2, 3…).

In the web app it is the node's **Leer más** (read more) button.

## Other declared caps

Some responses cap their inner lists so they do not grow without limit. When they cut, they say so with a field of their
own:

* a total counter and the trimmed list (for example, `discarded_total` with `candidates_truncated: true`);
* `*_truncated: true` when a list was cut (`refs_truncated`, `contracts_truncated`);
* a summary of what was dropped, such as `unpriced` in counterparties: how many rows of tokens without a published price
  were left out, and from which contracts.

Each endpoint's reference says what cap it has and how it declares it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.