aws ec2 describe-instances: Filters, Query & CI Errors

List and filter EC2 instances - and extract exactly the field you need.

aws ec2 describe-instances returns details about your EC2 instances. With --filters and --query you can narrow to specific instances and pull out just the IDs or IPs a pipeline needs.

What it does

The command returns reservations, each containing instances with their state, IP addresses, tags, and metadata. Because the response is deeply nested (Reservations[].Instances[]), you almost always pair it with --filters (server-side) and --query (client-side JMESPath) to get usable output.

Common usage

# Running instances with a given tag, as a flat list of IDs
aws ec2 describe-instances \
  --filters "Name=tag:Env,Values=prod" "Name=instance-state-name,Values=running" \
  --query "Reservations[].Instances[].InstanceId" --output text

# Get the public IP of one instance
aws ec2 describe-instances --instance-ids i-0abc123 \
  --query "Reservations[0].Instances[0].PublicIpAddress" --output text

Common error in CI: empty result from wrong filter vs region

A script gets empty output and assumes no instances, when really the --region is wrong (instances live elsewhere) or the filter key is mistyped - Name=tag:env (lowercase) will not match a Env tag, since tag keys are case-sensitive. Fix: confirm the region (set AWS_REGION or --region), use the exact tag key casing, and remember filter Values are case-sensitive too. Use --query against the real shape (Reservations[].Instances[]) - querying Instances[] at the top level returns nothing.

Key options

Related guides