> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/platform/understanding/pagination/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# 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 response includes these fields:

* `value`: the array of resources on the current page.

* `supplemental`: metadata about the result set, including pagination counts.

* `@odata.nextLink`: the URL for the next page, when another page is available.

A trimmed response looks like this:

```json
{
  "value": [
    { "name": "asset-001" },
    { "name": "asset-002" }
  ],
  "supplemental": {
    "count": 2,
    "kind": "Asset",
    "operation": "list",
    "pagination": {
      "start": 0,
      "end": 2,
      "records": 2,
      "total": 145
    }
  },
  "@odata.nextLink": "<NEXT_PAGE_URL>"
}

```

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. Use `@odata.nextLink` to continue through the result set, including when you have applied filters.

## 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.

```bash
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

The service uses `$skiptoken` to identify the start offset of a page. It supplies the next request URL in `@odata.nextLink`, so you do not need to construct the token yourself.
After processing the current page’s `value` array, request the URL returned in `@odata.nextLink` with the same bearer authentication:

```bash
curl -X GET "<NEXT_PAGE_URL>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

Replace `<NEXT_PAGE_URL>` with the complete `@odata.nextLink` value from the response. Continue following each returned link until `@odata.nextLink` is absent. Keep the query parameters in the returned URL so the next request continues the same result set.

## Sort with \$orderby

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

```bash
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.

```bash
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`:

```bash
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:

```bash
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:

```bash
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`.

* Follow `@odata.nextLink` until the response no longer includes it.

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](/platform/understanding/rate-limits).

## Related reading

* API overview: the request and response conventions these endpoints share.

* Rate limits: why server-side filtering matters for request volume.