> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Gcore list endpoints return paginated results using limit and offset, with count and results fields to iterate through all pages.

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.

> [!NOTE]
>
> 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](/developer-tools/rest-api/first-api-call).

## Response structure

Every list response includes `count` and `results`:

```json theme={null}
{
  "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 |

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

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

## Iterate all pages

**curl (shell loop)**

```bash theme={null}
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
```

**Python SDK**

```python theme={null}
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)}")
```

**Go SDK**

```go theme={null}
// 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))
```

**JavaScript**

```javascript theme={null}
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.