Qoder CN Series:Pagination

Qoder Cloud Agents API list endpoints use cursor-based pagination. Pass the next_page value from the previous response as the page parameter in the next request. Cursors remain stable even when data changes.

Request parameters

Parameter	Type	Required	Default	Description
limit	integer	No	20	Number of items per page, range 1-100
page	string	No	—	Opaque cursor returned by next_page in the previous response
before_id	string	No	—	Compatibility cursor: returns records before this ID
after_id	string	No	—	Compatibility cursor: returns records after this ID

Response structure

All list endpoints return a unified 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 as the page parameter in the next request
first_id	string | null	ID of the first record on the current page
last_id	string | null	ID of the last record on the current page
has_more	boolean	Whether more data is available

Basic usage

Fetch the first page

# Get the first 10 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

Fetch the next page

Use the next_page value from the previous response as page:

# Get the next 10 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&page=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

Compatibility cursors

Some endpoints also accept before_id and after_id as ID-based compatibility cursors:

# Get the 10 records after agent_def456
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

Full traversal example

The following script iterates through all Agents:

#!/bin/bash
# Iterate over all Agents and print names
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
next_page=""
page_num=1

while true; do
  # Build URL
  url="$BASE_URL/agents?limit=50"
  if [ -n "$next_page" ]; then
    url="$url&page=$next_page"
  fi

  # Send request
  response=$(curl -s "$url" \
    -H "Authorization: Bearer $QODER_PAT")

  # Parse response
  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"

  if [ -z "$next_page" ]; then
    break
  fi

  page_num=$((page_num + 1))

  # Delay between requests to avoid throttling
  sleep 0.1
done

echo "Done"

limit parameter behavior

Value	Behavior
Omitted	Defaults to 20 records
1	Minimum value, returns 1 record
100	Maximum value, 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

# Fetch only 1 record to check whether data exists
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

Empty results

When no data is available or the end of the list is reached:

{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Notes

1. Cursor stability — page is an opaque cursor and should be passed back exactly as received in the response

2. Sort order — records are returned in descending creation time by default (newest first)

3. Compatibility cursors — before_id and after_id are retained as ID-based compatibility cursors

4. Concurrency safety — pagination is safe to perform concurrently from multiple clients