> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentphone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server.

# Pagination

> How to paginate through list endpoints in the AgentPhone API.

Most list endpoints support pagination to efficiently retrieve large datasets. The API uses two pagination strategies depending on the endpoint.

## Offset-Based Pagination

Used by endpoints like `GET /v1/numbers`, `GET /v1/conversations`, and `GET /v1/agents`.

| Parameter | Description                                        |
| --------- | -------------------------------------------------- |
| `limit`   | Number of results per page (default: 20, max: 100) |
| `offset`  | Number of results to skip (default: 0)             |

```typescript
const BASE_URL = "https://api.agentphone.ai";

// Get first page (20 results)
const page1 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=0`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

// Get second page
const page2 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=20`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
```

```python
import requests

BASE_URL = "https://api.agentphone.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get first page (20 results)
page1 = requests.get(f"{BASE_URL}/v1/numbers?limit=20&offset=0", headers=headers).json()

# Get second page
page2 = requests.get(f"{BASE_URL}/v1/numbers?limit=20&offset=20", headers=headers).json()
```

### Response format

```json
{
  "data": [],
  "hasMore": true,
  "total": 42
}
```

* `hasMore` — `true` if more results are available beyond the current page.
* `total` — Total number of items (may not be present on every endpoint).

## Cursor-Based Pagination

Used by message endpoints like `GET /v1/numbers/:id/messages`. Cursors use timestamps for efficient pagination of time-ordered data.

| Parameter | Description                                        |
| --------- | -------------------------------------------------- |
| `limit`   | Number of results per page (default: 50, max: 200) |
| `before`  | ISO timestamp — return messages before this time   |
| `after`   | ISO timestamp — return messages after this time    |

```typescript
const BASE_URL = "https://api.agentphone.ai";

// Get most recent 50 messages
const recent = await fetch(
  `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const messages = await recent.json();
const oldestMessage = messages.data[messages.data.length - 1];

// Get next 50 messages (older than the oldest we have)
if (messages.hasMore) {
  const older = await fetch(
    `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50&before=${oldestMessage.receivedAt}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}
```

```python
import requests

BASE_URL = "https://api.agentphone.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Get most recent 50 messages
recent = requests.get(
    f"{BASE_URL}/v1/numbers/{number_id}/messages?limit=50",
    headers=headers,
).json()

oldest_message = recent["data"][-1]

# Get next 50 messages (older than the oldest we have)
if recent["hasMore"]:
    older = requests.get(
        f"{BASE_URL}/v1/numbers/{number_id}/messages?limit=50&before={oldest_message['receivedAt']}",
        headers=headers,
    ).json()
```

> **Warning**
>
> Always check `hasMore` before fetching the next page. Use cursor-based pagination (`before`/`after`) for time-ordered data — it is more efficient than offset-based pagination for large datasets.