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

# Pagination

> Learn how to paginate through API responses

Most list endpoints in the Poelis Public API support pagination to help you efficiently retrieve large datasets.

## Pagination Parameters

All paginated endpoints accept these query parameters:

* **`limit`**: Number of items to return per page (1-200, default: 50)
* **`offset`**: Number of items to skip from the beginning (default: 0)

## Basic Usage

```bash theme={null}
# Get first page (50 items)
GET /v1/public/workspaces?limit=50&offset=0

# Get second page (next 50 items)
GET /v1/public/workspaces?limit=50&offset=50

# Get third page (next 50 items)
GET /v1/public/workspaces?limit=50&offset=100
```

## Response Format

Paginated responses include:

* **`items`**: Array of resources
* **`count`**: Number of items in the current response (not total count)

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Workspace 1"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Workspace 2"
    }
  ],
  "count": 2
}
```

## Pagination Strategies

### Offset-Based Pagination

Use `offset` and `limit` to page through results:

<CodeGroup>
  ```python Python theme={null}
  def fetch_all_workspaces(api_key, base_url):
      all_workspaces = []
      offset = 0
      limit = 50
      
      while True:
          response = requests.get(
              f"{base_url}/v1/public/workspaces",
              headers={"Authorization": f"Bearer {api_key}"},
              params={"limit": limit, "offset": offset}
          )
          response.raise_for_status()
          data = response.json()
          
          all_workspaces.extend(data["items"])
          
          # If we got fewer items than requested, we've reached the end
          if len(data["items"]) < limit:
              break
          
          offset += limit
      
      return all_workspaces
  ```

  ```javascript JavaScript theme={null}
  async function fetchAllWorkspaces(apiKey, baseUrl) {
    const allWorkspaces = [];
    let offset = 0;
    const limit = 50;
    
    while (true) {
      const response = await fetch(
        `${baseUrl}/v1/public/workspaces?limit=${limit}&offset=${offset}`,
        {
          headers: {
            'Authorization': `Bearer ${apiKey}`
          }
        }
      );
      
      const data = await response.json();
      allWorkspaces.push(...data.items);
      
      // If we got fewer items than requested, we've reached the end
      if (data.items.length < limit) {
        break;
      }
      
      offset += limit;
    }
    
    return allWorkspaces;
  }
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Choose Appropriate Limits" icon="slider">
    Use `limit=50` for most cases. Increase only if needed, up to 200
  </Card>

  <Card title="Handle Empty Results" icon="inbox">
    Check if `count === 0` to detect end of results
  </Card>
</CardGroup>