Mastering Okta API Pagination: The Link-Header Cursor Model Explained

What You’ll Get From This Guide

When you call an Okta list endpoint (e.g., GET /api/v1/users), the response is split into pages. Okta does not expose an offset or page number; instead it returns an RFC 5988 Link header that contains a cursor‑based after parameter. This article shows you how to read that header, follow the cursor, and avoid common mistakes such as hitting the rate limit or skipping records.

Why Okta Uses Cursor‑Based Pagination

Cursor pagination gives the server full control over which records belong to each page, preventing gaps or duplicates when data changes between requests. The cursor is opaque: you never need to parse it, only pass the URL verbatim.

Step‑by‑Step: Listing Users with a Cursor

1. Initial request – include a limit (max 200 for users). The API will clamp values above the maximum without error.

   curl -X GET \
     "https://{yourOktaDomain}/api/v1/users?limit=200" \
     -H "Accept: application/json" \
     -H "Authorization: SSWS {apiToken}" \
     -w "%{http_code}\n" \
     -o users_page1.json
   

2. Read the Link header – the response contains something like:

   Link: <https://{yourOktaDomain}/api/v1/users?limit=200&after=Z3Vlc3Qx>; rel="next", <https://{yourOktaDomain}/api/v1/users?limit=200>; rel="self"
   

   The after query parameter is the cursor. Do not modify it; keep the URL exactly as provided.
3. Follow the cursor – make a new request to the next URL until the header no longer contains a rel="next" link.

   curl -X GET \
     "https://{yourOktaDomain}/api/v1/users?limit=200&after=Z3Vlc3Qx" \
     -H "Accept: application/json" \
     -H "Authorization: SSWS {apiToken}" \
     -w "%{http_code}\n" \
     -o users_page2.json
   

4. Aggregate results – merge the JSON arrays from each page into a single list. Use a streaming parser if the dataset is large.

Handling Filters and Search

If you use filter= or search= parameters, you only need to include them on the initial request. The next URL already contains the encoded query string. Re‑applying the filter on subsequent pages will cause duplicates or missing records.

Rate Limiting: The Silent Throttle

Okta enforces per‑endpoint rate limits. Each response includes:

• X-Rate-Limit-Limit – total allowed requests in the window.
• X-Rate-Limit-Remaining – remaining requests.
• X-Rate-Limit-Reset – epoch time when the window resets.

If you loop too quickly, you’ll receive a 429 Too Many Requests error. A simple back‑off strategy:

while (remaining > 0) {
  // make request
  // update remaining, reset
  if (remaining == 0) {
    sleep(reset - now)
  }
}

Common Mistakes to Avoid

• Hard‑coding a limit of 1000 or more – the server will silently clamp to the maximum, potentially returning fewer records than expected.
• Building the after cursor manually – the cursor is opaque; any tampering can break pagination.
• Ignoring the rel="next" link and stopping after the first page – you’ll miss half the users.
• Not handling 429 responses – your sync job will fail or retry indefinitely.
• Assuming the result set is a consistent snapshot – users added or updated during pagination can shift between pages, leading to duplicates or gaps.

Incremental Sync with lastUpdated Filter

For sync jobs, combine pagination with a filter on lastUpdated to process only changed records. Example:

GET /api/v1/users?limit=200&filter=lastUpdated+gt+"2026-10-12T00:00:00.000Z"

Remember to keep the same filter on the next URL; otherwise you’ll re‑process records.

Practical Verification

• Spin up a free Okta developer org and create >200 test users.
• Run the curl example with limit=2 to observe two pages and the Link header.
• Check the X-Rate-Limit-* headers during a tight loop to confirm throttling.
• Export all users via pagination and compare the count to the Admin Console’s user count to ensure no records were missed.

Conclusion

Okta’s cursor‑based pagination via RFC 5988 Link headers is straightforward once you follow the next URLs verbatim. Avoid hard‑coding limits, building cursors, or ignoring rate‑limit headers. With the practices above, you’ll reliably retrieve all users, groups, or apps without hitting throttles or skipping data.