# Pagination

Some of our API endpoints support paginated results to help manage and navigate through large sets of data efficiently. Pagination can be controlled using the `limit` and `offset` query parameters.

#### Query Parameters

* **limit**: Specifies the maximum number of records to return. This parameter is used to limit the size of the result set.
  * Type: Integer
  * Default: 10
  * Example: `limit=20`
* **offset**: Specifies the number of records to skip before starting to return results. This parameter is used to paginate through the data.
  * Type: Integer
  * Default: 0
  * Example: `offset=40`

### Request

To fetch paginated results, include the `limit` and `offset` query parameters in an API request where the query parameters are supported.

**Endpoint**

```bash
GET /v1/workspaces
```

**Example Request**

```http
GET /v1/workspaces?limit=20&offset=40
```

### Response

The response will include the requested records, along with metadata about the pagination.

**Response Format**

```json
{
  "data": [
    {
      "id": 1,
      "name": "Example Item 1",
      ...
    },
    {
      "id": 2,
      "name": "Example Item 2",
      ...
    },
    ...
  ],
  "meta": {
    "totalRecords": 1000,
    "limit": 20,
    "offset": 40
  }
}
```

#### Response Fields

* **data**: An array of the requested records.
* **meta**: An object containing metadata about the pagination.
  * **totalRecords**: The total number of records available.
  * **limit**: The number of records returned in the current request.
  * **offset**: The number of records skipped before starting to return results.

### Error Handling

**Invalid `limit` or `offset`**

If the provided `limit` or `offset` is invalid (e.g., non-integer or negative values), the API will return a `400 Bad Request` status code.

**Example Error Response**

```json
{
  "error": "Invalid query parameters",
  "message": "The 'limit' and 'offset' parameters must be non-negative integers."
}
```

### Usage Example

**Fetching the First Page of Results**

```http
GET /v1/workspaces?limit=10&offset=0
```

**Fetching the Second Page of Results**

```http
GET /v1/workspaces?limit=10&offset=10
```

**Fetching Results with a Custom Limit**

```http
GET /v1/workspaces?limit=50&offset=0
```

### Best Practices

1. **Set Reasonable Limits**: To optimize performance and reduce load, set a reasonable `limit` value.
2. **Handle Large Data Sets Efficiently**: Use the `offset` parameter to paginate through large data sets without overwhelming the server or client.
3. **Check Metadata**: Always check the `meta` object in the response to understand the context of the returned data and plan further pagination if needed.