Pagination

How pagination works

List endpoints use offset-based pagination.

• Parameters

  • limit: number of items to return (/data/bookings: default 100, max 1000; /data/pricing: default 1000, max 5000)

  • offset: number of items to skip (default: 0)

• Response fields

  • total: total items available after filters

  • limit: the limit you requested/applied

  • offset: the offset you requested/applied

  • has_more: whether another page exists

  • next_offset: the next offset, or null on the final page

  • items: the current page of results

• Paging logic

  • Request next_offset while has_more is true

  • You’ve reached the end when has_more is false

  • GET /data/bookings is ordered by reservation_start (asc), then booking_date (asc)

Example request

JavaScript

// Server-side (Node 18+). Don’t expose API keys in the browser.
(async () => {
  const BASE_URL = 'https://api.okup.ai';
  const API_KEY = process.env.OKUPAI_API_KEY;

  const res = await fetch(`${BASE_URL}/data/bookings?from=2025-01-01&to=2025-01-31&limit=200&offset=0`, {
    headers: { 'X-API-Key': API_KEY },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  const data = await res.json();
  console.log(data);
})();

Python

import os, requests

BASE_URL = "https://api.okup.ai"
API_KEY = os.environ["OKUPAI_API_KEY"]

r = requests.get(
    f"{BASE_URL}/data/bookings",
    headers={"X-API-Key": API_KEY},
    params={"from": "2025-01-01", "to": "2025-01-31", "limit": 200, "offset": 0},
    timeout=30,
)
r.raise_for_status()
print(r.json())

cURL

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/bookings?from=2025-01-01&to=2025-01-31&limit=200&offset=0"

Iterate pages

JavaScript

const BASE_URL = 'https://api.okup.ai';
const API_KEY = process.env.OKUPAI_API_KEY;

async function fetchAllBookings({ from, to, pageSize = 500 }) {
  let offset = 0;
  const all = [];

  while (true) {
    const res = await fetch(`${BASE_URL}/data/bookings?from=${from}&to=${to}&limit=${pageSize}&offset=${offset}`, {
      headers: { 'X-API-Key': API_KEY },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

    const data = await res.json();
    all.push(...data.items);

    if (!data.has_more) break;
    offset = data.next_offset;
  }
  return all;
}

// Usage:
fetchAllBookings({ from: '2025-01-01', to: '2025-01-31', pageSize: 500 }).then(console.log);

Python

import os, requests

BASE_URL = "https://api.okup.ai"
API_KEY = os.environ["OKUPAI_API_KEY"]

def fetch_all_bookings(from_date: str, to_date: str, page_size: int = 500):
    offset = 0
    all_items = []

    while True:
        r = requests.get(
            f"{BASE_URL}/data/bookings",
            headers={"X-API-Key": API_KEY},
            params={"from": from_date, "to": to_date, "limit": page_size, "offset": offset},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        all_items.extend(data.get("items", []))

        if not data.get("has_more"):
            break
        offset = data["next_offset"]

    return all_items

# Usage:
print(fetch_all_bookings("2025-01-01", "2025-01-31", 500))

cURL

# Example: paginate with a simple offset loop (adjust page size and range as needed)
PAGE_SIZE=500
for OFFSET in $(seq 0 $PAGE_SIZE 5000); do
  echo "Fetching offset=$OFFSET"
  curl -sS -H "X-API-Key: $OKUPAI_API_KEY" \
    "https://api.okup.ai/data/bookings?from=2025-01-01&to=2025-01-31&limit=$PAGE_SIZE&offset=$OFFSET"
  echo # newline between pages
done

Incremental synchronization policy

Repeatedly downloading all historical data is slow, creates avoidable load, and increases the chance that a long sync fails partway through. Delta synchronization transfers only rows that changed and is safer to retry.

For API keys that existed before this policy was introduced, broad booking and pricing scans become unavailable on 26 October 2026 at 00:00 UTC. New API keys receive a 30-day migration period. Treat the enforcement_at value returned by the API as authoritative for your key.

Before your deadline, broad requests still succeed but include:

Deprecation: true
Sunset: Mon, 26 Oct 2026 00:00:00 GMT
Link: <https://docs.okup.ai/okupai-api/basics/pagination>; rel="deprecation"

The JSON body also contains an additive warning:

{
  "warnings": [
    {
      "code": "full_sync_deprecated",
      "message": "Repeated full synchronization will stop being supported after 2026-10-26.",
      "required_parameter": "updated_since",
      "docs_url": "https://docs.okup.ai/okupai-api/basics/pagination",
      "enforcement_at": "2026-10-26T00:00:00Z"
    }
  ]
}

Existing response fields are unchanged. Pricing warnings use changed_since as required_parameter.

Recommended delta workflow

1. Complete one bootstrap import and upsert every page locally.

2. Save the highest updated_at from bookings and changed_at from pricing only after all pages complete successfully.

3. On the next run, request:

   • /data/bookings?updated_since=<ISO-8601 timestamp>

   • /data/pricing?changed_since=<ISO-8601 timestamp>

4. Use a small overlap (for example, one second), and upsert by stable identifiers so retries and boundary timestamps are safe.

5. Continue requesting next_offset while has_more is true.

6. Send the previous response's ETag in If-None-Match for the exact same URL. A 304 Not Modified response has no JSON body.

Advance your saved timestamp only after every page succeeds. Run one sync job per OkupAI account. As a starting point, poll pricing every 5 minutes and bookings every 15 minutes.

Initial or recovery bootstrap

Use bootstrap mode only for an initial import or disaster recovery:

curl -sS \
  -H "X-API-Key: $OKUPAI_API_KEY" \
  "https://api.okup.ai/data/bookings?sync_mode=bootstrap&limit=1000&offset=0"

The first request with sync_mode=bootstrap&offset=0 opens a 30-minute window for that API key. During the window:

• include sync_mode=bootstrap on every page;

• follow next_offset until has_more is false;

• you may page through both bookings and pricing;

• do not combine bootstrap mode with updated_since or changed_since.

Only one bootstrap may start per API key in any 24-hour period. Starting another after the 30-minute window but before the cooldown ends returns 429 Too Many Requests; wait for Retry-After. A nonzero offset without an active window returns 422—when eligible, restart at offset=0.

Bounded operational reads

These focused requests remain available without delta or bootstrap mode:

• bookings with both from and to, for a window of at most 90 days;

• pricing with okupai_property_id, from, and to, for a window of at most 90 days.

These exemptions are for operational lookups, not repeated account-wide synchronization.

Enforcement errors

An unbounded request after your deadline returns:

HTTP/1.1 422 Unprocessable Entity
X-Error-Code: incremental_sync_required

{
  "error": "Broad synchronization now requires updated_since or sync_mode=bootstrap.",
  "code": "incremental_sync_required",
  "required_parameter": "updated_since",
  "bootstrap_parameter": "sync_mode=bootstrap",
  "docs_url": "https://docs.okup.ai/okupai-api/basics/pagination",
  "enforcement_at": "2026-10-26T00:00:00Z"
}

A bootstrap started during its cooldown returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 84540
X-Error-Code: bootstrap_cooldown

{
  "error": "A bootstrap may only be started once per API key every 24 hours.",
  "code": "bootstrap_cooldown",
  "docs_url": "https://docs.okup.ai/okupai-api/basics/pagination",
  "bootstrap_window_minutes": 30,
  "bootstrap_available_at": "2026-10-27T00:00:00Z"
}

If the API returns another 429, wait for Retry-After and add random jitter before retrying.

An ETag belongs to the exact request URL, including filters, pagination, and date range. Do not reuse it for a different URL.