pagination.md

Pagination and filtering

Most MK.IO list endpoints accept query parameters that page, sort, and filter the results on the server. Using them keeps responses small, removes client-side filtering work, and reduces the number of follow-up requests your integration makes.

The shape of a list response

A list endpoint returns two top-level fields:

value: the array of resources on the current page.
supplemental: metadata about the result set, including pagination counts.

A trimmed response looks like this:

{
  "value": [
    { "name": "asset-001" },
    { "name": "asset-002" }
  ],
  "supplemental": {
    "count": 2,
    "kind": "Asset",
    "operation": "list",
    "pagination": {
      "start": 0,
      "end": 2,
      "records": 2,
      "total": 145
    }
  }
}

The pagination block tells you where you are in the collection: records is how many items this page returned, and total is how many exist across the whole project. Comparing them tells you whether more pages remain.

Limit a page with $top

$top caps how many items a single page returns. The service returns up to that many, and never more than exist.

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$top=10" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The $ is escaped as \$ in these examples so that your shell does not treat the parameter as a variable.

Page through results with $skiptoken

$skiptoken sets the start offset for the next page. Use it to walk a collection one page at a time.

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$top=10&\$skiptoken=<SKIPTOKEN>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Do not construct $skiptoken values by hand. Take the value from the previous response.

To page until the end, request pages until supplemental.pagination.records is smaller than your $top, or until the running total of returned records reaches supplemental.pagination.total.

Sort with $orderby

$orderby orders the result collection by a field. The valid fields depend on the endpoint.

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$orderby=properties/created%20desc" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

For the Media API asset list, sortable fields include name, properties/created, properties/lastModified, and properties/storageAccountName. Other APIs expose their own sort keys. Check the API reference for the fields a given endpoint supports.

Filter with $filter

$filter restricts the result set to items that match an expression.

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$filter=name%20eq%20'my-asset'" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The fields available to filter on vary by resource. Common examples are assets by name or properties/created, live events by properties/resourceState, devices by spec/siteName, and sites by status/locationName.

Filter by label

Several list endpoints also support label queries, which are separate from $filter.

Return items that carry a given label key with $label_key:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$label_key=studio" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

When you pass more than one $label_key, an item must carry all of those keys to match.

Match a key and value with $label. Use = for an exact match and ~ for a partial match:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$label=studio=paravalley" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Label queries are supported on the asset, live event, device, network, and site list endpoints.

Combine parameters to do less work

The parameters compose. A single request can limit, sort, and filter at once:

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets?\$top=10&\$orderby=properties/created%20desc&\$label=studio=paravalley" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

That one call returns the ten most recent assets for one studio, which would otherwise take a full list plus client-side sorting and filtering.

A pattern for scanning large collections

When you need to process an entire collection, work from narrow to broad:

Apply the narrowest $filter or label query the task allows.
Add $orderby if processing order matters.
Set a bounded $top.
Page with $skiptoken until no further records remain.

Filtering and sorting on the server is almost always better than listing everything and filtering locally. It returns less data, needs fewer follow-up requests, and keeps you clear of the rate limits.