> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirurobotics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

export const PlatformApiLink = ({endpoint, newTab, children}) => {
  const href = `/references/platform-api/2026-05-06/endpoints/${endpoint}`;
  if (newTab) {
    return <a href={href} target="_blank" rel="noopener noreferrer">{children}</a>;
  }
  return <a href={href}>{children}</a>;
};

All list endpoints in the Miru API support filtering to help you retrieve specific resources.

For example, when <PlatformApiLink endpoint="devices/list">listing devices</PlatformApiLink>, you can filter by `id`, `name`, and other fields.

## Single value filters

Each list endpoint supports its own set of filter names. To see the filters supported by a specific endpoint, look for query parameters in the **Query Parameters** section containing *filter by* in their description.

`id` is a common filter amongst all list endpoints. It allows you to filter by a resource's unique identifier. For example, when listing devices, you can filter by the <PlatformApiLink endpoint="devices/list#parameter-id"><strong>device id</strong></PlatformApiLink> using **`id=<device-id>`** in the request URL.

The following uses the `id=dvc_123` filter to include only the device with the `dvc_123` `id`:

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/devices?id=dvc_123' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```

Filtering by ID will return at most one resource, since IDs are unique. Other fields, like <PlatformApiLink endpoint="deployments/list#parameter-activity-status">deployment activity status</PlatformApiLink>, can return multiple results.

## Multi-value filters

To filter by multiple values, specify the filter values as a `|` separated list: `<filter_name>=<value_1>|<value_2>|<value_3>`.

Thus, to filter devices by multiple ids, you can use the `id` filter with a `|` separated list of ids: `id=dvc_123|dvc_456|dvc_789`.

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/devices?id=dvc_123|dvc_456|dvc_789' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```

## Combining filters

You can combine filters using `&`. All filters are combined with AND logic, so resources must match all criteria.

The following request filters the device list to include only the devices with the IDs `dvc_123` and `dvc_456` and the name `Robot A`: `id=dvc_123|dvc_456&name=Robot%20A`.

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/devices?id=dvc_123|dvc_456&name=Robot%20A' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```

## URL encoding

When using filters with special characters, ensure that you properly URL-encode the values.

For example, spaces are URL encoded as `%20`. Browsers and client applications will automatically URL-encode the values for you, so you shouldn't need to worry about it, but it's good to know.

The following request filters the device list to only include devices named `My Device Name` using the `name=My%20Device%20Name` filter.

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/devices?name=My%20Device%20Name' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```