Keeping Cursor Tokens Small: Compression, Encoding, Length Limits

Measure before you optimize. Mint a cursor from your widest real filter set, not from a unit test, and log both the encoded length and the decoded payload length. The ratio between them tells you where the bytes go.

import base64, json

def mint(payload: dict) -> str:
    raw = json.dumps(payload, separators=(",", ":")).encode()
    token = base64.urlsafe_b64encode(raw).decode().rstrip("=")
    print(f"json_bytes={len(raw)} token_chars={len(token)}")
    return token

The rule that follows:

• Under 1 KB: leave it alone.
• Between 1 KB and 2 KB: tighten the payload, drop redundant fields, shorten names.
• Over 2 KB, or growing with user input: move the payload to a server-side store and return an id plus a signature.

The 2 KB line is judgment, not specification. It leaves margin inside an 8 KB request budget so that browser cookies and a second Link header cannot tip a reasonable client over the edge. Treat 2 KB as a warning, 4 KB as a hard block, and 8 KB as the wall you will eventually be failed by.

A cursor exists to resume a query. It is not a cache for information the server does not want to look up. Anything cheaply derivable from an id belongs on the server.

Fields that routinely get stuffed in and should not:

• The user's identity or claims. The authenticated request already names the user, and duplicating it invites disagreement between the two.
• Tenant or workspace names. Store the id.
• Full filter objects. If the user filtered by category, price range and date, the cursor needs to detect that the filter changed, not carry the filter. A short hash of the filter signature is enough.
• Sort order spelled out in text. A single byte or short code covers it.
• Display values such as titles or URLs. If it is in the cursor, the client can read it, because base64 is an encoding, not a secret.

That last point has a security consequence. Clients receive cursors, keep them in browser history, and log them. A signature proves the token was not tampered with; it does not hide the payload. Treat every byte in the token as public, which is one more reason to keep it small.

When the payload must travel, encode it tightly. Three options, in order of effort:

Shortened keys. Rename created_at to t, last_id to i, filter_hash to h. A small schema map in code translates back, and a version byte lets you change the map later. This alone often cuts the JSON size by 40 percent.

Fixed binary layout. A version byte, an 8-byte big-endian timestamp, an 8-byte id and a 3-byte filter checksum is 20 bytes. Base64url of 20 bytes is 27 characters. The same information as full-key JSON runs 88 bytes and base64urls to 118 characters. The version byte also gives you a clean evolution path: an unknown version is rejected, not parsed as garbage.

CBOR or MessagePack. Integers stay integers and unwanted field names disappear, at the cost of a decoder dependency on both ends.

A worked comparison makes the gap concrete. The JSON cursor above plus a 32-byte HMAC crosses the wire at roughly 160 characters; the binary version with the same HMAC is roughly 75. Neither is a problem yet. The difference matters once the payload carries five more fields and you are shaving bytes after an incident.

Signing is not free. A 32-byte digest doubles to 44 characters under base64, and asymmetric signatures run far larger. Signing also creates a key rotation question: how do you retire a key without invalidating in-flight cursors?

The practical answer is to sign only what an attacker could abuse. If the token holds an opaque id, the id is the only thing worth signing. The server looks up the row, checks ownership against the authenticated request, and rejects a mismatch. A leaked cursor from one user then cannot read another user's page even if it is edited, provided the server checks ownership after lookup.

When you do sign, sign the encoded form rather than a JSON string, so verification does not depend on field ordering. Trim base64 padding in base64url headers, because padding is legal but easily mangled by proxies and clients. Put the signing algorithm version in the same version byte as the payload so a rotation is a recognizable error rather than a silent decode failure.

If the payload will not fit, stop squeezing. Mint an id, store the state with a TTL, return the id plus a signature. A random 128-bit id base64urls to 22 characters; a UUID without hyphens lands near 24. Add an HMAC and you stay under 100 characters in the worst case.

The cost is one read per page request. That read is usually what you would do anyway to validate the signature. Build it deliberately:

• Redis or DynamoDB with a TTL, keyed by token id, storing the decoded sort key, the filter signature and a mint time.
• An encrypted envelope if you cannot afford a read. Encryption hides contents and validates integrity, but makes tokens larger, not smaller, because ciphertext and tag both cost bytes. Use it when the payload is sensitive, not when it is large.
• A snapshot id if ordering must stay stable while rows change. Contentful's move to cursor-based pagination pairs cursors with dropping total counts, since counting large result sets is expensive (Contentful on cursor pagination).

The trade-off is real. A cache eviction invalidates pages mid-session, so return a clear restartable error rather than a 500, and set the TTL well beyond any reasonable session.

A limit in a comment is not a limit. Enforce it in three places.

At mint time, compute the encoded length and refuse to sign anything over budget. Return a problem detail rather than a 500. RFC 9457 defines a machine-readable error body with type, title, status and detail, and identifies the problem class by URI so clients can branch on it (RFC 9457). The Swagger walkthrough explains why this beats ad-hoc error shapes for human and machine consumers alike (Swagger on problem details). Frameworks make it easy: Spring's ProblemDetail renders an RFC 9457 body and sets the status automatically (Spring Framework docs). The older RFC 7807 defines the same structure and is now obsoleted (RFC 7807), so target the current one.

At parse time, reject oversized input before decoding. Check length, check the version byte, verify the signature, then decode. A decoder that accepts a 10 KB string and fails on a JSON parse is a small denial-of-service surface.

In tests, generate a cursor from the widest allowed filter set and assert it stays under budget. That is the test that catches the regression when someone adds one more field.

The limit also shows up in your contract. When you return a next link in the Link header, RFC 8288 governs its serialization and relation naming (RFC 8288). A walkthrough of Link-header pagination shows how the next-page URL is carried in that header (Vincent Schmalbach on Link-header pagination). A long cursor sits directly inside that header value, so shrinking the cursor shrinks the header.

Pagination design itself affects cursor size, because page length and ordering stability decide what must travel. Guides comparing offset and keyset pagination explain why keyset avoids deep scans and returns consistent pages as rows shift (Design Gurus pagination guide). AWS documents how inefficient pagination scans rows that produce no useful results and burns metered units (AWS Database Blog). WSO2 puts both patterns side by side before you commit an API surface (WSO2 pagination design patterns). If you need a consistency guarantee across filters and sort orders, there is a detailed treatment of encoding filter signatures and tie-breakers into a signed cursor (Medium).

A cursor format is a schema, and schemas change. Put a version byte first and dispatch on it during parse. When v2 arrives, keep v1 readable for as long as old cursors can persist, then reject them with a specific problem type so clients know to restart.

This is the same discipline API versioning applies at the endpoint level. Akamai's overview covers the choices (URI, header, query parameter) and the compatibility risks of each (Akamai on API versioning). Cursors need that rigor with a different mechanism: a version byte inside the token is simpler than shunting a version through the URI, and it keeps the version tied to the format rather than the route.

Keep the parse function total, turning any input string into a valid payload or a typed error, never a crash. Length check, strict base64url decode, version dispatch, signature check, payload decode, each with its own error code. Someone debugging a 400 at 2 a.m. will remember the error code, not the prose.

For teams running several model providers behind one surface, the same discipline applies where tokens are minted and consumed. Quanta Inference exposes text, image, video, audio and embedding models through one OpenAI-compatible key, which keeps cursor logic in your own application code instead of spreading it across provider SDKs.