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

# 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.

## 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"
```

Page 1 response (limit=5, count=35):

```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"}
  ]
}
```

Page 2 response (limit=5, offset=5):

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

## Iterate all pages

<Tabs>
  <Tab title="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
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from gcore import Gcore

    client = Gcore(api_key=os.environ["GCORE_API_KEY"])

    limit, offset = 100, 0
    all_instances = []

    while True:
        page = client.cloud.instances.list(
            project_id=int(os.environ["PROJECT_ID"]),
            region_id=int(os.environ["REGION_ID"]),
            limit=limit,
            offset=offset,
        )
        all_instances.extend(page.results)
        offset += limit
        if offset >= page.count:
            break

    print(f"Total: {len(all_instances)}")
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    var projectID int64 = 1234567
    var regionID  int64 = 148
    var limit int64 = 100
    var offset int64 = 0
    var all []cloud.Instance

    for {
        page, err := client.Cloud.Instances.List(context.TODO(), cloud.InstanceListParams{
            ProjectID: gcore.Int(projectID),
            RegionID:  gcore.Int(regionID),
            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))
    ```
  </Tab>

  <Tab title="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}`);
    ```
  </Tab>
</Tabs>

## 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.