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

# Pagination

> How to paginate through list endpoints using limit and offset parameters.

# Pagination

List endpoints in the Tedro API use **offset-based pagination**. You control how many items to retrieve and where to start in the result set.

## Query Parameters

| Parameter | Type    | Default | Max   | Description                                |
| --------- | ------- | ------- | ----- | ------------------------------------------ |
| `limit`   | integer | `20`    | `100` | Number of items to return per page         |
| `offset`  | integer | `0`     | --    | Number of items to skip from the beginning |

## Response Format

Paginated endpoints return an object with an `items` array and a `total` count:

```json theme={null}
{
  "items": [
    { "id": "550e8400-...", "name": "Customer Support Bot" },
    { "id": "6ba7b810-...", "name": "Lead Qualifier" }
  ],
  "total": 47
}
```

| Field   | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| `items` | array   | The page of results                             |
| `total` | integer | Total number of matching items across all pages |

Use `total` to calculate the number of pages: `Math.ceil(total / limit)`.

## Paginated Endpoints

The following list endpoints support `limit` and `offset`:

| Endpoint                              | Description               |
| ------------------------------------- | ------------------------- |
| `GET /api/contacts`                   | List contacts             |
| `GET /api/conversations`              | List conversations        |
| `GET /api/runs`                       | List workflow runs        |
| `GET /api/broadcasts`                 | List broadcasts           |
| `GET /api/broadcasts/{id}/recipients` | List broadcast recipients |
| `GET /api/groups/{id}/contacts`       | List group contacts       |

<Note>
  Some list endpoints (like `GET /api/workflows`, `GET /api/tags`, `GET /api/tools`) return all items without pagination. These endpoints typically have smaller result sets.
</Note>

## Examples

### First Page

```bash cURL theme={null}
curl "https://api.tedro.io/api/contacts?limit=20&offset=0" \
  -b cookies.txt \
  -H "x-workspace-id: your-workspace-uuid"
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api.tedro.io/api/contacts?limit=20&offset=0',
  {
    headers: {
      'Cookie': `better-auth.session_token=${sessionToken}`,
      'x-workspace-id': 'your-workspace-uuid',
    },
  }
);

const { items, total } = await response.json();
console.log(`Showing ${items.length} of ${total} contacts`);
```

### Fetching All Pages

```javascript Node.js theme={null}
async function fetchAllContacts(sessionToken, workspaceId) {
  const allContacts = [];
  let offset = 0;
  const limit = 100; // Max per page

  while (true) {
    const response = await fetch(
      `https://api.tedro.io/api/contacts?limit=${limit}&offset=${offset}`,
      {
        headers: {
          'Cookie': `better-auth.session_token=${sessionToken}`,
          'x-workspace-id': workspaceId,
        },
      }
    );

    const { items, total } = await response.json();
    allContacts.push(...items);

    if (allContacts.length >= total) break;
    offset += limit;
  }

  return allContacts;
}
```