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

# Expansions

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>;
};

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 <PlatformApiLink endpoint="deployments/get">deployment</PlatformApiLink> has the following default response structure:

```json theme={null}
{
  "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"
}
```

The `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 <PlatformApiLink endpoint="deployments/get"><strong>deployment</strong></PlatformApiLink> using its ID (assuming you already know it).
* Then, having obtained the **`device_id`** from the deployment response, fetch the <PlatformApiLink endpoint="devices/get"><strong>device</strong></PlatformApiLink> 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`**

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

  ```json Response theme={null}
  {
    "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": {
      "object": "device",
      "id": "dvc_123",
      "name": "My Device",
      "status": "online",
      "agent_version": "v1.0.0",
      "last_connected_at": "2021-01-01T00:00:00Z",
      "last_disconnected_at": null,
      "created_at": "2021-01-01T00:00:00Z",
      "updated_at": "2021-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

With the expansion, the response includes the `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`**.

<CodeGroup>
  ```bash Request theme={null}
  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-05-06.rainier'
  ```

  ```json Response theme={null}
  {
    "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": {
      "object": "device",
      "id": "dvc_123",
      "name": "My Device",
      "status": "online",
      "agent_version": "v1.0.0",
      "last_connected_at": "2021-01-01T00:00:00Z",
      "last_disconnected_at": null,
      "created_at": "2021-01-01T00:00:00Z",
      "updated_at": "2021-01-01T00:00:00Z"
    },
    "release": {
      "object": "release",
      "id": "rls_123",
      "version": "v1.0.0",
      "git_commit_id": "git_commit_123",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## 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`**

<CodeGroup>
  ```bash Request theme={null}
  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-05-06.rainier'
  ```

  ```json Response theme={null}
  {
    "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",
    "release": {
      "object": "release",
      "id": "rls_123",
      "version": "v1.0.0",
      "git_commit_id": "git_commit_123",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "config_schemas": [
        {
          "object": "config_schema",
          "id": "cfg_sch_123",
          "digest": "sha256:1234567890",
          "config_type_name": "Motion Control",
          "instance_filepath": "/srv/miru/configs/v1/motion-control.json",
          "created_at": "2021-01-01T00:00:00Z",
          "updated_at": "2021-01-01T00:00:00Z",
          "config_type_id": "cfg_typ_123",
          "language": "jsonschema",
          "format": "json"
        }
      ]
    }
  }
  ```
</CodeGroup>

<Warning>
  Expansions cannot be nested beyond four levels deep. `expand=field1.field2.field3.field4` is the maximum depth.
</Warning>

When expanding nested fields, there's no need to expand the parent field. Since the release must be expanded to expand its config schemas in the `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, <PlatformApiLink endpoint="deployments/list">listing deployments</PlatformApiLink> returns the following response structure.

```json theme={null}
{
  "object": "list",
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "data": [
    {
      "object": "deployment",
      "id": "dpl_123",
      ...
    },
    {
      "object": "deployment",
      "id": "dpl_456",
      ...
    },
    ...
  ]
}
```

To expand the `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`**

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

  ```json Response theme={null}
  {
    "object": "list",
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "data": [
      {
        "object": "deployment",
        "id": "dpl_123",
        ...
        "device": {
          "object": "device",
          "id": "dvc_123",
          "name": "Robot A",
          ...
        }
      },
      {
        "object": "deployment",
        "id": "dpl_456",
        ...
        "device": {
          "object": "device",
          "id": "dvc_456",
          "name": "Robot B",
          ...
        }
      },
      ...
    ]
  }
  ```
</CodeGroup>

### Total count

The `total_count` field in a list response represents the total number of items matching the query. Because Miru [paginates](/developers/platform-api/query-params/pagination) 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:

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

  ```json Response theme={null}
  {
    "object": "list",
    "total_count": 15,
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "data": [
      {
        "object": "deployment",
        "id": "dpl_123",
        ...
      },
      {
        "object": "deployment",
        "id": "dpl_456",
        ...
      },
      ...
    ]
  }
  ```
</CodeGroup>

Computing the total count can add significant latency, especially for large datasets. Only use it when necessary!