Pagination and filtering

Cursors

List endpoints return a page of results and a cursor for the next one:

{
  "data": [ … ],
  "pagination": { "next_cursor": "eyJpZCI6MTIwfQ", "limit": 50 }
}

Pass next_cursor back as cursor to get the next page. When next_cursor is null, you have everything. Cursors are opaque: don't build or edit them.

import os, requests

url = "https://api.q4.sa/v1/documents"
params = {"symbols": "1120", "limit": 500}
headers = {"x-api-key": os.environ["Q4_API_KEY"]}
docs = []

while True:
    body = requests.get(url, params=params, headers=headers).json()
    docs += body["data"]
    cursor = body["pagination"]["next_cursor"]
    if not cursor:
        break
    params["cursor"] = cursor

limit defaults to 50 on most endpoints. The maximum is on each endpoint's page.

Filtering

• Lists are comma-separated and match any value: symbols=2222,1120.
• Different parameters must all match: symbols=2222&types=financial_report is Aramco's financial reports.
• Dates: from and to filter on the item's own date (published, traded, held), inclusive.
• `updated_after` filters on when we last changed the item.

Keeping in sync

1. Backfill once with limit=500.
2. Then poll with updated_after set to the time of your last successful run.
3. Add webhooks to hear about changes as they happen.