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

# Pagination

> limit/offset pagination across list endpoints

Shoal API uses simple `limit` and `offset` query parameters on list endpoints, but bulk and export-style routes have tighter caps than scoped evaluation routes.

## Parameters

* `limit`: number of items to return
* `offset`: number of items to skip

Values above the maximum are silently capped. Negative values are clamped to the minimum (1 for `limit`, 0 for `offset`).

## Example

```bash theme={null}
curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25&offset=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To fetch the next page, increase `offset` by `limit`.

## Caps

Common caps:

| Endpoint class                       | Default limit | Max limit | Max offset |
| ------------------------------------ | ------------- | --------- | ---------- |
| Scoped list routes                   | 50            | 50        | 500        |
| `/v1/radar/all` and `/v1/signal/all` | 25            | 25        | 250        |
| `/v1/organizations/all`              | 25            | 25        | 100        |

Use the `since` parameter to filter by time instead of paginating deeply. Bulk `/all` routes are intentionally constrained to protect the higher-value historical and export surfaces.

## Cursor-Based Pagination

For large result sets that exceed offset limits, radar and signal endpoints support cursor-based pagination via the `cursor` and `next_cursor` fields.

### How It Works

1. Make a normal request with `since` (and optionally `limit`).
2. If the response includes a non-null `next_cursor`, more results are available.
3. Pass `next_cursor` as the `cursor` query parameter on your next request, along with the **same `since` value**.
4. Repeat until `next_cursor` is `null`.

When `cursor` is provided, `offset` is ignored.

### Example

```bash theme={null}
# First page
curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response includes: "next_cursor": "eyJ0cyI6Ii4uLiIsImlkIjo2NTB9"

# Next page — pass cursor, keep the same since value
curl "https://api.shoal.xyz/v1/radar/all?since=2026-04-04T00:00:00Z&limit=25&cursor=eyJ0cyI6Ii4uLiIsImlkIjo2NTB9" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Details

* The cursor is a base64url-encoded JSON token. Treat it as opaque — do not decode or modify it.
* The `since` parameter is **required** when using `cursor`. The cursor is bound to the original query context; changing `since` between pages will return an error.
* On `/v1/radar/all` and `/v1/signal/all`, `since` must also remain within the allowed recent lookback window.
* `offset` is ignored when `cursor` is present.
* When `next_cursor` is `null`, you have reached the end of the result set.