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

# Pagination

> Cursor-based pagination for list endpoints

List endpoints use **cursor-based keyset pagination** for consistent, efficient paging through large result sets.

## How it works

1. Make your first request (no cursor):

```bash theme={null}
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/signals?keyword=AI&limit=10"
```

2. Check `has_more` and `next_cursor` in the response (the list itself is under a resource key: `signals` for `/v1/signals`, `entities` for `/v1/entities`):

```json theme={null}
{
  "signals": [...],
  "has_more": true,
  "next_cursor": "c2cudjEuOGYzYTFjOWUuNDU2"
}
```

3. Pass `next_cursor` as the `cursor` parameter for the next page:

```bash theme={null}
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/signals?keyword=AI&limit=10&cursor=c2cudjEuOGYzYTFjOWUu..."
```

4. Repeat until `has_more` is `false`.

## Parameters

| Parameter | Type    | Default | Range | Description                          |
| --------- | ------- | ------- | ----- | ------------------------------------ |
| `limit`   | integer | 25      | 1-50  | Results per page                     |
| `cursor`  | string  | n/a     | n/a   | Opaque cursor from previous response |

## Paginated endpoints

* `GET /v1/signals`: signals list
* `GET /v1/entities`: entities list

## Why cursor-based?

Cursor pagination is more efficient and consistent than offset-based pagination:

* **No skipped/duplicated results** when data changes between pages
* **Consistent performance** regardless of page depth (no `OFFSET N` scan)
* **Opaque cursors**: the format may change without breaking clients