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

# Pagination

## Response envelope

Every list endpoint wraps results in a standard paginated envelope:

```json
{
  "data": [
    { "id": "load_550e8400-...", "load_number": "LD-001" },
    { "id": "load_662f9b11-...", "load_number": "LD-002" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 150,
    "total_pages": 8
  }
}
```

## Query parameters

Control pagination with two query parameters:

| Parameter   | Type    | Default | Description                                |
| ----------- | ------- | ------- | ------------------------------------------ |
| `page`      | integer | `1`     | The page number to retrieve (1-indexed).   |
| `page_size` | integer | `20`    | Number of results per page. Maximum `100`. |

## Example request

```bash
curl "https://tryenvoy.ai/api/v1/loads?page=2&page_size=50" \
  -H "X-API-Key: <your-api-key>"
```

Response:

```json
{
  "data": [
    { "id": "load_a3c7e912-...", "load_number": "LD-051" },
    { "id": "load_b4d8f023-...", "load_number": "LD-052" }
  ],
  "pagination": {
    "page": 2,
    "page_size": 50,
    "total_count": 150,
    "total_pages": 3
  }
}
```

## Pagination fields

| Field         | Type    | Description                               |
| ------------- | ------- | ----------------------------------------- |
| `page`        | integer | Current page number.                      |
| `page_size`   | integer | Number of results returned per page.      |
| `total_count` | integer | Total number of results across all pages. |
| `total_pages` | integer | Total number of pages.                    |

## Iterating through pages

Use `total_pages` to determine when to stop:

```python
import requests

url = "https://tryenvoy.ai/api/v1/loads"
headers = {"X-API-Key": "<your-api-key>"}
page = 1

while True:
    response = requests.get(url, headers=headers, params={"page": page, "page_size": 100})
    data = response.json()

    for load in data["data"]:
        process(load)

    if page >= data["pagination"]["total_pages"]:
        break
    page += 1
```

```typescript
const headers = { "X-API-Key": "<your-api-key>" };
let page = 1;

while (true) {
  const res = await fetch(
    `https://tryenvoy.ai/api/v1/loads?page=${page}&page_size=100`,
    { headers }
  );
  const { data, pagination } = await res.json();

  for (const load of data) {
    process(load);
  }

  if (page >= pagination.total_pages) break;
  page++;
}
```

## Sorting

Some list endpoints support sorting via `order_by` and `order_desc` parameters:

| Parameter    | Type    | Default      | Description               |
| ------------ | ------- | ------------ | ------------------------- |
| `order_by`   | string  | `created_at` | Field to sort by.         |
| `order_desc` | boolean | `true`       | Sort in descending order. |

```bash
curl "https://tryenvoy.ai/api/v1/loads?order_by=created_at&order_desc=false&page_size=50" \
  -H "X-API-Key: <your-api-key>"
```

## Search

List endpoints that support search accept a `search` query parameter for full-text filtering:

```bash
curl "https://tryenvoy.ai/api/v1/carriers?search=midwest&page_size=20" \
  -H "X-API-Key: <your-api-key>"
```

The search parameter filters across relevant fields for each resource (e.g., name, MC number, and DOT number for carriers).