When API endpoints return large collections of data, results are paginated to keep responses fast and manageable. This guide explains how pagination and filtering work in the Data Mammoth API.
Pagination
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | The page number to retrieve |
per_page | integer | 25 | Number of results per page (max: 100) |
Example Request
curl -X GET "https://api.datamammoth.com/v1/servers?page=2&per_page=10" \
-H "Authorization: Bearer dm_key_abc123def456"Pagination Metadata
Every paginated response includes a meta object with pagination details:
{
"data": [...],
"meta": {
"total": 47,
"page": 2,
"per_page": 10,
"total_pages": 5,
"has_next": true,
"has_prev": true
}
}| Field | Description |
|---|---|
total | Total number of records matching the query |
page | Current page number |
per_page | Number of results per page |
total_pages | Total number of pages |
has_next | Whether a next page exists |
has_prev | Whether a previous page exists |
Iterating Through All Pages
To retrieve all records, iterate through pages until has_next is false:
import requestsall_servers = [] page = 1 headers = {"Authorization": "Bearer dm_key_abc123def456"}
while True: response = requests.get( f"https://api.datamammoth.com/v1/servers?page={page}&per_page=50", headers=headers ) data = response.json() all_servers.extend(data["data"])
if not data["meta"]["has_next"]: break page += 1
print(f"Total servers: {len(all_servers)}")
Filtering
Most list endpoints support query parameters for filtering results server-side, reducing the amount of data transferred and processed.
Common Filters
Servers
GET /v1/servers?status=running®ion=us-east&tag=production| Parameter | Description | Example Values |
|---|---|---|
status | Server status | running, stopped, provisioning |
region | Data center region | us-east, eu-west |
tag | Server tag/label | production, staging |
name | Search by server name | web- (partial match) |
Invoices
GET /v1/billing/invoices?status=unpaid&date_from=2026-01-01&date_to=2026-03-31| Parameter | Description | Example Values |
|---|---|---|
status | Invoice status | paid, unpaid, overdue, cancelled |
date_from | Start date (ISO 8601) | 2026-01-01 |
date_to | End date (ISO 8601) | 2026-03-31 |
Support Tickets
GET /v1/support/tickets?status=open&priority=high&department=technical| Parameter | Description | Example Values |
|---|---|---|
status | Ticket status | open, in_progress, resolved, closed |
priority | Ticket priority | low, medium, high, critical |
department | Support department | technical, billing, sales |
Combining Filters
Apply multiple filters simultaneously. All filters are combined with AND logic:
# Servers that are running AND in us-east AND tagged as production
GET /v1/servers?status=running®ion=us-east&tag=productionSorting
Some endpoints support sorting with the sort parameter:
GET /v1/servers?sort=created_at&order=desc| Parameter | Description |
|---|---|
sort | Field to sort by (e.g., created_at, name, status) |
order | Sort direction: asc (ascending) or desc (descending) |
Best Practices
1. Filter Server-Side
Always use query parameters to filter data rather than fetching everything and filtering locally:
# Good — filter on the server
GET /v1/servers?status=runningAvoid — fetching all and filtering locally
GET /v1/servers # then filter in code2. Request Only What You Need
Use smaller page sizes when you only need a few records:
# If you only need the first 5 results
GET /v1/servers?per_page=5&page=13. Use Consistent Page Sizes
Keep per_page consistent across requests to avoid confusion with offsets.
4. Handle Empty Results
Your code should handle the case where no results match the filters:
{
"data": [],
"meta": {
"total": 0,
"page": 1,
"per_page": 25,
"total_pages": 0,
"has_next": false,
"has_prev": false
}
}5. Cache Where Appropriate
Cache paginated results for data that changes infrequently to reduce API calls.
What to Do Next
- API Rate Limits & Best Practices — Optimize your API usage.
- API Error Codes & Handling — Handle pagination errors.
- Server Management API — Filter and paginate servers.
- Billing API — Filter and paginate invoices.