Paginate and synchronize safely

Growing collections use filter-bound snapshot cursors so one traversal sees a stable upper watermark while records continue changing.

1. Send the first request with documented filters and limit.
2. Process data.
3. If pagination.has_more is true, send another request with the exact pagination.next_cursor.
4. Keep the same endpoint and filters.
5. Stop when has_more is false and next_cursor is null.

The default limit is 50 and the maximum is 200. Treat a cursor as opaque: do not decode, edit, persist beyond its synchronization cycle, or reuse it with a different endpoint, path identifier, filter, or ordering.

{
  "data": [],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Collections that document created_after or updated_after accept RFC 3339 UTC timestamps. The two parameters are mutually exclusive.

1. Complete the current snapshot traversal.
2. Store a safe synchronization watermark appropriate to your design.
3. Start the next cycle with updated_after to include later creations and updates.
4. Traverse all returned cursors without changing that filter.
5. Upsert by resource id and tolerate at-least-once delivery.

Do not use client wall-clock time as proof that the server has returned every change. Avoid advancing a checkpoint before the entire cycle is durably processed.

Halqa and student collections include records across semesters unless semester_id or semester_status is supplied. Their id identifies the semester-specific record. lineage_id identifies the continuing logical halqa or learner across a semester carry-forward.

Choose keys deliberately:

• use id for API reads, writes, and exact record state;
• use lineage_id to correlate historical and successor records;
• never substitute one for the other.

• Semesters, halqas, students, sessions, recitation collections, Learning Plans, assignments, and attendance define snapshot pagination.
• The eligible-sheikh lookup is current discovery, not an incremental feed.
• Surah reference data is bounded and does not accept pagination or filters.

An invalid_query response means a filter, cursor binding, timestamp, or limit does not match the contract. Restart a new traversal with valid filters rather than modifying the cursor.