Pagination

Response envelope

Every list endpoint wraps results in a standard paginated envelope:

1
{
2
  "data": [
3
    { "id": "load_550e8400-...", "load_number": "LD-001" },
4
    { "id": "load_662f9b11-...", "load_number": "LD-002" }
5
  ],
6
  "pagination": {
7
    "page": 1,
8
    "page_size": 20,
9
    "total_count": 150,
10
    "total_pages": 8
11
  }
12
}

Query parameters

Control pagination with two query parameters:

Example request

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

Response:

1
{
2
  "data": [
3
    { "id": "load_a3c7e912-...", "load_number": "LD-051" },
4
    { "id": "load_b4d8f023-...", "load_number": "LD-052" }
5
  ],
6
  "pagination": {
7
    "page": 2,
8
    "page_size": 50,
9
    "total_count": 150,
10
    "total_pages": 3
11
  }
12
}

Pagination fields

Iterating through pages

Use total_pages to determine when to stop:

1
import requests
2
3
url = "https://tryenvoy.ai/api/v1/loads"
4
headers = {"X-API-Key": "<your-api-key>"}
5
page = 1
6
7
while True:
8
    response = requests.get(url, headers=headers, params={"page": page, "page_size": 100})
9
    data = response.json()
10
11
    for load in data["data"]:
12
        process(load)
13
14
    if page >= data["pagination"]["total_pages"]:
15
        break
16
    page += 1

1
const headers = { "X-API-Key": "<your-api-key>" };
2
let page = 1;
3
4
while (true) {
5
  const res = await fetch(
6
    `https://tryenvoy.ai/api/v1/loads?page=${page}&page_size=100`,
7
    { headers }
8
  );
9
  const { data, pagination } = await res.json();
10
11
  for (const load of data) {
12
    process(load);
13
  }
14
15
  if (page >= pagination.total_pages) break;
16
  page++;
17
}

Sorting

Some list endpoints support sorting via order_by and order_desc parameters:

$
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:

$
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).