---
title: "POST /2025-09-09/microvms"
method: POST
path: "/2025-09-09/microvms"
---

# POST /2025-09-09/microvms

`POST /2025-09-09/microvms`

Runs a new MicroVM from the specified image. The MicroVM starts in PENDING state and transitions to RUNNING once provisioning completes. To connect, generate an authentication token using CreateMicrovmAuthToken.

## Request body

- object
  - `ingressNetworkConnectors` NetworkConnector[] — The list of ingress network connectors to configure for the MicroVM.
  - `egressNetworkConnectors` NetworkConnector[] — The list of egress network connectors to configure for the MicroVM.
  - `imageIdentifier` string, required — The ARN or ID of the MicroVmImage
  - `imageVersion` string — The version of the MicroVM image to run.
  - `executionRoleArn` string — The ARN of an IAM role that the service assumes to perform actions on behalf of the caller.
  - `idlePolicy` object — Configuration that controls MicroVM auto-suspend and auto-resume behavior. Idle time is measured by inbound traffic through the MicroVM proxy endpoint — if no requests arrive within the configured duration, the MicroVM is suspended.
    - `maxIdleDurationSeconds` integer — The maximum time in seconds that a MicroVM can remain idle before it is automatically suspended.
    - `suspendedDurationSeconds` integer — The maximum time in seconds that a MicroVM can remain suspended before it is automatically terminated.
    - `autoResumeEnabled` boolean — Indicates whether the MicroVM automatically resumes when it receives a request while suspended.
  - `logging` object — Configuration for MicroVM logging output. Specify exactly one: cloudWatch to enable CloudWatch logging, or disabled to turn off logging.
    - `disabled` object — Specifies that logging is disabled.
    - `cloudWatch` object — Configuration for sending logs to Amazon CloudWatch Logs.
      - `logGroup` string — The name of the CloudWatch Logs log group to send logs to.
      - `logStream` string — The name of the CloudWatch Logs log stream within the log group.
  - `runHookPayload` string — Per-MicroVM initialization data delivered as the request body of the /run lifecycle hook. Use to pass tenant-specific configuration such as session IDs or secret references. Maximum: 16,384 bytes.
  - `maximumDurationInSeconds` integer — The maximum duration in seconds that the MicroVM can exist before being terminated by the platform. Valid range: 1–28,800 (8 hours).
  - `clientToken` string — A unique, case-sensitive identifier you provide to ensure the idempotency of the request.

## Response `200`

Success

- RunMicrovmResponse
  - `microvmId` string, required — The unique identifier of the MicroVM.
  - `state` 'PENDING' | 'RUNNING' | 'SUSPENDING' | 'SUSPENDED' | 'TERMINATING' | 'TERMINATED', required — The current lifecycle state of the MicroVM.
  - `endpoint` string, required — The HTTPS endpoint URL for communicating with the MicroVM. Include a valid authentication token in the X-aws-proxy-auth header when sending requests.
  - `imageArn` string, required — The ARN of the MicroVM image used to run this MicroVM.
  - `imageVersion` string, required — The version of the MicroVM image used to run this MicroVM.
  - `executionRoleArn` string — The ARN of the IAM execution role assumed by the MicroVM.
  - `idlePolicy` object — The idle policy configuration of the MicroVM.
    - `maxIdleDurationSeconds` integer, required — The maximum time in seconds that a MicroVM can remain idle before it is automatically suspended.
    - `suspendedDurationSeconds` integer, required — The maximum time in seconds that a MicroVM can remain suspended before it is automatically terminated.
    - `autoResumeEnabled` boolean, required — Indicates whether the MicroVM automatically resumes when it receives a request while suspended.
  - `maximumDurationInSeconds` integer, required — The maximum duration in seconds that the MicroVM can exist.
  - `startedAt` string, date-time, required — The timestamp when the MicroVM first started.
  - `terminatedAt` string, date-time — The timestamp when the MicroVM terminated.
  - `stateReason` string — The reason for why the MicroVM is in the current state.
  - `ingressNetworkConnectors` NetworkConnector[] — The list of ingress network connectors configured for the MicroVM.
  - `egressNetworkConnectors` NetworkConnector[] — The list of egress network connectors configured for the MicroVM.

## Other responses

- `480` — InternalServerException
- `481` — AccessDeniedException
- `482` — ResourceNotFoundException
- `483` — ThrottlingException
- `484` — ConflictException
- `485` — ValidationException
- `486` — ServiceQuotaExceededException

---

[API](https://skmtc.net/aws/apis/lambda-microvms.md) · [All operations](https://skmtc.net/aws/apis/lambda-microvms/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/lambda-microvms/versions/83f10af82eb8/schema)