Skip to main content
Conventions

Pagination

All list endpoints in the Qoder Cloud Agents CN API use cursor-based pagination. Pass before_id or after_id to page through results. Cursors remain stable across data changes.

Request parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Items per page, range 1–100
before_idstringNo—Returns records before this ID (paging backward)
after_idstringNo—Returns records after this ID (paging forward)
before_id and after_id are mutually exclusive. Sending both returns 400 invalid_request_error. Some resources (Files, Skills, Vaults) use after/before as parameter names in their list endpoints, which are equivalent to after_id/before_id defined on this page — the server accepts both.

Response structure

All list endpoints return the same pagination envelope: 
{
  "data": [
    { "id": "agent_abc123", "name": "my-agent", "...": "..." },
    { "id": "agent_def456", "name": "another-agent", "...": "..." }
  ],
  "first_id": "agent_abc123",
  "last_id": "agent_def456",
  "has_more": true
}

Field descriptions

FieldTypeDescription
dataarrayResources on the current page
first_idstring | nullID of the first record on this page
last_idstring | nullID of the last record on this page
has_morebooleanWhether more records remain

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"

Page forward

Use last_id from the previous response as after_id: 
# 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"

Page backward

Use the current page's first_id as before_id: 
# Get the 10 records before agent_abc123
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&before_id=agent_abc123" \
  -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"
has_more=true
after_id=""
page=1

while [ "$has_more" = "true" ]; do
  url="$BASE_URL/agents?limit=50"
  if [ -n "$after_id" ]; then
    url="$url&after_id=$after_id"
  fi

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

  count=$(echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data']))")
  has_more=$(echo "$response" | python3 -c "import sys,json; print(str(json.load(sys.stdin)['has_more']).lower())")
  after_id=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin)['last_id'] or '')")

  echo "Page ${page}: ${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')}\")
"

  page=$((page + 1))
  sleep 0.1
done

echo "Done"

limit behavior

ValueBehavior
OmittedDefaults to 20
1Minimum, returns 1 record
100Maximum, returns 100 records
0 or negativeReturns 400
> 100**Silently capped at 100** (HTTP 200, no error).has_morereflects whether additional records remain
Passing limit > 100 does not return 400 — the API silently caps the page at 100 records. Code that sets limit=500 receives only the first 100 with no error. Use after_id to page through the rest. 
# Fetch a single 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": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Notes

  1. Cursor stability — cursors are based on resource IDs, so concurrent writes do not cause duplicates or skips.
  2. Sort order — records are returned in descending creation time by default (newest first).
  3. Deleted resources — using a deleted resource ID as a cursor may return 400.
  4. Concurrent paging — paging is safe to perform concurrently from multiple clients.
Guides
Tutorials
API Reference