Pagination

List endpoints (posts, comments, replies) return one page per request and an opaque cursor for the next page. Pass it back as the cursor query parameter to continue. When meta.cursors.next is null, you have reached the end.

curl "https://api.openhandle.dev/v1/instagram/profiles/@instagram/posts" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"

{
  "platform": "instagram",
  "resource": "post",
  "capturedAt": "2026-08-06T12:04:11Z",
  "source": "live",
  "data": ["…"],
  "meta": {
    "cursors": { "next": "b3BhcXVlLWN1cnNvcg" }
  }
}

Next page:

curl "https://api.openhandle.dev/v1/instagram/profiles/@instagram/posts?cursor=b3BhcXVlLWN1cnNvcg" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"

Rules

• Cursors are opaque. Do not parse, store long-term, or construct them. Their format can change at any time.
• Cursors are bound to their request. A cursor belongs to the endpoint, the target, the freshness tier, and every query input the request sent, such as q, limit, sort, type, since, or a playlist or comment ID. It also belongs to the environment of the key: a cursor from a Test key does not work with a Live key. Send the same inputs with the cursor. A cursor with a changed input returns CURSOR_MISMATCH.
• Each page is one billable request. Fetching five pages is five requests.
• Sources can switch mid-pagination. If the upstream source no longer accepts a cursor, for example because it expired, the API returns UPSTREAM_SWITCHED (HTTP 409) with retryable: false and details.restartRequired: true. Do not retry the same cursor. Restart the pagination from the first page.

Limiting history with since

Profile post lists on Instagram, TikTok, and Twitter (profile.posts.list) accept a since parameter with an RFC 3339 timestamp. Posts older than that point are left out of the page. Pagination ends once the feed passes that point, so you do not pay for pages you would discard. An old pinned post at the top of a profile does not end it. A value that is not an RFC 3339 timestamp returns INVALID_SINCE. Send the same since with every cursor:

curl "https://api.openhandle.dev/v1/instagram/profiles/@instagram/posts?since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"