Using the Lambda metadata endpoint

The Lambda metadata endpoint lets your functions discover which Availability Zone (AZ) they are running in, enabling you to optimize latency by routing to same-AZ resources like Amazon ElastiCache and Amazon RDS endpoints, and to implement AZ-aware resilience patterns.

The endpoint returns metadata in a simple JSON format through a localhost HTTP API within the execution environment and is accessible to both runtimes and extensions.

Getting started

Powertools for AWS Lambda provides a utility for accessing the Lambda metadata endpoint in Python, TypeScript, Java, and .NET. The utility caches the response after the first call and handles SnapStart cache invalidation automatically.

Use the Powertools for AWS Lambda metadata utility or call the metadata endpoint directly

Python

Install the Powertools package:

pip install "aws-lambda-powertools"

Use the metadata utility in your handler:

Example Retrieving AZ ID with Powertools (Python)

from aws_lambda_powertools.utilities.lambda_metadata import get_lambda_metadata

def handler(event, context):
    metadata = get_lambda_metadata()
    az_id = metadata.availability_zone_id  # e.g., "use1-az1"

    return {"az_id": az_id}

TypeScript

Install the Powertools package:

npm install @aws-lambda-powertools/commons

Use the metadata utility in your handler:

Example Retrieving AZ ID with Powertools (TypeScript)

import { getMetadata } from '@aws-lambda-powertools/commons/utils/metadata';

const metadata = await getMetadata();

export const handler = async () => {
  const { AvailabilityZoneID: azId } = metadata;
  return azId;
};

Java

Add the Powertools dependency to your pom.xml:

<dependencies>
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-lambda-metadata</artifactId>
        <version>2.10.0</version>
    </dependency>
</dependencies>

Use the metadata client in your handler:

Example Retrieving AZ ID with Powertools (Java)

import software.amazon.lambda.powertools.metadata.LambdaMetadata;
import software.amazon.lambda.powertools.metadata.LambdaMetadataClient;

public class App implements RequestHandler<Object, String> {

    @Override
    public String handleRequest(Object input, Context context) {
        LambdaMetadata metadata = LambdaMetadataClient.get();
        String azId = metadata.getAvailabilityZoneId(); // e.g., "use1-az1"

        return "{\"azId\": \"" + azId + "\"}";
    }
}

.NET

Install the Powertools package:

dotnet add package AWS.Lambda.Powertools.Metadata

Use the metadata class in your handler:

Example Retrieving AZ ID with Powertools (.NET)

using AWS.Lambda.Powertools.Metadata;

public class Function
{
    public string Handler(object input, ILambdaContext context)
    {
        var azId = LambdaMetadata.AvailabilityZoneId;
        return $"Running in AZ: {azId}";
    }
}

All Runtimes

All Lambda runtimes support the metadata endpoint, including custom runtimes and container images. Use the following example to access the metadata API directly from your function using the environment variables that Lambda automatically sets in the execution environment.

Example Accessing the metadata endpoint directly

# Variables are automatically set by Lambda
METADATA_ENDPOINT="http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment"

# Make the request
RESPONSE=$(curl -s -H "Authorization: Bearer ${AWS_LAMBDA_METADATA_TOKEN}" "$METADATA_ENDPOINT")

# Parse the AZ ID
AZ_ID=$(echo "$RESPONSE" | jq -r '.AvailabilityZoneID')

echo "Function is running in AZ ID: $AZ_ID"

Understanding Availability Zone IDs

AZ IDs (for example, use1-az1) always refer to the same physical location across all AWS accounts, while AZ names (for example, us-east-1a) may map to different physical infrastructure in each AWS account in certain regions. For more information, see AZ IDs for cross-account consistency.

Converting AZ ID to AZ name:

To convert an AZ ID to an AZ name, use the Amazon EC2 DescribeAvailabilityZones API. To use this API, add the ec2:DescribeAvailabilityZones permission to your function's execution role.

API reference

Environment variables

Lambda automatically sets the following environment variables in every execution environment:

• AWS_LAMBDA_METADATA_API – The metadata server address in the format {ipv4_address}:{port} (for example, 169.254.100.1:9001).

• AWS_LAMBDA_METADATA_TOKEN – A unique authentication token for the current execution environment. Lambda generates this token automatically at initialization. Include it in all metadata API requests.

Endpoint

GET http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment

Request

Required headers:

• Authorization – The token value from the AWS_LAMBDA_METADATA_TOKEN environment variable with the Bearer scheme: Bearer <token>. This token-based authentication provides defense in depth protection against Server-Side Request Forgery (SSRF) vulnerabilities. Each execution environment receives a unique, randomly generated token at initialization.

Response

Status: 200 OK

Content-Type: application/json

Cache-Control: private, max-age=43200, immutable

The response is immutable within an execution environment. Clients should cache the response and respect the Cache-Control TTL. For SnapStart functions, the TTL is reduced during initialization so that clients refresh metadata after restore when the execution environment may be in a different AZ. If you use Powertools, caching and SnapStart invalidation are handled automatically.

Body:

{
  "AvailabilityZoneID": "use1-az1"
}

The AvailabilityZoneID field contains the unique identifier for the Availability Zone where the execution environment is running.

Note

Additional fields may be added to the response in future updates. Clients should ignore unknown fields and not fail if new fields appear.

Error responses

• 401 Unauthorized – The Authorization header is missing or contains an invalid token. Verify you are passing Bearer ${AWS_LAMBDA_METADATA_TOKEN}.

• 405 Method Not Allowed – Request method is not GET.

• 500 Internal Server Error – Server-side processing error.