Pagination

All list endpoints in the Gcore 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.gcore.com/cloud/v1/regions?limit=5&offset=0" \
  -H "Authorization: APIKey $GCORE_API_KEY"

# Page 2: items 6–10
curl "https://api.gcore.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

curl (shell loop)
Python SDK
Go SDK
JavaScript

LIMIT=100
OFFSET=0

while true; do
  RESPONSE=$(curl -s \
    "https://api.gcore.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 Gcore

client = Gcore()  # 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.gcore.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.

Account settings

Developer Tools

CDN

FastEdge

Edge Cloud

AI

Gclaw

Managed DNS

Public DNS

Hosting

Colocation

Object Storage

Video Streaming

DDoS protection

Edge Proxy

WAAP

Response structure

Parameters

Iterate all pages

​Response structure

​Parameters

​Iterate all pages

​Pagination in practice

Response structure

Parameters

Iterate all pages

Pagination in practice