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

# Sorting

API list endpoints support sorting using the `order_by` query parameter.

The Miru API uses field-based sorting. You can specify which field(s) to sort by and the sort direction (ascending or descending).

Resource IDs are used as a tie-breaker when multiple resources have equivalent fields to ensure deterministic sort results.

## Query parameters

List endpoints that support sorting accept the `order_by` query parameter, which is optional.

### Order by

You can sort the list results using the following format: `<field_name>:<direction>`. The direction is optional and defaults to descending if not specified.

To illustrate, the following order by queries are all valid:

* `order_by=created_at`
* `order_by=created_at:asc`
* `order_by=created_at:desc`

The available sort fields depend on the specific endpoint. Look for the `order_by` query parameter in the **Query Parameters** section of the list endpoint you want to sort.

Common sort fields include:

* `id` - Sort by object ID
* `created_at` - Sort by creation timestamp

All fields support exactly two sort directions.

* `asc` - Ascending order (A-Z, a-z, 0-9, oldest first, etc.)
* `desc` - Descending order (Z-A, z-a, 9-0, newest first, etc.)

## Single field sorting

For endpoints that support single-field sorting, add the `order_by` query parameter to the list endpoint URL.

The following request sorts config instances by descending creation date using the query parameter `order_by=created_at:desc`.

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

The following request sorts config instances by ascending creation date using the query parameter `order_by=created_at:asc`.

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

## Multiple field sorting

In cases where your primary field sort yields multiple items that hold the same value, you may find it beneficial to sort by auxiliary fields. In such cases, you can specify additional sort fields via a comma-separated list: **`<field_name_1>:<direction_1>,<field_name_2>:<direction_2>,...`**.

Let's take the example of `order_by=created_at:desc,id:asc`:

* First, the results are sorted by the `created_at` field in descending order (newest items appear first).
* For any items that have the same `created_at` timestamp, the API uses `id` as a tie-breaker.
* Last, the tied items are sorted by `id` in ascending order (lowest ID first).

```json theme={null}
{
  "object": "list",
  "limit": 10,
  "offset": 0,
  "has_more": false,
  "data": [
    {
      "object": "device",
      "id": "dvc_4",
      "created_at": "2023-01-01T00:00:00Z"
      ...
    },
    {
      "object": "device",
      "id": "dvc_2",
      "created_at": "2022-01-01T00:00:00Z"
      ...
    },
    {
      "object": "device",
      "id": "dvc_3",
      "created_at": "2022-01-01T00:00:00Z"
      ...
    },
    {
      "object": "device",
      "id": "dvc_1",
      "created_at": "2021-01-01T00:00:00Z"
      ...
    },
  ]
}
```

All devices are sorted by creation date (`created_at`) in descending order. Since elements with IDs 2 and 3 have the same creation date, they are sorted by ID in ascending order.

The following request sorts devices by descending creation date and then by ascending ID:

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

## Deterministic sorting

By default, all sorting queries use resource IDs as a tie-breaker (ascending order) to ensure deterministic results. For example, `created_at:desc` is effectively `created_at:desc,id:asc`.

If a request already contains `id` as a sort field, then the request is already deterministic, and an additional `id` sort field will not be added.

To illustrate this, the following table shows the original request ordering and the effective request ordering for a few different examples.

| Original                 | Effective                |
| ------------------------ | ------------------------ |
| `created_at:desc`        | `created_at:desc,id:asc` |
| `name:asc`               | `name:asc,id:asc`        |
| `created_at:desc,id:asc` | `created_at:desc,id:asc` |
| `id:asc,created_at:desc` | `id:asc,created_at:desc` |