Pagination

All list endpoints in the CDB API return paginated results using limit and offset query parameters. Without explicit pagination, a single response returns up to 1000 items — the default for most endpoints. For accounts with many resources, iterating pages is required to retrieve all results.

ℹ️

The code examples require GCORE_API_KEY, GCORE_CLOUD_PROJECT_ID, and GCORE_CLOUD_REGION_ID to be set in the environment — set them up in First API call.

Response structure

Every list response includes count and results:

{
  "count": 35,        // total number of matching items across all pages
  "results": [...]    // items on this page (up to `limit`)
}

count is the total across all pages, not the current page alone — use it to calculate how many pages remain.

Parameters

Both parameters are optional and can be combined on any list endpoint:

Parameter	Default	Maximum	Description
limit	1000	1000	Items per page
offset	0	—	Skip the first N items

# Page 1: items 1–5
curl "https://api.cdb-staging.cdn.orange.com/cloud/v1/regions?limit=5&offset=0" \
  -H "Authorization: APIKey $GCORE_API_KEY"

# Page 2: items 6–10
curl "https://api.cdb-staging.cdn.orange.com/cloud/v1/regions?limit=5&offset=5" \
  -H "Authorization: APIKey $GCORE_API_KEY"

First page response:

{
  "count": 35,
  "results": [
    {"id": 196, "display_name": "London-2"},
    {"id": 184, "display_name": "Chester"},
    {"id": 180, "display_name": "Frankfurt-2"},
    {"id": 176, "display_name": "Sines-3"},
    {"id": 172, "display_name": "San Jose"}
  ]
}

Second page response:

{
  "count": 35,
  "results": [
    {"id": 164, "display_name": "Sines-2"},
    {"id": 160, "display_name": "Paris-3"},
    ...
  ]
}

Iterate all pages

LIMIT=100
OFFSET=0

while true; do
  RESPONSE=$(curl -s \
    "https://api.cdb-staging.cdn.orange.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID?limit=$LIMIT&offset=$OFFSET" \
    -H "Authorization: APIKey $GCORE_API_KEY")

  COUNT=$(echo "$RESPONSE" | grep -o '"count":[0-9]*' | grep -o '[0-9]*')
  echo "Page offset=$OFFSET, total=$COUNT"

  # Process results here...

  OFFSET=$((OFFSET + LIMIT))
  if [ "$OFFSET" -ge "$COUNT" ]; then break; fi
done

from gcore import CDB

client = CDB()  # reads GCORE_API_KEY, GCORE_CLOUD_PROJECT_ID, GCORE_CLOUD_REGION_ID

limit, offset = 100, 0
all_instances = []

while True:
    page = client.cloud.instances.list(
        limit=limit,
        offset=offset,
    )
    all_instances.extend(page.results)
    offset += limit
    if offset >= page.count:
        break

print(f"Total: {len(all_instances)}")

// Uses GCORE_CLOUD_PROJECT_ID and GCORE_CLOUD_REGION_ID read by gcore.NewClient()
ctx := context.Background()
var limit int64 = 100
var offset int64 = 0
var all []cloud.Instance

for {
    page, err := client.Cloud.Instances.List(ctx, cloud.InstanceListParams{
        Limit:  gcore.Int(limit),
        Offset: gcore.Int(offset),
    })
    if err != nil { panic(err) }
    all = append(all, page.Results...)
    offset += limit
    if offset >= int64(page.Count) { break }
}
fmt.Printf("Total: %d\n", len(all))

const BASE = "https://api.cdb-staging.cdn.orange.com";
const headers = { Authorization: `APIKey ${process.env.GCORE_API_KEY}` };
const PROJECT_ID = process.env.PROJECT_ID;
const REGION_ID  = process.env.REGION_ID;

let offset = 0, limit = 100, all = [];
while (true) {
  const res = await fetch(
    `${BASE}/cloud/v1/instances/${PROJECT_ID}/${REGION_ID}?limit=${limit}&offset=${offset}`,
    { headers }
  );
  const { count, results } = await res.json();
  all = all.concat(results);
  offset += limit;
  if (offset >= count) break;
}
console.log(`Total: ${all.length}`);

Pagination in practice

Most API responses return all results in a single page when the total is under 1000. Pagination becomes important when:

• An account has hundreds or thousands of instances, volumes, or other resources
• Filtering is applied server-side and the filtered set still exceeds the default limit
• Building inventory tooling or cost reporting across all resources

For most individual workflow operations (create VM, attach volume, configure network), pagination is not needed — those operations work on a single resource at a time.