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

# Pagination

> Navigate large result sets with cursor-based pagination

List endpoints use **cursor-based pagination**. Results are returned in stable order, and you page through them using a cursor rather than an offset.

## Response structure

Every paginated response includes these fields:

```json theme={null}
{
  "object": "list",
  "url": "/api/v1/transactions",
  "has_more": true,
  "next_cursor": "txn_h8i9j0k1l2m3n4",
  "data": [...]
}
```

| Field         | Type    | Description                                                                                                                                                   |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`      | string  | Always `"list"`                                                                                                                                               |
| `url`         | string  | The canonical path of the collection, relative to the API host (e.g. `/api/v1/transactions`). Always present, never null, and does not include a query string |
| `has_more`    | boolean | `true` if more results exist beyond this page                                                                                                                 |
| `next_cursor` | string  | The cursor to pass as `starting_after` for the next page. Only present when `has_more` is `true`                                                              |
| `data`        | array   | The array of results                                                                                                                                          |

## Parameters

<ParamField query="limit" type="integer" default="100">
  Number of results per page. Minimum 1, maximum 500.
</ParamField>

<ParamField query="starting_after" type="string">
  A cursor for pagination. Pass the `next_cursor` value from the previous response to fetch the next page.
</ParamField>

## Paginated endpoints

* [`GET /transactions`](/docs/api-reference/transactions/list-transactions)
* [`GET /journal_entries`](/docs/api-reference/journal-entries/list-journal-entries)

[`GET /categories`](/docs/api-reference/categories/list-categories) is also a list endpoint, but it returns the full set in a single response and does not accept `limit` or `starting_after`.

## Example

Fetch the first page of transactions:

```bash theme={null}
curl "https://app.finta.com/api/v1/transactions?limit=100" \
  -H "Authorization: Bearer finta_your_key_here"
```

If `has_more` is `true`, use `next_cursor` to get the next page:

```bash theme={null}
curl "https://app.finta.com/api/v1/transactions?limit=100&starting_after=txn_h8i9j0k1l2m3n4" \
  -H "Authorization: Bearer finta_your_key_here"
```

### Fetching all pages

```bash theme={null}
cursor=""

while true; do
  if [ -z "$cursor" ]; then
    response=$(curl -s "https://app.finta.com/api/v1/transactions?limit=500" \
      -H "Authorization: Bearer finta_your_key_here")
  else
    response=$(curl -s "https://app.finta.com/api/v1/transactions?limit=500&starting_after=$cursor" \
      -H "Authorization: Bearer finta_your_key_here")
  fi

  # Process the data in this page
  echo "$response" | jq '.data'

  has_more=$(echo "$response" | jq -r '.has_more')
  if [ "$has_more" != "true" ]; then
    break
  fi

  cursor=$(echo "$response" | jq -r '.next_cursor')
done
```

<Tip>Use larger `limit` values (up to 500) to reduce the total number of requests, especially if you are syncing all data.</Tip>

<Tip>Writing a generic helper that paginates any list endpoint? Use the `url` field from the response instead of hardcoding the path: append `?starting_after={next_cursor}` to `response.url` and the same function works across `/transactions`, `/journal_entries`, and any future list endpoint.</Tip>