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
# 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"
{
"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
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:
# 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"
Always include a sort parameter when paginating to ensure consistent ordering across pages.
Best Practices
Use consistent sorting
Without sorting, result order may vary between requests
Cache totals
Store the total from the first request to track progress
Handle empty pages
An empty data array indicates no more results
Respect rate limits
Add delays between pagination requests if needed
CSV Export
For bulk data export, use the format=csv parameter instead of manual pagination:
curl "https://api.debtstack.ai/v1/bonds?format=csv&limit=1000" \
-H "X-API-Key: ds_xxxxx" \
-o bonds.csv
