expand[]
query parameter, you can include related objects directly in the response.
Expansions are powerful but add some latency. As such, they should be used strategically to balance performance with the data needed in an individual request.
device
, config_schema
, config_type
, and content
objects are not included in the config instance response by default.
To retrieve the device for a given config instance, you could make two separate requests:
device_id
from the config instance response, fetch the device using the device ID.expand[]
parameter to include the device
object directly in the config instance response, avoiding a second request.
The following request expands the device
field using expand[]=device
:
device
that the config instance belongs to, reducing the request count from two to one.
To see a full list of expandable fields for an object, look for the expand[]
parameter in the Query Parameters section of the API endpoint you are querying.
expand[]
parameters separated by &
.
The following request expands both the device
and content
fields of the config instance using expand[]=device&expand[]=content
.
.
) notation within the expand[]
parameter.
The following request expands the config_type
inside the config_schema
of the config instance using expand[]=config_schema.config_type
:
expand[]=field1.field2.field3.field4
is the maximum depth.expand[]=config_schema.config_type
query parameter, the config_schema
field is automatically expanded as well.
content
field for every config instance in a list response, use the expand[]=content
, 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.content
). Miru automatically applies the expansion to each item in the list, not the list itself.
The following request expands the content
field for every config instance in the list using expand[]=content:
:
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 actually returned in a single 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 set to -1
unless explicitly expanded.
To include the actual total count in the response, add expand[]=total_count
to the request: