List endpoints in the Qoder Cloud Agents API use cursor-based pagination. Use the next_page value from a response as the page query parameter on the next request. Cursors remain stable even as data changes.
Request parameters
| Parameter | Type | Required | Default | Description |
|---|
limit | integer | No | 20 | Items per page, range 1–100 |
page | string | No | — | Opaque cursor returned by the previous response's next_page |
before_id | string | No | — | Compatibility cursor: returns records before this ID |
after_id | string | No | — | Compatibility cursor: returns records after this ID |
page, before_id, and after_id are mutually exclusive. Sending more than one cursor returns 400 invalid_request_error.
Response structure
All list endpoints return the same pagination envelope:
{
"data": [
{ "id": "agent_abc123", "name": "my-agent", "...": "..." },
{ "id": "agent_def456", "name": "another-agent", "...": "..." }
],
"next_page": "agent_def456",
"first_id": "agent_abc123",
"last_id": "agent_def456",
"has_more": true
}
Field descriptions
| Field | Type | Description |
|---|
data | array | Resources on the current page |
next_page | string | null | Opaque cursor for the next page. Pass it as the page query parameter |
first_id | string | null | ID of the first record on this page |
last_id | string | null | ID of the last record on this page |
has_more | boolean | Whether more records remain |
Basic usage
Fetch the first page
# Get the first 10 Agents
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
Fetch the next page
Use next_page from the previous response as page:
# Get the next 10 Agents
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&page=agent_def456" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
Compatibility cursors
Some endpoints also accept before_id and after_id for ID-based cursor compatibility:
# Get the 10 records after agent_def456
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
Full traversal example
The script below iterates through every Agent:
#!/bin/bash
# Iterate over all Agents and print names
BASE_URL="https://api.qoder.com/api/v1/cloud"
next_page=""
page_num=1
while true; do
url="$BASE_URL/agents?limit=50"
if [ -n "$next_page" ]; then
url="$url&page=$next_page"
fi
response=$(curl -s "$url" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN")
count=$(echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data']))")
next_page=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('next_page') or '')")
echo "Page ${page_num}: ${count} records"
echo "$response" | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for item in data:
print(f\" - {item['id']}: {item.get('name', 'unnamed')}\")
"
if [ -z "$next_page" ]; then
break
fi
page_num=$((page_num + 1))
sleep 0.1
done
echo "Done"
limit behavior
| Value | Behavior |
|---|
| Omitted | Defaults to 20 |
| 1 | Minimum, returns 1 record |
| 100 | Maximum, returns 100 records |
| 0 or negative | Returns 400 invalid_request_error with message Field 'limit' must be a positive integer. |
| > 100 | Returns 400 invalid_request_error with message limit exceeds maximum of 100 |
Passing limit > 100 returns 400. Use limit=100 and page to page through larger result sets.
# Fetch a single record to check whether data exists
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=1" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
Empty results
When there is no data or the end of the list has been reached:
{
"data": [],
"next_page": null,
"first_id": null,
"last_id": null,
"has_more": false
}
Notes
- Cursor stability —
page cursors are opaque and should be passed back exactly as returned.
- Sort order — records are returned in descending creation time by default (newest first).
- Compatibility cursors —
before_id and after_id are retained for ID-based cursor compatibility.
- Concurrent paging — paging is safe to perform concurrently from multiple clients.
Next steps
