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

# Cursor-based pagination

> Navigate large result sets with cursor-based pagination. Learn how to iterate through all pages, handle concurrent changes, and avoid common pitfalls.

List endpoints return results in pages. Yoshi uses **cursor-based pagination** — each response includes an opaque cursor that points to the next page.

## How it works

Send a request with an optional `limit` to control page size:

```bash theme={null}
curl "https://api.yoshi.ai/transactions?limit=50" \
  -H "Authorization: Bearer yoshi_YOUR_KEY"
```

The response includes pagination fields alongside `data`:

```json theme={null}
{
  "data": [...],
  "has_more": true,
  "cursor": "eyJpZCI6InR4bl8xMjM0NTYifQ==",
  "count": 50,
  "meta": { ... }
}
```

| Field      | Description                                                                       |
| ---------- | --------------------------------------------------------------------------------- |
| `has_more` | `true` if more pages exist                                                        |
| `cursor`   | Opaque string to pass as `?cursor=` on the next request. `null` on the last page. |
| `count`    | Number of items in this page                                                      |

To get the next page, pass the cursor from the previous response:

```bash theme={null}
curl "https://api.yoshi.ai/transactions?limit=50&cursor=eyJpZCI6InR4bl8xMjM0NTYifQ==" \
  -H "Authorization: Bearer yoshi_YOUR_KEY"
```

## Iterate all pages

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Yoshi from "@yoshi-ai/sdk";

  const yoshi = new Yoshi();

  // Auto-pagination with the SDK
  const allTransactions = [];
  for await (const tx of yoshi.transactions.list({ limit: 100 })) {
    allTransactions.push(tx);
  }

  console.log(`Fetched ${allTransactions.length} transactions`);
  ```

  ```python Python theme={null}
  from yoshi import Yoshi

  yoshi = Yoshi()

  all_transactions = []
  for tx in yoshi.transactions.list(limit=100):
      all_transactions.append(tx)

  print(f"Fetched {len(all_transactions)} transactions")
  ```

  ```typescript Manual pagination theme={null}
  let cursor: string | undefined;
  const allTransactions = [];

  do {
    const response = await fetch(
      `https://api.yoshi.ai/transactions?limit=100${cursor ? `&cursor=${cursor}` : ""}`,
      { headers: { Authorization: `Bearer ${process.env.YOSHI_API_KEY}` } },
    );
    const body = await response.json();

    allTransactions.push(...body.data);
    cursor = body.cursor;
  } while (cursor);
  ```
</CodeGroup>

<Tip>
  The SDKs handle pagination automatically with async iterators. Use manual pagination only if you're calling the API directly.
</Tip>

## Parameters

| Parameter | Type    | Default | Description                   |
| --------- | ------- | ------- | ----------------------------- |
| `limit`   | integer | 50      | Items per page (1–100)        |
| `cursor`  | string  | —       | Cursor from the previous page |

## Common pitfalls

**Don't parse the cursor.** It's an opaque string — its format may change without notice.

**Don't store cursors long-term.** Cursors are designed for sequential traversal within a single session. They may become invalid over time.

**Don't assume stable ordering across pages.** If new items are added while you're paginating, you may see them on a later page or miss them. For transactions, new items typically appear at the beginning of the list.

**Handle invalid cursors.** If a cursor is expired or malformed, the API returns a `400` error:

```json theme={null}
{
  "error": {
    "type": "https://api.yoshi.ai/errors/validation-error",
    "code": "VALIDATION_ERROR",
    "message": "Invalid or expired cursor",
    "param": "cursor"
  }
}
```

When this happens, restart pagination from the beginning (without a cursor).

## Which endpoints support pagination

| Endpoint                                  | Paginated                 |
| ----------------------------------------- | ------------------------- |
| `GET /transactions`                       | Yes                       |
| `GET /paper-trading/accounts/{id}/trades` | Yes                       |
| `GET /actions`                            | Yes                       |
| `GET /accounts`                           | No (returns all accounts) |
| `GET /recurring`                          | No (returns all streams)  |
| `GET /investments`                        | No (returns all holdings) |