Sign In to the Console
AWS Lambda
Developer Guide

AWS Documentation » AWS Lambda » Developer Guide » AWS Lambda Runtimes » AWS Lambda Runtime Interface

AWS Lambda Runtime Interface

AWS Lambda provides an HTTP API for custom runtimes to receive invocation events from Lambda and send response data back within the Lambda execution environment.

The OpenAPI specification for the runtime API version 2018-06-01 is available here: runtime-api.zip

Runtimes get an endpoint from the AWS_LAMBDA_RUNTIME_API environment variable, add the API version, and use the following resource paths to interact with the API.

Example Request

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

Next Invocation

Path – /runtime/invocation/next

Method – GET

Retrieves an invocation event. The response body contains the payload from the invocation, which is a JSON document that contains event data from the function trigger. The response headers contain additional data about the invocation.

Response Headers

  • Lambda-Runtime-Aws-Request-Id – The request ID, which identifies the request that triggered the function invocation.

    For example, 8476a536-e9f4-11e8-9739-2dfe598c3fcd.

  • Lambda-Runtime-Deadline-Ms – The date that the function times out in Unix time milliseconds.

    For example, 1542409706888.

  • Lambda-Runtime-Invoked-Function-Arn – The ARN of the Lambda function, version, or alias that's specified in the invocation.

    For example, arn:aws:lambda:us-east-2:123456789012:function:custom-runtime.

  • Lambda-Runtime-Trace-Id – The AWS X-Ray tracing header.

    For example, Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.

  • Lambda-Runtime-Client-Context – For invocations from the AWS Mobile SDK, data about the client application and device.

  • Lambda-Runtime-Cognito-Identity – For invocations from the AWS Mobile SDK, data about the Amazon Cognito identity provider.

The request ID tracks the invocation within Lambda. Use it to specify the invocation when you send the response.

The tracing header contains the trace ID, parent ID, and sampling decision. If the request is sampled, the request was sampled by Lambda or an upstream service. The runtime should set the _X_AMZN_TRACE_ID with the value of the header. The X-Ray SDK reads this to get the IDs and determine whether to trace the request.

Invocation Response

Path – /runtime/invocation/AwsRequestId/response

Method – POST

Sends an invocation response to Lambda. After the runtime invokes the function handler, it posts the response from the function to the invocation response path. For synchronous invocations, Lambda then sends the response back to the client.

Example Success Request

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl -X POST  "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "SUCCESS"

Invocation Error

Path – /runtime/invocation/AwsRequestId/error

Method – POST

If the function returns an error, the runtime formats the error into a JSON document, and posts it to the invocation error path.

Example Request Body

{
    "errorMessage" : "Error parsing event data.",
    "errorType" : "InvalidEventDataException"
}

Example Error Request

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" : \"InvalidEventDataException\"}"
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/error"  -d "$ERROR"

Initialization Error

Path – /runtime/init/error

Method – POST

If the runtime encounters an error during initialization, it posts an error message to the initialization error path.

Example Error Request

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
#ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" : \"InvalidFunctionException\"}"
#curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error"  -d "$ERROR"