API resources support bulk fetching through list endpoints. For example, you can list config instances in a workspace. At a minimum, all list endpoints accept the limit and offset query parameters. The Miru API paginates results to efficiently manage large datasets, returning a subset of items along with metadata to help you retrieve additional pages. Currently, the Miru API uses offset-based pagination, with support for cursor-based pagination coming soon.

​
Query Parameters

All list endpoints optionally accept the limit and offset query parameters.

​
Limit

limit specifies the maximum number of items which can be returned in a single request. The default is 10 while the maximum is 100.

​
Offset

offset specifies the starting position of the current page. The default is 0.

​
Example

A limit of 10 with an offset of 0 returns items 1-10. A limit of 15 with an offset of 10 returns the items 21-35. To specify the limit and offset, add the limit and offset query parameters to the list endpoint URL. The following request specifies a limit of 10 and an offset of 0 by appending ?limit=10&offset=0 to the list endpoint URL. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/config_instances?limit=10&offset=0' \
  --header 'X-API-Key: <api-key>'

​
List Response Format

Every list response follows the same structure. 
{
  "object": "list",
  "total_count": -1,
  "limit": 10,
  "offset": 0,
  "has_more": false,
  "data": [
    {
      "object": "config_instance",
      "id": "cfg_inst_123",
      ...
    },
    {
      "object": "config_instance",
      "id": "cfg_inst_456",
      ...
    },
    ...
  ]
}

​
Object

object is always a string with the value “list” to indicate that it is a list response. Total Count total_count is the total number of items matching the query. By default, the total count is not computed (and thus set to -1) to avoid the performance cost of counting all items. To get the total count, you must explicitly request it using the expand[]=total_count parameter. While useful, the total count is typically not needed and can incur significant performance costs, so please use judiciously. See the total_count expansion documentation for more information about retrieving the total count.

​
Limit

limit specifies the number of items returned in the response. If a valid value is provided (e.g., 10), the response will reflect that value. If an invalid value is provided (e.g., 1001), the closest valid value will be used instead (in this case, 100).

​
Offset

offset indicates the starting index of the returned items. If a valid value is provided (e.g., 5), the response will reflect that value. If an invalid value is provided (e.g., -3), the closest valid value will be used instead (0 in this case).

​
Has More

has_more is a boolean that indicates whether more items exist beyond the current page. If true, you can fetch the next page by increasing the offset by the limit.

​
Data

data is an array of the actual items returned by the query. The number of items in the array will be less than or equal to the specified limit.

​
Pagination Walkthrough

To paginate a request, continually request the next page until has_more is false. The next page uses the same limit but the offset is increased by the limit. First, let’s make a request with a limit of 10 and an offset of 0. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/config_instances?limit=10&offset=0' \
  --header 'X-API-Key: <api-key>'
The response will look like similar to the following: 
{
  "object": "list",
  "total_count": -1,
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "data": [
    {
      "object": "config_instance",
      "id": "cfg_inst_123",
      ...
    },
    {
      "object": "config_instance",
      "id": "cfg_inst_456",
      ...
    },
    ...
  ]
}
If has_more is false, there are no more items after the current page. If has_more is true, more items exist after the current page. The next pagination request uses the same limit but the offset is increased by the limit: offset = offset + limit. This gives us an offset of 10 and a limit of 10. Simply repeat this process until has_more is false. The next request would use an offset of 20 and a limit of 10, then 30 and 10, and so on.