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

# Pagination

> Learn how to handle paginated responses in the Vepler API

## Overview

The Vepler API uses **offset-based pagination** for list and query endpoints. Requests accept `limit` and `offset` parameters, and responses indicate whether more data is available.

## Request Parameters

| Parameter | Type    | Default | Description                                    |
| --------- | ------- | ------- | ---------------------------------------------- |
| `limit`   | integer | 25      | Number of items to return (varies by endpoint) |
| `offset`  | integer | 0       | Number of items to skip                        |

## Response Format

Paginated responses include metadata alongside the results:

```json theme={null}
{
  "success": true,
  "result": [ ... ],
  "totalSize": 1250,
  "size": 25,
  "hasMore": true,
  "nextOffset": 25
}
```

| Field                 | Description                                       |
| --------------------- | ------------------------------------------------- |
| `totalSize` / `total` | Total number of matching records                  |
| `size`                | Number of records returned in this response       |
| `hasMore`             | Whether additional records exist beyond this page |
| `nextOffset`          | The offset value to use for the next page         |

## Basic Usage

### First Page

```typescript theme={null}
import { SDK } from '@vepler/sdk';

const vepler = new SDK({ apiKey: process.env.VEPLER_API_KEY });

const response = await vepler.property.getV1PropertyLocationIds({
  locationIds: 'loc_123',
  limit: '50',
  offset: '0'
});

if (response.propertyListResponse) {
  console.log(response.propertyListResponse.result);
  console.log('Has more:', response.propertyListResponse.hasMore);
}
```

### Subsequent Pages

```typescript theme={null}
const page2 = await vepler.property.getV1PropertyLocationIds({
  locationIds: 'loc_123',
  limit: '50',
  offset: '50'
});
```

## Complete Iteration Example

```typescript theme={null}
async function getAllProperties(locationId: string) {
  const vepler = new SDK({ apiKey: process.env.VEPLER_API_KEY });
  const allProperties: unknown[] = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await vepler.property.getV1PropertyLocationIds({
      locationIds: locationId,
      limit: String(limit),
      offset: String(offset)
    });

    if (!response.propertyListResponse) break;

    allProperties.push(...response.propertyListResponse.result);

    if (!response.propertyListResponse.hasMore) break;

    offset += limit;

    // Small delay between pages
    await new Promise(resolve => setTimeout(resolve, 100));
  }

  return allProperties;
}
```

## Query Endpoint Pagination

For POST query endpoints, pagination parameters are in the request body:

```typescript theme={null}
const response = await vepler.property.postV1PropertyQuery({
  area: [{ type: 'postcode', value: 'SW1A' }],
  query: { beds: [2, 3] },
  limit: 50,
  offset: 0
});

// Next page
const page2 = await vepler.property.postV1PropertyQuery({
  area: [{ type: 'postcode', value: 'SW1A' }],
  query: { beds: [2, 3] },
  limit: 50,
  offset: 50
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Appropriate Page Sizes" icon="gauge">
    * Use larger page sizes (50-100) for bulk operations
    * Use smaller page sizes (10-25) for user-facing displays
    * Check each endpoint's documentation for maximum allowed values
  </Accordion>

  <Accordion title="Add Delays Between Pages" icon="clock">
    When iterating through many pages, add a small delay to avoid hitting usage limits:

    ```typescript theme={null}
    await new Promise(resolve => setTimeout(resolve, 100));
    ```
  </Accordion>

  <Accordion title="Use Field Selection" icon="filter">
    Reduce response size by requesting only the fields you need:

    ```typescript theme={null}
    const response = await vepler.property.getV1PropertyLocationIds({
      locationIds: 'loc_123',
      limit: '100',
      offset: '0',
      attributes: 'address,pricing'
    });
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Error Handling" icon="circle-exclamation" href="/concepts/errors">
    Handle errors effectively
  </Card>

  <Card title="Usage & Limits" icon="gauge" href="/guides/rate-limiting">
    Understand usage metering
  </Card>
</CardGroup>