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

# Pagination

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

API resources support bulk fetching through list endpoints. For example, you can <PlatformApiLink endpoint="config-instances/list"><strong>list config instances</strong></PlatformApiLink> 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](https://www.merge.dev/blog/offset-pagination), with support for [cursor-based pagination](https://www.merge.dev/blog/cursor-pagination) coming soon.

## Query parameters

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

### Limit

`limit` specifies the maximum number of items that 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 items 11-25.

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.

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/config_instances?limit=10&offset=0' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```

## List response format

Every list response follows the same structure.

```json theme={null}
{
  "object": "list",
  "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 is omitted from the response 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 it judiciously. See the `total_count` [expansion](/developers/platform-api/query-params/expansions#total-count) 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 request with a limit of 10 and an offset of 0.

```bash theme={null}
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/config_instances?limit=10&offset=0' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-05-06.rainier'
```

The response will look similar to the following:

```json theme={null}
{
  "object": "list",
  "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 beyond the current page. The subsequent 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. Repeat this process until `has_more` is `false`. The following request would use an offset of 20 and a limit of 10, then 30 and 10, and so on.