Give Feedback

pydo.microvms.list()

Generated on 16 Oct 2026 from pydo version v0.44.0

Copy page as Markdown View page as Markdown

Usage

client.microvms.list(
    page=1,
    per_page=25,
    region=None,
    name=None,
    tag_name=None,
)

Returns JSON Raises HttpResponseError

Description

To list all of the MicroVMs on your team, send a GET request to /v2/microvms.

The region, name, and tag_name filters combine with AND.

Parameters

page integer optional

Which 'page' of paginated results to return.

Min: 1

Default: 1

per_page integer optional

Number of items returned per page.

Min: 1

Max: 200

Default: 25

region string optional

Only return MicroVMs in this region.

name string optional

Only return the MicroVM with this exact name.

tag_name string optional

Only return MicroVMs with this tag. A tag that matches no MicroVMs returns an empty list.

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.microvms.list()
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.microvms.list(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

Show Response Example

{
  "microvms": [
    {
      "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
      "name": "example-microvm",
      "region": "mkc1",
      "size": {
        "cpu": 1,
        "memory": 2048,
        "disk": 50
      },
      "source": {
        "oci_ref": "docker.io/library/nginx:latest"
      },
      "state": "paused",
      "networking": "public",
      "auto_pause": {
        "enabled": true,
        "idle_timeout": "5m0s"
      },
      "auto_resume": true,
      "http_protocol": "http",
      "ports": [
        80
      ],
      "tags": [
        "example"
      ],
      "urls": [
        {
          "hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
          "port": 80,
          "default": true,
          "status": "ACTIVE"
        }
      ],
      "created_at": "2026-09-29T21:38:29Z"
    }
  ],
  "links": {
    "pages": {
      "last": "/v2/microvms?page=4&per_page=1",
      "next": "/v2/microvms?page=2&per_page=1"
    }
  },
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 4
  }
}

More Information

See /v2/microvms in the API reference for additional detail on responses, headers, parameters, and more.