पृष्ठांकनन्यायः। लेखापरीक्षापथे (२१ सितम्बे) चिह्नम्। अत्र सूची कथं मिता दीयते। अङ्कपृष्ठं, कुञ्चिका, क्रमः, सीमा। न अनन्तउत्तरम्; पृष्ठधर्मः।
English (minimizable)
After audit trails (21 Sep), this post treats how APIs return lists in slices. It covers offset pages, cursor or keyset pagination, sort stability, max page size, opaque tokens and when not to COUNT everything.
पूर्ण-शीर्षकम् / Full title
पृष्ठांकनन्यायः: A Metrical Codification of API Pagination (with English glosses)
English · overview and topics (minimizable)
What this post is about
Pagination is how an API returns a large collection in bounded pages instead of one giant array.
Topics covered
- Why unbounded lists hurt servers and clients
- Offset/page-number vs cursor/keyset pagination
- Deterministic sort order as contract
- Max page size
- Response fields: items, next_cursor, has_more, optional total
- Opaque cursors (security)
- Deletes and bidirectional scroll
- Links to rate limits and retries
Who should read
API designers, mobile and web client authors, backend engineers owning list endpoints.
Sanskrit note
Title पृष्ठांकनन्यायः = pṛṣṭhāṅkana-nyāyaḥ roughly “the rule/method of page-marking”.
परम्परा-सन्धिः / Series links
| पूर्वं / Prior | अत्र किम् उपचीयते / Adds | किं न पुनरुच्यते / Does not repeat |
|---|---|---|
| संविदापरीक्षा (२६ जुलै) | boundary field stability | list field names |
| सीमादरः (१३ अगस्त) | admission rate | page-size abuse |
| द्वारपालसेवा (१२ अगस्त) | edge entry | list at gateway |
| इदम् | cursors offsets order max-page | - |
ग्राह्य-त्याज्य-विवेकः / Keep and avoid
ग्राह्यम् / Keep
१. मितपृष्ठम्: hard max page size
२. कुञ्चिकापथः: prefer cursor/keyset for large changing data
३. क्रमसत्यम्: document sort keys
४. अपारकुञ्चिका: opaque cursor tokens
५. has_more: clear end signal
६. गणनाविवेकः: total count only when cheap or needed
७. इदमर्थपठनम्: list GET safe to retry
त्याज्यम् / Avoid
- return entire table by default
- client-built SQL in cursor
- offset deep page on huge tables as only option
अध्याय-योजना / Chapter plan
| प्रकरणम् | विषयः | छन्दः | श्लोकाः |
|---|---|---|---|
| १ | मङ्गलं बीजं च / Opening | अनुष्टुभ् | २ |
| २ | मूलतत्त्वानि / Core ideas | अनुष्टुभ् | २ |
| ३ | मुख्यविधिः / Main method | उपजाति | १ |
| ४ | रक्षा · विधिः / Guardrails | अनुष्टुभ् | २ |
| ५ | विवेक · सीमा / Judgment | अनुष्टुभ् | २ |
| ६ | पूर्वसन्धिः / Links to earlier posts | उपजाति | १ |
| ७ | उपसंहारः / Close | अनुष्टुभ् | २ |
पारिभाषिक-कोशः / Glossary
| Modern English | संस्कृतम् | Note |
|---|---|---|
| pagination | पृष्ठांकनम् | |
| offset pagination | अङ्कपृष्ठम् / पृष्ठसङ्ख्या | |
| cursor/keyset | कुञ्चिकापृष्ठम् / कुञ्चिकानुसारम् | |
| page size | पृष्ठमात्रा / सीमा | |
| next cursor | अग्रेकुञ्चिका | |
| has_more | अधिकास्ति / अवशिष्टम् | |
| stable sort | स्थिरक्रमः | |
| opaque token | अपारसंकेतः | |
| deep pagination | गभीराङ्कपृष्ठम् | offset into huge offsets |
| seek method | अन्वेषणविधिः | keyset alias |
श्लोकः १ (अनुष्टुभ्)
पृष्ठांकनन्यायस्तस्माद् मितदर्शनसाधनम् ॥१॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
बिना सीमां यदि सूची दीयते तदा यन्त्रं दह्यते ।
पृष्ठांकनन्यायः तस्मात् मितदर्शनसाधनम् ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| बिना | without |
| सीमाम् | limit/bound |
| यदि | if |
| सूची | list |
| दीयते | is given |
| तदा | then |
| यन्त्रम् | machine/system |
| दह्यते | is burned |
| पृष्ठांकनन्यायः | pagination dharma |
| तस्मात् | therefore |
| मितदर्शनसाधनम् | means of measured seeing |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| बिना सीमाम् | without a bound |
| सूची दीयते | full list returned |
| यन्त्रं दह्यते | system burns |
| मितदर्शनम् | measured viewing |
English sense
If an API returns an unbounded list, memory, time and client UI all suffer. Pagination exists so each response is a bounded window of results.
Context / topic
Topic: why pagination exists. Problem: unbounded list endpoints.
वृत्तमिति: ८-८-८-८।
श्लोकः २ (अनुष्टुभ्)
कुञ्चिकापृष्ठं स्थिरं सत्ये योजने च ॥२॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
अङ्कपृष्ठं सरलं किन्तु अस्थिरं महति लेखे ।
कुञ्चिकापृष्ठं स्थिरं सत्ये योजने च ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| अङ्कपृष्ठम् | number-page (offset) |
| सरलम् | simple |
| किन्तु | but |
| अस्थिरम् | unstable |
| महति लेखे | on a large table |
| कुञ्चिकापृष्ठम् | key/cursor page |
| स्थिरम् | stable |
| सत्ये योजने | in true joining/order |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| अङ्कपृष्ठम् | offset/page-number pages |
| अस्थिरम् | unstable under writes |
| कुञ्चिकापृष्ठम् | cursor/keyset pages |
| स्थिरम् | stable |
English sense
Offset pagination (page=3 and limit=20) is easy to code but skips or duplicates rows when data changes between calls. Cursor or keyset pagination (after_id=…) stays stable for feeds and large tables.
Context / topic
Topic: offset vs cursor. Prefer cursors for infinite scroll and high-write tables.
वृत्तमिति: ८-८-८-८।
श्लोकः ३ (अनुष्टुभ्)
अक्रमसूचौ पृष्ठं मिथ्या भवेत् सदा ॥३॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
क्रमः स्पष्टः लेख्यः स्यात् येन कुञ्चिका सिध्यति ।
अक्रमसूचौ पृष्ठं मिथ्या भवेत् सदा ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| क्रमः | order |
| स्पष्टः | clear |
| लेख्यः | documented |
| येन | by which |
| कुञ्चिका | cursor |
| सिध्यति | succeeds |
| अक्रमसूचौ | in unordered list |
| पृष्ठम् | page |
| मिथ्या | false |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| क्रमः स्पष्टः | explicit sort order |
| कुञ्चिका सिध्यति | cursor works |
| अक्रमसूचौ | unordered list |
English sense
A cursor is only meaningful if the sort key is total and documented (for example created_at, id). Without a deterministic order, pages lie.
Context / topic
Topic: deterministic ordering is part of the API contract.
वृत्तमिति: ८-८-८-८।
श्लोकः ४ (अनुष्टुभ्)
अतिमहत्पृष्ठं पुनः दाहं वहेत् ॥४॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
सीमा मिता ग्राहकाय दातव्या न तु अनन्ता ।
अतिमहत्पृष्ठं पुनः दाहं वहेत् ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| सीमा | limit |
| मिता | measured |
| ग्राहकाय | for the client |
| दातव्या | must be given |
| न तु अनन्ता | not unlimited |
| अतिमहत्पृष्ठम् | over-large page |
| पुनः | again |
| दाहम् | heat/load |
| वहेत् | would carry |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| सीमा मिता | bounded page size |
| अतिमहत्पृष्ठम् | huge page |
| दाहम् | burn |
English sense
Even with pagination, allow a max page size. Clients asking for limit=100000 are still a denial of service.
Context / topic
Topic: max page size and server-side caps.
वृत्तमिति: ८-८-८-८।
श्लोकः ५ (उपजाति)
next_cursor वा शून्यं स्पशेत् ।
गणना सर्वेषां महती
न नित्यं दातव्या लघौ पथि ॥५॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
has_more सत्यं वदेत् अन्ते next_cursor वा शून्यं स्पशेत् ।
गणना सर्वेषां महती न नित्यं दातव्या लघौ पथि ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| has_more | whether more exists |
| सत्यम् | truthfully |
| वदेत् | should say |
| अन्ते | at the end |
| next_cursor | next cursor |
| शून्यम् | empty/null |
| गणना | count |
| सर्वेषाम् | of all |
| महती | expensive |
| न नित्यम् | not always |
| लघौ पथि | on the light path |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| has_more | boolean more pages |
| next_cursor | opaque next token |
| गणना सर्वेषाम् | total count of all rows |
English sense
Return either a next cursor or has_more. Full COUNT(*) on every list call is often too expensive for the hot path; offer totals only when needed.
Context / topic
Topic: response shape and expensive totals.
API shape: items + next_cursor + optional total.
वृत्तमिति: एकादशाक्षराः पादाः।
श्लोकः ६ (अनुष्टुभ्)
ग्राहकः संकेतं वहेद् न तु SQL रचयेत् ॥६॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
कुञ्चिका अपारा स्यात् न तु आन्तरिकं गुह्यं स्फुटतु ।
ग्राहकः संकेतं वहेत् न तु SQL रचयेत् ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| कुञ्चिका | cursor |
| अपारा | opaque |
| न तु | not |
| आन्तरिकम् | internal |
| गुह्यम् | secret |
| स्फुटतु | should spill |
| ग्राहकः | client |
| संकेतम् | token |
| वहेत् | carries |
| SQL | SQL |
| रचयेत् | should compose |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| अपारा | opaque |
| आन्तरिकं गुह्यम् | internal secret |
| SQL रचयेत् | client builds SQL |
English sense
Cursors should be opaque tokens (often signed or encrypted). Never let clients invent offsets into internal indexes or raw SQL fragments.
Context / topic
Topic: opaque cursors and security.
वृत्तमिति: ८-८-८-८।
श्लोकः ७ (अनुष्टुभ्)
मृतपंक्तौ स्थिरता कठिना भवेत् ॥७॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
लोपलेखे कुञ्चिका धर्मं पृथक् विचिन्तयेत् ।
मृतपंक्तौ स्थिरता कठिना भवेत् ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| लोपलेखे | in deletion case |
| कुञ्चिकाधर्मम् | cursor policy |
| पृथक् | separately |
| विचिन्तयेत् | must consider |
| मृतपंक्तौ | when row is gone |
| स्थिरता | stability |
| कठिना | hard |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| लोपलेखे | when rows delete |
| मृतपंक्तौ | on missing rows |
| स्थिरता | stability |
English sense
Deletes and updates between pages need a stated policy: skip missing keys, or return a clear error, or use a snapshot read.
Context / topic
Topic: mutation between page fetches.
वृत्तमिति: ८-८-८-८।
श्लोकः ८ (अनुष्टुभ्)
एकदिशि केवलं नित्यं मास्तु नीतिः ॥८॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
प्रतिलोमपृष्ठं यदि इष्टं तदा कुञ्चिकाद्वयं कुर्यात् ।
एकदिशि केवलं नित्यं मास्तु नीतिः ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| प्रतिलोमपृष्ठम् | reverse page |
| इष्टम् | wanted |
| कुञ्चिकाद्वयम् | cursor pair |
| एकदिशि | one direction |
| नित्यम् | always |
| मास्तु | must not be |
| नीतिः | the only policy |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| प्रतिलोमपृष्ठम् | backward page |
| कुञ्चिकाद्वयम् | prev and next cursors |
| एकदिशि | one-way only |
English sense
If the product needs scroll up and down, design prev and next cursors together. Do not invent reverse by subtracting offsets later.
Context / topic
Topic: bidirectional pagination.
वृत्तमिति: ८-८-८-८।
श्लोकः ९ (अनुष्टुभ्)
चञ्चलक्षेत्रैः ग्राहकाः भिद्यन्ते ॥९॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
संविदायां पृष्ठक्षेत्राणि लेख्यानि स्थिरनामानि ।
चञ्चलक्षेत्रैः ग्राहकाः भिद्यन्ते ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| संविदायाम् | in the contract |
| पृष्ठक्षेत्राणि | page fields |
| लेख्यानि | must be written |
| स्थिरनामानि | stable names |
| चञ्चलक्षेत्रैः | with unstable fields |
| ग्राहकाः | clients |
| भिद्यन्ते | break |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| संविदायाम् | in the API contract |
| स्थिरनामानि | stable field names |
| चञ्चलक्षेत्रैः | churning fields |
English sense
Document page size defaults, max, cursor field names and error codes in the contract. Renaming nextPageToken every quarter breaks every mobile client.
Context / topic
Topic: contract testing and stable pagination fields. Links to संविदापरीक्षा.
वृत्तमिति: ८-८-८-८।
श्लोकः १० (उपजाति)
किन्तु महत्याचने वेगं बध्नाति ।
पुनर्यत्ने कुञ्चिका स्थिरा
द्विः दानं मा वहेत् पथि ॥१०॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
सीमादरः पृष्ठं न हन्ति धर्मे किन्तु महत्याचने वेगं बध्नाति ।
पुनर्यत्ने कुञ्चिका स्थिरा द्विः दानं मा वहेत् पथि ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| सीमादरः | rate limit |
| पृष्ठम् | page |
| न हन्ति | does not kill |
| धर्मे | in dharma |
| महत्याचने | on oversized ask |
| वेगम् | rate |
| बध्नाति | binds |
| पुनर्यत्ने | in retry |
| कुञ्चिका | cursor |
| स्थिरा | stable |
| द्विः दानम् | double gift/effect |
| मा वहेत् | must not carry |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| सीमादरः | rate limit |
| महत्याचने | huge page ask |
| पुनर्यत्ने | on retry |
| द्विः दानम् | double side effect |
English sense
Rate limits and pagination work together: cap abusive list storms and keep list GETs idempotent so retries with the same cursor do not create writes.
Context / topic
Topic: link to rate limit and retry treatises.
सन्धिः: सीमादरः + पुनःप्रयासः + पृष्ठांकनम्.
वृत्तमिति: एकादशाक्षराः पादाः।
श्लोकः ११ (अनुष्टुभ्)
एभिः पृष्ठांकनं मितदर्शनसमन्वितम् ॥११॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
सीमा क्रमः कुञ्चिका अपारता गणनाविवेकः पञ्चकम् ।
एभिः पृष्ठांकनं मितदर्शन समन्वितम् ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| सीमा | page size bound |
| क्रमः | sort order |
| कुञ्चिका | cursor |
| अपारता | opacity |
| गणनाविवेकः | count discretion |
| पञ्चकम् | set of five |
| मितदर्शनम् | measured view |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| पञ्चकम् | five limbs: size order cursor opacity count-policy |
English sense
Five limbs of pagination dharma: bound size, fix order, use cursors, keep them opaque and treat totals as optional cost.
Context / topic
Topic: checklist summary.
वृत्तमिति: ८-८-८-८।
श्लोकः १२ (अनुष्टुभ्)
मितं सत्यं क्रियायोग्यं तन्त्रधर्मः स उच्यते ॥१२॥
पदच्छेदः · Word-for-word · English (minimizable)
पदच्छेदः
इति पृष्ठांकनन्यायसारः मितसूची समन्वितः ।
मितं सत्यं क्रियायोग्यं तन्त्रधर्मः सः उच्यते ॥
Word-for-word
| संस्कृतपदम् | Word-for-word English |
|---|---|
| इति | thus |
| पृष्ठांकनन्यायसारः | essence of pagination dharma |
| मितसूची | measured list |
| समन्वितः | joined |
| मितम् | measured |
| सत्यम् | true |
| क्रियायोग्यम् | operable |
| तन्त्रधर्मः | system dharma |
| उच्यते | is called |
Gloss table
| पदम् | अर्थः / sense |
|---|---|
| मितसूची | bounded list |
| तन्त्रधर्मः | platform dharma |
English sense
Closing: a good list API shows the truth in slices that clients and servers can both afford.
Context / topic
Topic: closing dharma for API list design.
उपसंहारन्यायः: मा सर्वं देहि; मितं देहि; स्थिरं देहि।
वृत्तमिति: ८-८-८-८।
श्लोकसूची / Verse index
१. Unbounded list burn / अनन्तसूचीदाहः
२. Offset vs cursor / अङ्कः कुञ्चिका च
३. Order contract / क्रमसंविदा
४. Max page size / अधिकतमसीमा
५. has_more and totals / अवशिष्टं गणना च
६. Opaque cursor / अपारकुञ्चिका
७. Deletes mid-scroll / लोपमध्ये
८. Bidirectional pages / उभयदिशा
९. Contract fields / संविदाक्षेत्राणि
१०. Rate limit and retry links / सीमा यत्नसन्धिः
११. Five limbs / पञ्चाङ्गम्
१२. Closing dharma / उपसंहारः
सन्दर्भाः / References
- Prior: contract tests 2026-07-26; rate limit 2026-08-13; API gateway 2026-08-12.
- Domain: REST/GraphQL list pagination cursors keyset offsets.
- From this post onward: each verse carries word-for-word English and sense.
- Style: no em dash; no Oxford comma in English clauses.