Skip to main content
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 endpoints’ 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. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/config_instances?order_by=created_at:desc' \
  --header 'X-API-Key: <api-key>'
The following request sorts config instances by ascending creation date using the query parameter order_by=created_at:asc. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/config_instances?order_by=created_at:asc' \
  --header 'X-API-Key: <api-key>'

​
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, 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).
{
  "object": "list",
  "total_count": -1,
  "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: 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/devices?order_by=created_at:desc,id:asc' \
  --header 'X-API-Key: <api-key>'

​
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 effecively 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.
OriginalEffective
created_at:desccreated_at:desc,id:asc
name:ascname:asc,id:asc
created_at:desc,id:asccreated_at:desc,id:asc
id:asc,created_at:descid:asc,created_at:desc
⌘I