Pagination

Page-based pagination envelope used by list endpoints.

Most V1 list endpoints return a shared pagination envelope. Use the page and page_size query parameters (where documented per endpoint) to walk through results. The OpenAPI spec is authoritative for defaults and maximum page sizes.

Paginated response envelope

{
  "count": 142,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "has_next": true,
  "has_previous": false,
  "results": [ /* ... */ ]
}
Field Meaning
count Total number of matching rows across all pages.
page Current page number (1-based).
page_size Maximum rows returned in this page.
total_pages Total pages given the current page_size.
has_next true when another page exists after this one.
has_previous true when a page exists before this one.
results Array of items for the current page.

Page size

Inventory and ingestion list endpoints accept page_size between 1 and 100 where documented in OpenAPI. When omitted, the default is endpoint-specific — check the spec rather than assuming a global default.

MusiSearch (POST /v1/search/tracks) uses the same envelope fields in its response body; pagination parameters are described in the OpenAPI operation.

Where pagination applies

Endpoint Notes
GET /v1/catalogs List shape; V1 may return zero or one catalogue.
GET /v1/tracks Technical track inventory.
GET /v1/artists Technical artist inventory.
GET /v1/releases Technical release inventory.
GET /v1/works Technical work inventory.
GET /v1/ingestions Ingestion delivery status list.
GET /v1/ingestions/{id}/entities Delivered entities for one batch.
GET /v1/ingestions/{id}/items Ingestion item rows.
GET /v1/storage/objects List mode only; exact lookup via object_key is not paginated.
POST /v1/search/tracks MusiSearch results envelope.

Where pagination does not apply

  • GET /v1/taxonomies/tags — full taxonomy returned in one response (~267 tags in V1).
  • POST /v1/audio/tagging — live tagging returns a single result object.
  • GET /v1/audio/tagging — stored tagging lookup for one track.
  • POST /v1/audio/features — live feature extraction for one object.
  • POST /v1/profiling/tracks — aggregate profiles for the submitted track list.
  • OpenAPI spec — per-endpoint parameters and schemas.
  • Errors — validation errors for out-of-range page values.