DescribeInstances

Lists your instances, or inspects specific ones by id.

Paginated. Read every page: a client that takes the first page and stops sees a partial answer with no error.

Request

Parameter	Type	Constraints
`InstanceId.N`	list	`i-` followed by 8 or 17 hex characters. Anything else: `InvalidInstanceID.Malformed`
`Filter.N`	list	See below. Cannot be combined with `InstanceId.N` in a way that contradicts it
`MaxResults`	integer	5–1000. Cannot be combined with `InstanceId.N`
`NextToken`	string	Opaque, from a previous response. Cannot be combined with `InstanceId.N`
`DryRun`	boolean

Omitting MaxResults gives up to 1000 instances per page, with a nextToken when there are more.

Filters

Filters AND together; the values within one filter OR together. Names and values are case-sensitive. Values may contain the wildcards * and ?.

Supported:

Filter	Matches
`instance-id`
`instance-type`	Our name
`instance-state-name`	`pending`, `running`, `stopping`, `stopped`, `shutting-down`, `terminated`
`instance-state-code`
`image-id`
`key-name`
`availability-zone`
`launch-time`	Wildcards allowed
`private-ip-address`
`ip-address`	The public address
`subnet-id`, `vpc-id`
`reservation-id`
`launch-index`
`client-token`
`root-device-name`, `root-device-type`
`architecture`
`security-group-id`, `security-group-name`
`block-device-mapping.*`	Attached volumes
`network-interface.*`	The instance’s interface
`tag:<key>`, `tag-key`

[!primary]

An unsupported filter is an error, not an empty result. Filters naming things this platform never reports — placement groups, IAM instance profiles, metadata options, spot fields, dedicated hosts and the rest — return InvalidParameterValue naming the filter.

Matching nothing silently would be worse: your script would report zero matches and carry on confidently with a wrong answer.

Response

Instances are grouped into reservations, exactly as on AWS — one reservation per RunInstances call.

Element	Notes
`reservationId`	`r-…`
`instanceId`	`i-…`
`imageId`, `instanceType`, `keyName`	`instanceType` is our name
`instanceState`	`name` and `code`
`privateIpAddress`	On your own subnet
`ipAddress`	Public address, when one is associated
`launchTime`
`placement.availabilityZone`
`amiLaunchIndex`	Position within its reservation
`architecture`, `rootDeviceName`, `rootDeviceType`
`blockDeviceMapping`	Attached volumes and their attach state
`groupSet`	Security groups
`networkInterfaceSet`	The interface, its address and its subnet
`tagSet`
`clientToken`	If one was sent at launch
`stateReason`, `reason`	Why it reached its current state
`monitoring`	Always `disabled` — there is no monitoring service

Elements this platform does not have are omitted, never invented. Every SDK treats an absent member as null, so nothing breaks; a fabricated value would.

Instance states

State	Meaning
`pending`	Launching
`running`	Booted. Not necessarily configured
`stopping` / `stopped`	Off. Root disk and private address retained, storage still occupied
`shutting-down`	Terminating
`terminated`	Gone. Root disk destroyed

A terminated instance remains visible for a short window after termination, then disappears. That window is what lets a terraform destroy observe the terminal state it waits for instead of failing on a not-found.

Ordering and pagination

Reservations come back oldest first, by the creation time of their first instance; instances within a reservation by launch index. That is a stricter guarantee than AWS makes, which says order may vary — so code written against AWS is safe here.

A reservation can span a page boundary and appear as a partial entry on each side. Join on reservationId if that matters to you.

An empty page can still carry a nextToken, because filters are applied after a page is assembled. Stop when the token is absent, not when a page is empty.

Errors

Code	Status	Cause
`InvalidInstanceID.Malformed`	400	The id is not the right shape
`InvalidInstanceID.NotFound`	400	No such instance — or it is another account’s, which is byte-identical
`InvalidParameterValue`	400	An unsupported filter, or `MaxResults` out of range
`InvalidParameterCombination`	400	`MaxResults` or `NextToken` with `InstanceId.N`
`InvalidPaginationToken`	400	Expired, invalid, or issued for different filters

A pagination token is tied to the filters and page size it was issued for. Changing either mid-iteration invalidates it.

Examples

alias sc='aws --endpoint-url https://ec2.shelfcs.com --region hel1'

sc ec2 describe-instances \
  --query 'Reservations[].Instances[].[InstanceId,InstanceType,State.Name,PrivateIpAddress]' \
  --output table

sc ec2 describe-instances --filters Name=tag:Name,Values=web Name=instance-state-name,Values=running

for page in ec2.get_paginator("describe_instances").paginate(
    Filters=[{"Name": "instance-state-name", "Values": ["running"]}]
):
    for r in page["Reservations"]:
        for i in r["Instances"]:
            print(i["InstanceId"], i["InstanceType"])

data "aws_instances" "running" {
  instance_state_names = ["running"]
}