# Stream the integration response for your proxy integrations in API Gateway You can configure your proxy integration to control how API Gateway returns your integration response. By default, API Gateway waits to receive the complete response before beginning transmission. However, if you set your integration's response transfer mode to `STREAM`, API Gateway doesn't wait for a response to be completely computed before sending it to the client. Response streaming works for all REST API endpoint types. Use response streaming for the following use cases: + Lower the time-to-first-byte (TTFB) for generative AI applications like chatbots. + Stream large image, video, or music files without using an S3 pre-signed URL. + Perform long-running operations while reporting incremental progress like server-sent events (SSE). + Exceed API Gateway's 10 MB response payload limit. + Exceed API Gateway's 29 second timeout limit without requesting an integration timeout limit increase. + Receive a binary payload without configuring the binary media types. ## Considerations for response payload streaming The following considerations might impact your use of response payload streaming: + You can only use response payload streaming for `HTTP_PROXY` or `AWS_PROXY` integration types. This includes Lambda proxy integrations and private integrations that use `HTTP_PROXY` integrations. + The default transfer mode setting is `BUFFERED`. To use response streaming you must change the response transfer mode to `STREAM`. + Response streaming is only supported for REST APIs. + Request streaming isn't supported. + You can stream your response for up to 15 minutes. + Your streams are subject to idle timeouts. For Regional or private endpoints, the timeout is 5 minutes. For edge-optimized endpoints, the timeout is 30 seconds. + If you use response streaming for a Regional REST API with your own CloudFront distribution, you can achieve an idle time out greater than 30 seconds by increasing the response timeout of your CloudFront distribution. For more information, see [Response timeout](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout). + When the response transfer mode is set to `STREAM`, API Gateway can’t support features that require buffering the entire integration response. Because of this, the following features aren't supported with response streaming: + Endpoint caching + Content encoding. If you want to compress your integration response, do this in your integration. + Response transformation with VTL + Within each streaming response, the first 10MB of response payload is not subject to any bandwidth restrictions. Response payload data exceeding 10MB is restricted to 2MB/s. + When the connection between the client and API Gateway or between API Gateway and Lambda is closed due to timeout, the Lambda function might continue to execute. For more information, see [Configure Lambda function timeout](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Response streaming incurs a cost. For more information, see [API Gateway Pricing](https://aws.amazon.com/api-gateway/pricing/). # Set up an HTTP proxy integration with payload response streaming in API Gateway When you set up response payload streaming, you specify the response transfer mode in the integration request of your method. You configure these settings in the integration request to control how API Gateway behaves before and during the integration response. When you use response streaming, you can configure the integration timeout up to 15 minutes. When you use payload response streaming with an `HTTP_PROXY` integration, API Gateway won't send the HTTP response status code or any HTTP response headers until it fully receives all headers. ## Create an HTTP proxy integration with payload response streaming The following procedure shows you how to import a new API with the `responseTransferMode` set to `STREAM`. If you have an existing integration API and want to modify the `responseTransferMode`, see [Update the response transfer mode for an HTTP proxy integration](#response-streaming-http-update). ------ #### [ AWS Management Console ] **To create an HTTP proxy integration with payload response streaming** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a REST API. 1. Choose **Create resource**. 1. For **Resource name**, enter **streaming**. 1. Choose **Create resource**. 1. With the **/streaming** resource selected, choose **Create method**. 1. For **Method type**, choose **ANY**. 1. For **Integration type**, choose **HTTP**. 1. Choose **HTTP proxy integration**. 1. For **Response transfer mode**, choose **Stream**. 1. For **HTTP method**, choose a method. 1. For **Endpoint URL**, enter an integration endpoint. Make sure that you choose an endpoint that produces a large payload to be streamed back to you. 1. Choose **Create method**. After you create your method, deploy your API. **To deploy your API** 1. Choose **Deploy API**. 1. For **Stage**, select **New stage**. 1. For **Stage name**, enter **prod**. 1. (Optional) For **Description**, enter a description. 1. Choose **Deploy**. ------ #### [ AWS CLI ] **To create a new API with payload response streaming** 1. Copy the following Open API file, and then save it as `ResponseStreamDemoSwagger.yaml`. In this file, `responseTransferMode` is set to `STREAM`. The integration endpoint is set to `https://example.com`, but we recommend that you modify it to an endpoint that produces a large payload to be streamed back to you. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /streaming: get: x-amazon-apigateway-integration: httpMethod: "GET" uri: "https://example.com" type: "http_proxy" timeoutInMillis: 900000 responseTransferMode: "STREAM" ``` 1. Use the following `import-rest-api` command to import your OpenAPI definition: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Use the following `create-deployment` command to deploy your new API to a stage: ``` aws apigateway create-deployment \ --rest-api-id a1b2c3 \ --stage-name prod \ --region us-west-1 ``` ------ ## Update the response transfer mode for an HTTP proxy integration The following procedure shows how to update the response transfer mode for an HTTP proxy integration. ------ #### [ AWS Management Console ] **To update the response transfer mode for an HTTP proxy integration** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a REST API. 1. Choose a method. 1. On the **Integration request** tab, under **Integration request settings**, choose **Edit**. 1. For **Response transfer mode**, choose **Stream**. 1. Choose **Save**. After you update your method, deploy your API. **To deploy your API** 1. Choose **Deploy API**. 1. For **Stage**, select **New stage**. 1. For **Stage name**, enter **prod**. 1. (Optional) For **Description**, enter a description. 1. Choose **Deploy**. ------ #### [ AWS CLI ] The following `update-integration` command updates the transfer mode of an integration from `BUFFERED` to `STREAM`. For any existing APIs, the response transfer mode for all integrations is set to `BUFFERED`. ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \ --region us-west-1 ``` You need to redeploy your API for the changes to take effect. If you customized the integration timeout, this timeout value is removed, as API Gateway streams your response for up to 5 minutes. The following `update-integration` command updates the transfer mode of an integration from `STREAM` to `BUFFERED`: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \ --region us-west-1 ``` You need to redeploy your API for the changes to take effect. ------ # Set up a Lambda proxy integration with payload response streaming in API Gateway You can stream the response of a Lambda function to improve time to first byte (TTFB) performance and send partial responses back to the client as they become available. API Gateway requires you to use the [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) Lambda API to invoke your Lambda function. API Gateway passes an event object to the Lambda function. The backend Lambda function parses the incoming request data to determine the response that it returns. In order for API Gateway to stream the Lambda output, the Lambda function must output the [format](#response-transfer-mode-lambda-format) required by API Gateway. ## Differences in Lambda proxy integrations between stream and buffered response transfer mode The following list describes the differences between a Lambda proxy integration and a Lambda proxy integration for response streaming: + API Gateway uses the [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API to invoke the Lambda proxy integration for response streaming. This results in a different URI, which is the following: ``` arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations ``` This ARN uses a different date for the API version and a different service action compared to Lambda proxy integration. If you use the API Gateway console for response streaming, the console uses the correct URI for you. + In a Lambda proxy integration, API Gateway sends the response to client only after it receives the full response from Lambda. In a Lambda proxy integration for response streaming, API Gateway begins the payload stream after it receives the valid metadata and delimiter from Lambda. + Lambda proxy integration for response streaming uses the same input format as the proxy integration, but it requires a different output format. ## Lambda proxy integration format for response streaming When API Gateway invokes a Lambda function with response streaming, the input format is the same as the input format of a Lambda function for proxy integration. For more information, see [Input format of a Lambda function for proxy integration](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). When Lambda streams a response to API Gateway, the response must adhere to the following format. This format uses a delimiter to separate the metadata JSON and the raw payload. In this case, the payload data is streamed as it is transmitted by your streaming Lambda function: ``` { "headers": {"headerName": "headerValue", ...}, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "cookies" : ["cookie1", "cookie2"], "statusCode": httpStatusCode }PAYLOAD1 | PAYLOAD2 | PAYLOAD3 ``` In the output: + The `headers`, `multiValueHeaders`, `cookies`, and `statusCode` keys can be unspecified if no extra response headers are to be returned. + The `headers` key can only contain single-value headers. + The output expects the headers to contain either `Transfer-Encoding: chunked` or `Content-length: number`. If your function doesn't return either of these headers, API Gateway appends `Transfer-Encoding: chunked` to the response header. + The `multiValueHeaders` key can contain multi-value headers as well as single-value headers. You can use the `multiValueHeaders` key to specify all of your extra headers, including any single-value ones. + If you specify values for both `headers` and `multiValueHeaders`, API Gateway merges them into a single list. If the same key-value pair is specified in both, only the values from `multiValueHeaders` will appear in the merged list. + The metadata must be valid JSON. Only `headers`, `multiValueHeaders`, `cookies` and the `statusCode` keys are supported. + You must provide a delimiter after the metadata JSON. The delimiter must be 8 null bytes and it must appear within the first 16KB of stream data. + API Gateway doesn't require a specific format for the method response payload. If you're using a function URL to stream your Lambda function, you must modify the input and the output of your Lambda function to satisfy these requirements. If your Lambda function output doesn't adhere to the requirements of this format, API Gateway might still invoke your Lambda function. The following table shows the combinations of API integration request settings and Lambda function code that is supported by API Gateway. This includes supported combinations for response transfer mode of buffered. | Response transfer mode | Function code adheres to the required format | Lambda invoke API | Supported by API Gateway | | --- | --- | --- | --- | | Stream | Yes | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Yes. API Gateway streams your response. | | Stream | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway invokes your Lambda function and return a 500 error response. | | Stream | Yes | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway doesn't support this integration configuration. | | Stream | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway doesn't support this integration configuration. | | Buffered | Yes | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway doesn't support this integration configuration. | | Buffered | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway doesn't support this integration configuration. | | Buffered | Yes | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway returns the HTTP headers and status code but not the response body. | | Buffered | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Yes. This is a Lambda proxy integration. For more information, see [Lambda proxy integration](set-up-lambda-proxy-integrations.md). | # Configure a Lambda proxy integration with payload response streaming in API Gateway When you set up response payload streaming, you specify the transfer mode in the integration request of your resource. You configure these settings in the integration request to control how API Gateway behaves before and during the integration response. ## Example Lambda functions for response streaming Your Lambda function must adhere to the [Lambda proxy integration format for response streaming](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format). We recommend you use one of the three example Lambda functions to test out response streaming. When you create your Lambda function, make sure to do the following: + Provide an adequate timeout for your function. We recommend you configure a timeout of at least 1 minute to learn about response streaming. When you create your production resources, make sure your Lambda function timeout covers the full request cycle. For more information, see [Configure Lambda function timeout](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Use the latest Node.js runtime. + Use a Region where Lambda response streaming is available. ------ #### [ Using HttpResponseStream.from ] The following code example streams the JSON metadata objects and payloads back to the client using the `awslambda.HttpResponseStream()` method without using the pipeline method. You don't need to create the delimiter. For more information, see [Writing response streaming-enabled Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). ``` export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { "statusCode": 200, "headers": { "x-foo": "bar" }, "multiValueHeaders": { "x-mv1": ["hello", "world"], "Set-Cookie": ["c1=blue", "c2=red"] } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("First payload "); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("Final payload"); responseStream.end(); }); ``` ------ #### [ Using the pipeline method ] Lambda recommends that when you write response streaming-enabled functions, you use the `awslambda.streamifyResponse()` decorator that the native Node.js runtimes provide, and the `pipeline()` method. When you use the pipeline method, you don't need to create the delimiter, Lambda does this for you. For more information, see [Writing response streaming-enabled Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). The following code example streams the JSON metadata objects and three payloads back to the client. ``` import { pipeline } from 'node:stream/promises'; import { Readable } from 'node:stream'; export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { statusCode: 200, headers: { "Content-Type": "text/plain", "X-Custom-Header": "Example-Custom-Header" } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); const dataStream = Readable.from(async function* () { yield "FIRST payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "SECOND payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "THIRD payload\n"; await new Promise(r => setTimeout(r, 1000)); }()); await pipeline(dataStream, responseStream); } ); ``` ------ #### [ Without using the pipeline method ] The following code example streams the JSON metadata objects and three payloads back to the client without using the `awslambda.HttpResponseStream()` method. Without the `awslambda.HttpResponseStream()` method, you must include a delimiter of 8 null bytes between the metadata and the payload. ``` export const handler = awslambda.streamifyResponse(async (event, response, ctx) => { response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}'); response.write("\x00".repeat(8)); // DELIMITER await new Promise(r => setTimeout(r, 1000)); response.write("FIRST payload"); await new Promise(r => setTimeout(r, 1000)); response.write("SECOND payload"); await new Promise(r => setTimeout(r, 1000)); response.write("FINAL payload"); response.end(); }); ``` ------ ## Create a Lambda proxy integration with payload response streaming The following procedure shows how to create a Lambda proxy integration with payload response streaming. Use the example Lambda function or create your own. ------ #### [ AWS Management Console ] **To create a Lambda proxy integration with payload response streaming** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a REST API. 1. Choose **Create resource**. 1. For **Resource name**, enter **streaming**. 1. Choose **Create resource**. 1. With the **/streaming** resource selected, choose **Create method**. 1. For **Method type**, choose **ANY**. 1. For **Integration type**, choose **Lambda**. 1. Choose **Lambda proxy integration**. 1. For **Response transfer mode**, choose **Stream**. 1. For **Lambda function**, choose the name of your Lambda function. The API Gateway console automatically uses [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) API to invoke the Lambda function. You are responsible for writing a response streaming-enabled Lambda function. For an example, see [Example Lambda functions for response streaming](#response-streaming-lambda-example). 1. Choose **Create method**. After you create your method, deploy your API. **To deploy your API** 1. Choose **Deploy API**. 1. For **Stage**, select **New stage**. 1. For **Stage name**, enter **prod**. 1. (Optional) For **Description**, enter a description. 1. Choose **Deploy**. ------ #### [ AWS CLI ] The following procedure shows you how to import a new API with the `responseTransferMode` set to `STREAM`. If you have an existing integration API and want to modify the `responseTransferMode`, see [Update the response transfer mode for a Lambda proxy integration](#response-streaming-lambda-update). **To create a new API with payload response streaming** 1. Copy the following Open API file, and then save it as `ResponseStreamDemoSwagger.yaml`. In this file, `responseTransferMode` is set to `STREAM`, and the integration URI is set to `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`. Replace the function name from `my-function` with a streaming-enabled function and replace the credentials with an IAM role that has policies allowing the `apigateway` service to invoke Lambda functions. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /lambda: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations" type: "aws_proxy" timeoutInMillis: 90000 responseTransferMode: "STREAM" credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role" ``` Instead of supplying an IAM role for credentials, you can use the `add-permission` command for Lambda to add resource-based permissions. 1. Use the following `import-rest-api` command to import your OpenAPI definition: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Use the following `create-deployment` command to deploy your new API to a stage: ``` aws apigateway create-deployment \ --rest-api-id a1b2c2 \ --stage-name prod \ --region us-west-1 ``` ------ ### Update the response transfer mode for a Lambda proxy integration The following procedure shows how to update the response transfer mode for a Lambda proxy integration. When you change the response transfer mode to streaming, update your Lambda function so it adheres to the requirements for response streaming. Use the example Lambda function or create your own. ------ #### [ AWS Management Console ] **To update the response transfer mode for a Lambda proxy integration** 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose a REST API. 1. Choose a method. 1. On the **Integration request** tab, under **Integration request settings**, choose **Edit**. 1. For **Response transfer mode**, choose **Stream**. 1. For **Lambda function**, choose the name of your Lambda function. 1. Choose **Save**. After you update your method, deploy your API. **To deploy your API** 1. Choose **Deploy API**. 1. For **Stage**, select **New stage**. 1. For **Stage name**, enter **prod**. 1. (Optional) For **Description**, enter a description. 1. Choose **Deploy**. ------ #### [ AWS CLI ] 1. Update your Lambda function to be streaming-enabled. 1. Use the following AWS CLI command to update the integration URI and response transfer mode of your integration: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method ANY \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \ --region us-west-1 ``` 1. Redeploy your API for the changes to take effect. ------ # Troubleshoot issues with response streaming in API Gateway The following troubleshooting guidance might help resolve issues with your APIs that use response streaming. ## General troubleshooting You can use the [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) or the console's test tab to test your stream response. The following considerations might impact your use of test invoke for response streaming: + When you test your method, API Gateway buffers your streamed response payload. Once any of the following conditions have been met, API Gateway returns a one-time response containing the buffered payload: + The request is complete + 35 seconds have elapsed + More than 1 MB of response payload has been buffered + If more than 35 seconds elapse before your method returns an HTTP response status and all headers, then the response status returned in TestInvokeMethod is 0. + API Gateway doesn't produce any execution logs. After you've deployed your API, you can test your stream response by using a curl command. We recommend that you use the `-i` option to include protocol response headers in the output. To see the response data as it arrives, use the curl option `--no-buffer` ## Troubleshoot cURL errors If you're testing an integration and you receive the error `curl: (18) transfer closed with outstanding read data remaining`, make sure the timeout of your integration is long enough. If you're using a Lambda function, you need to update the response timeout of the Lambda function. For more information, see [Configure Lambda function timeout](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). ## Troubleshoot using access logging You can use access logs for your REST API stage to log and troubleshoot your response stream. In addition to the existing variables, you can use the following access log variables: `$context.integration.responseTransferMode` The response transfer mode of your integration. This can be either `BUFFERED` or `STREAMED`. `$context.integration.timeToAllHeaders` The time between when API Gateway establishes the integration connection to when it receives all integration response headers from the client. `$context.integration.timeToFirstContent` The time between when API Gateway establishes the integration connection to when it receives the first content bytes. `$context.integration.latency` or `$context.integrationLatency` The time when API Gateway establishes the integration connection to when the integration response stream is complete. The following figure shows how these access log variables represent different components of a response stream. ![\[Access log variables for response streaming in API Gateway\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/response-streaming-figure.png) For more information about access logs, see [Set up CloudWatch logging for REST APIs in API Gateway](set-up-logging.md). You can also use X-Ray to monitor your response stream. For more information, see [Trace user requests to REST APIs using X-Ray in API Gateway](apigateway-xray.md).