The Miru API uses expansions to retrieve related objects in a single request rather than making multiple API calls. This simplifies code and minimizes the number of API calls.
Response objects only include the core fields by default. Related objects (such as the device associated with a deployment) are included with their IDs, but not their complete object data. Using the expand query parameter, you can include related objects directly in the response.
Expansions are powerful but add latency. As such, they should be used strategically to balance performance with the data needed in an individual request.
Object expansions
Many response objects reference objects that are not included in the default response.
For example, a deployment has the following default response structure:
{
"object": "deployment",
"id": "dpl_123",
"description": "Deployment for the motion control config instance",
"status": "staged",
"activity_status": "staged",
"error_status": "none",
"target_status": "staged",
"device_id": "dvc_123",
"release_id": "rls_123",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
device, release, and config_instances objects are not included in the deployment response by default.
To retrieve the device for a given deployment, you could make two separate requests:
- First, fetch the deployment using its ID (assuming you already know it).
- Then, having obtained the
device_id from the deployment response, fetch the device using the device ID.
This is workable but adds both latency and complexity to your code. A better approach is to use the expand parameter to include the device object directly in the deployment response, avoiding a second request.
The following request expands the device field using expand=device
curl --request GET \
--url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=device \
--header 'X-API-Key: <api-key>' \
--header 'Miru-Version: 2026-03-09.tetons'
device that the deployment targets, reducing the request count from two to one.
To see a complete list of expandable fields for an object, look for the expand parameter in the Query Parameters section of the API endpoint you are querying.
Multiple expansions
You can expand multiple fields by passing in multiple expand parameters separated by & .
The following request expands both the device and release fields of the deployment using expand=device&expand=release.
curl --request GET \
--url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=device&expand=release \
--header 'X-API-Key: <api-key>' \
--header 'Miru-Version: 2026-03-09.tetons'
Nested expansions
When expanding an object, it’s often the case that the expanded object contains objects that can also be expanded. For example, deployments can expand their release, which in turn can expand its config schemas.
To expand nested objects, use the dot (.) notation within the expand parameter.
The following request expands the config_schemas inside the release of the deployment using expand=release.config_schemas
curl --request GET \
--url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=release.config_schemas \
--header 'X-API-Key: <api-key>' \
--header 'Miru-Version: 2026-03-09.tetons'
Expansions cannot be nested beyond four levels deep. expand=field1.field2.field3.field4 is the maximum depth.
expand=release.config_schemas query parameter, the release field is automatically expanded as well.
List expansions
Items
When listing deployments, you can expand fields in the same way you would for a single deployment. By default, listing deployments returns the following response structure.
{
"object": "list",
"limit": 10,
"offset": 0,
"has_more": true,
"data": [
{
"object": "deployment",
"id": "dpl_123",
...
},
{
"object": "deployment",
"id": "dpl_456",
...
},
...
]
}
device field for every deployment in a list response, use expand=device, just as you would for a single object.
Unlike other APIs you may encounter, you don’t need to prefix the field with data. (e.g., expand=data.device). Miru automatically applies the expansion to each item in the list, not the list itself.
The following request expands the device field for every deployment in the list using expand=device
curl --request GET \
--url 'https://api.mirurobotics.com/beta/deployments?expand=device' \
--header 'X-API-Key: <api-key>' \
--header 'Miru-Version: 2026-03-09.tetons'
Total count
The total_count field in a list response represents the total number of items matching the query. Because Miru paginates list responses, this number is often greater than the number of items returned per page.
If a list query matches 100 items but the limit parameter is set to 10, the list response would contain only 10 items despite the total count being 100.
By default, Miru does not compute total_count to avoid performance overhead. Instead, the field is omitted from the response unless explicitly expanded.
To include the actual total count in the response, add expand=total_count to the request:
curl --request GET \
--url 'https://api.mirurobotics.com/beta/deployments?expand=total_count' \
--header 'X-API-Key: <api-key>' \
--header 'Miru-Version: 2026-03-09.tetons'
