Pagination

The state of the spec

Of the ~292 publishable Admin API operations, 9 list endpoints declare pagination parameters in the OpenAPI document. The rest either:

• return a single resource (GET /users/{id}),
• return a bounded collection too small to paginate, or
• are list endpoints whose spec has not yet declared the parameters (the runtime may accept query params not yet documented).

Two patterns coexist in the declared 9:

Pattern	Endpoints	Params (verified in spec)
limit + offset	4	limit, offset (both string)
limit + page	2	limit, page (both number)
limit only	3	limit — no offset / page declared

Endpoints that declare pagination

Endpoint	Pattern
GET /api/v1/stores/{storeId}/domains/notifications	limit + offset (string)
GET /api/v1/stores/{storeId}/email-forwards/{forwardId}/logs	limit + offset (string)
GET /api/v1/taxes/currencies	limit + page (number)
GET /api/v1/themes	limit + page (number)
GET /api/v1/taxes/hs-codes	limit only
GET /api/v1/taxes/rates/sync-history	limit only
GET /api/internal/ai/usage/{storeId}/logs	limit only — internal
GET /api/internal/policy/hs-codes	limit only — internal
GET /api/internal/taxes/rates/sync-history	limit only — internal

The three /api/internal/* endpoints are filtered out by the dev portal's isPublishableOperation rule and do not appear in /api/*. They are listed here for completeness.

Worked example — limit + offset

# Page 1
curl 'https://api.tanqory.com/api/v1/stores/STORE_ID/domains/notifications?limit=20&offset=0' \
  -H "Authorization: Bearer $TANQORY_API_KEY"
 
# Page 2
curl 'https://api.tanqory.com/api/v1/stores/STORE_ID/domains/notifications?limit=20&offset=20' \
  -H "Authorization: Bearer $TANQORY_API_KEY"

Response shapes vary and are under-declared in the spec, so verify per endpoint. Two shapes are observed live:

• Bare array — some endpoints return the resource array directly; the end of the collection is an empty array.
• Paged envelope — others wrap results with totals. Verified live on the account activity log (GET /api/v1/auth/activity/logs):

{
  "data": [ /* … */ ],
  "total": 128,
  "page": 1,
  "limit": 20,
  "total_pages": 7
}

For that endpoint, limit defaults to 20 and is capped at 100 (verified). Loop until page reaches total_pages:

page=1
while :; do
  resp=$(curl -s "https://api.tanqory.com/api/v1/auth/activity/logs?page=$page&limit=20" \
    -H "Authorization: Bearer $TANQORY_API_KEY")
  echo "$resp" | jq '.data[]'
  [ "$page" -ge "$(echo "$resp" | jq '.total_pages')" ] && break
  page=$((page+1))
done

There is no has_more field — use page vs total_pages. Do not assume one shape across endpoints until the spec declares a unified envelope.

Worked example — limit + page

# Page 1 (1-indexed in this pattern)
curl 'https://api.tanqory.com/api/v1/themes?page=1&limit=20' \
  -H "Authorization: Bearer $TANQORY_API_KEY"
 
# Page 2
curl 'https://api.tanqory.com/api/v1/themes?page=2&limit=20' \
  -H "Authorization: Bearer $TANQORY_API_KEY"

What is not documented yet

The following are deliberate gaps — they are not in the spec today; do not infer them:

Gap	Status
Default / max limit per endpoint	Not in the spec. Verified live for the activity log: default 20, max 100. Other endpoints [FOUNDER TO CONFIRM].
total / total_pages envelope	Not in the spec, but returned live by the activity log (see the worked example above). Coverage across endpoints [FOUNDER TO CONFIRM].
has_more response field	Not used — pagination is page/total_pages-based, not cursor.
Link header with rel="next" / rel="prev"	Not declared in spec.
Cursor-based pagination	Not yet shipped on any endpoint.
Sort / order parameters	Not declared in spec on any list endpoint.

When the spec is amended to add a unified cursor pattern, this page will be rewritten and the legacy offset / page endpoints flagged for migration.

Next steps

Topic	When to read it
Errors	If the server rejects an out-of-range offset / page.
Rate limits	When paging through large collections in a loop.
Versioning	The unified cursor pattern will land behind a version bump.