Pagination and jobs

Cursors on every list, and how a request for more than 50 items becomes a job.

Pages

List endpoints return a page of items and a meta object. When another page exists, meta.next_cursor is set:

curl "https://api.instadata.dev/v1/instagram/comments?url=https://www.instagram.com/p/C8xQvZ2sVAb/&limit=50" \
  -H "Authorization: Bearer ik_live_..."

Pass meta.next_cursor back as cursor for the next page. No next_cursor means the last page. Cursors are opaque and short-lived.

params = {"url": post_url, "limit": 50}
items = []
while True:
    r = httpx.get(f"{BASE}/v1/instagram/comments", params=params, headers=H, timeout=120).json()
    items += r["data"]
    cursor = r.get("meta", {}).get("next_cursor")
    if not cursor:
        break
    params["cursor"] = cursor

Credits are charged per item returned. If the balance cannot cover the whole page, the page is clamped to what it can cover and the X-Limit-Clamped header says so. Free keys get at most 5 items a call, and X-Limit-Capped says when a request was lowered to that.

Jobs

Synchronous lists stop at limit=50. Ask for more and the call becomes a job:

curl "https://api.instadata.dev/v1/instagram/channel-posts?handle=nasa&limit=500" \
  -H "Authorization: Bearer ik_live_..."

{
  "data": { "job_id": "job_01J…", "status": "queued", "poll_url": "https://api.instadata.dev/v1/jobs/job_01J…" },
  "request_id": "req_01J…"
}

The response is 202 Accepted. Poll GET /v1/jobs/{id} until status is succeeded or failed; the result carries the items, or a result_url for large sets. Credits are charged when results are delivered, per item. Register a webhook for job.completed to skip polling.