Trace API Gateway Requests with X-Ray (2026)

AWS X-Ray now integrates with API Gateway, allowing you to trace requests as they flow through your API.

Here’s a quick look at what that means in practice. Imagine you have an API Gateway endpoint that triggers a Lambda function. Normally, if you wanted to see how long that request took, where it spent its time, and if any downstream services were slow, you’d be looking at CloudWatch Logs and Metrics, possibly with some custom instrumentation in your Lambda. With X-Ray, you get a visualized trace showing the entire journey of that request from the client, through API Gateway, to your Lambda, and any other AWS services it might interact with.

Let’s set up a simple example. We’ll create an API Gateway REST API that integrates with a Lambda function.

First, the Lambda function. This one just returns a simple JSON response.

import json

def lambda_handler(event, context):
    return {
        'statusCode': 200,
        'body': json.dumps('Hello from Lambda!')
    }

Now, let’s create an API Gateway REST API and a resource with a ANY method that integrates with this Lambda function.

The key to enabling X-Ray tracing is in the API Gateway configuration. You need to enable "Active tracing" for your API.

1. Go to the API Gateway console.
2. Select your API.
3. In the left-hand navigation pane, choose Settings.
4. Under the X-Ray tracing section, toggle Enable active tracing to On.

This single toggle tells API Gateway to start sending tracing information to X-Ray for every request that hits this API.

When a request comes in, API Gateway will:

• Generate a unique trace ID.
• Sample the request for tracing.
• If sampled, it will record a segment for itself, including latency and status code.
• It will then pass the trace ID and a parent segment ID to the integrated backend (our Lambda function in this case).

The Lambda function, if configured for X-Ray tracing, will then receive this information. When it executes, it will create its own segment, linked to the parent segment from API Gateway. If your Lambda function calls other AWS services (like DynamoDB or SQS), the AWS SDKs, when configured, will automatically generate subsegments for those calls.

To make sure your Lambda function also participates in the trace, you need to enable X-Ray tracing for it.

1. Go to the Lambda console.
2. Select your function.
3. Go to the Configuration tab.
4. Select Monitoring and operations tools.
5. Under AWS X-Ray tracing, choose Edit.
6. Select Enable active tracing.

This requires the Lambda function’s execution role to have the AWSXRayDaemonWriteAccess policy attached.

Once tracing is enabled on both API Gateway and Lambda, and a request is made, you’ll see a trace in the X-Ray console. This trace visually represents the journey of the request. You’ll see a node for API Gateway and a node for your Lambda function. Clicking on these nodes reveals detailed information: the duration of the API Gateway’s processing, the duration of the Lambda execution, any errors, and the HTTP status code.

If your Lambda function makes calls to other AWS services, like DynamoDB, you’ll see those as subsegments within the Lambda segment. For example, a dynamodb:GetItem call would appear as a distinct subsegment, showing its latency and whether it succeeded or failed. This is where the power of X-Ray truly shines – it stitches together distributed systems, making it easy to pinpoint bottlenecks.

The magic happens through a combination of headers and the X-Ray SDK. API Gateway injects X-Amzn-Trace-Id headers into the request it forwards to the backend. The X-Ray SDKs (available for Lambda, and within the AWS SDK for services) listen for these headers. If present, they use the provided trace ID to create a new segment that is a child of the incoming trace.

One thing that often trips people up is that X-Ray tracing is sampled by default. API Gateway and Lambda both have sampling rules. While enabling active tracing is the first step, you might not see every single request traced unless you adjust your sampling configuration. The default sampling rate is usually low (e.g., 1 request per second or 5% of requests). To see more traces, especially during development or debugging, you’ll want to go to the X-Ray console, navigate to Sampling in the left menu, and create or modify sampling rules to be more aggressive for your specific API Gateway API or Lambda function. For instance, you could set a fixed rate of 100% for a specific trace name or a higher percentage.

The next logical step after understanding request tracing is to dive into error analysis and how to use X-Ray annotations and metadata to add custom context to your traces.