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

# Pagination

> Navigate through large result sets

## Overview

All list endpoints support pagination using `limit` and `offset` parameters.

## Parameters

| Parameter | Type    | Default | Max | Description                |
| --------- | ------- | ------- | --- | -------------------------- |
| `limit`   | integer | 50      | 100 | Number of results per page |
| `offset`  | integer | 0       | -   | Number of results to skip  |

## Example

```bash theme={null}
# Get first page (results 0-49)
curl "https://api.debtstack.ai/v1/bonds?limit=50&offset=0" \
  -H "X-API-Key: ds_xxxxx"

# Get second page (results 50-99)
curl "https://api.debtstack.ai/v1/bonds?limit=50&offset=50" \
  -H "X-API-Key: ds_xxxxx"
```

## Response Metadata

Every paginated response includes metadata:

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 2849,
    "limit": 50,
    "offset": 0
  }
}
```

| Field    | Description                      |
| -------- | -------------------------------- |
| `total`  | Total number of matching results |
| `limit`  | Current page size                |
| `offset` | Current offset                   |

## Iterating Through All Results

### Python Example

```python theme={null}
import requests

API_KEY = "ds_xxxxx"
BASE_URL = "https://api.debtstack.ai/v1"

def get_all_bonds(params=None):
    """Fetch all bonds with pagination."""
    if params is None:
        params = {}

    params["limit"] = 100  # Max page size
    params["offset"] = 0

    all_bonds = []

    while True:
        response = requests.get(
            f"{BASE_URL}/bonds",
            params=params,
            headers={"X-API-Key": API_KEY}
        )
        data = response.json()

        all_bonds.extend(data["data"])

        # Check if we've fetched all results
        if len(all_bonds) >= data["meta"]["total"]:
            break

        params["offset"] += params["limit"]

    return all_bonds

# Get all high-yield bonds
bonds = get_all_bonds({"min_ytm": 8.0, "has_pricing": True})
print(f"Found {len(bonds)} bonds")
```

## Sorting

Combine pagination with sorting for consistent results:

```bash theme={null}
# Sort by maturity date, ascending
curl "https://api.debtstack.ai/v1/bonds?sort=maturity_date&limit=50" \
  -H "X-API-Key: ds_xxxxx"

# Sort by YTM, descending (prefix with -)
curl "https://api.debtstack.ai/v1/bonds?sort=-pricing.ytm&limit=50" \
  -H "X-API-Key: ds_xxxxx"
```

<Warning>
  Always include a `sort` parameter when paginating to ensure consistent ordering across pages.
</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use consistent sorting" icon="arrow-up-arrow-down">
    Without sorting, result order may vary between requests
  </Card>

  <Card title="Cache totals" icon="database">
    Store the `total` from the first request to track progress
  </Card>

  <Card title="Handle empty pages" icon="circle-check">
    An empty `data` array indicates no more results
  </Card>

  <Card title="Respect rate limits" icon="gauge">
    Add delays between pagination requests if needed
  </Card>
</CardGroup>

## CSV Export

For bulk data export, use the `format=csv` parameter instead of manual pagination:

```bash theme={null}
curl "https://api.debtstack.ai/v1/bonds?format=csv&limit=1000" \
  -H "X-API-Key: ds_xxxxx" \
  -o bonds.csv
```

This returns a CSV file with all matching results (up to 1000 rows).