• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. CLI Reference
  2. Invoke

serverless invoke

serverless invoke calls a deployed AWS Lambda function with the event you pass and prints its response. The function runs in AWS with its deployed code and IAM role, so use serverless invoke to test a stage after serverless deploy; to run the code on your machine without deploying, use serverless invoke local, and to route a stage's real events to your working copy, use serverless dev. The same command also invokes AgentCore Runtime agents, sandboxes and web apps.

serverless invoke --function hello --data '{"name":"Ada"}'

The command prints the function's response on standard output, formatted as JSON:

{
    "statusCode": 200,
    "body": "Hello, Ada"
}

Options

serverless invoke --function accepts these options:

OptionAliasValueDefaultRequiredDescription
--function-fstringYesFunction to invoke, as named under functions in serverless.yml. One of --function, --agent, --sandbox or --web-app is required.
--data-dstringStandard inputNoEvent to send. JSON is parsed into an object unless --raw is set.
--path-pfile pathNoJSON or YAML file holding the event, relative to the service directory. Ignored when --data is set.
--rawbooleanfalseNoSend --data and --context as strings even when they are valid JSON.
--contextstringNoClient context to send with the invocation.
--contextPathfile pathNoJSON or YAML file holding the client context. Ignored when --context is set.
--type-tRequestResponse, Event or DryRunRequestResponseNoInvocation type. See Invocation types and logs.
--log-lbooleanfalseNoWith RequestResponse, also print the last 4 KB of the invocation's log.
--qualifier-qversion number or alias nameThe deploy's alias for a durable function, otherwise none ($LATEST)NoVersion or alias to invoke.
--tenant-idstringNoTenant ID for a function with tenant isolation.
--durable-execution-name1 to 64 characters: letters, digits, -, _NoName of a durable execution; makes the invocation idempotent. See Durable functions.
--jsonbooleanfalseNoPrint one JSON object on standard output and every message on standard error.
--stage-sstringprovider.stage, else devNoStage of the deployed function.
--region-rstringprovider.region, else us-east-1NoAWS Region of the deployed function.
--aws-profilestringprovider.profileNoAWS profile whose credentials the command uses.
--config-cfile pathserverless.ymlNoService configuration file to use.

The command also accepts the options every command takes: --param="key=value" (repeatable), --org, --app, --verbose, --debug and --help (-h). --header is not available with --function; the options for agents, sandboxes and web apps are in their own sections.

Event data and client context

serverless invoke takes the event from the first of these that is set:

  1. --data.
  2. --path: a .json or .yml/.yaml file is parsed; any other file is read as text.
  3. Standard input, when standard input is not a terminal.

Unless --raw is set, text that is valid JSON is parsed and sent as a JSON value, and other text is sent as a JSON string. The value parsed from a .json, .yml or .yaml file goes through that step again: a string that is valid JSON, or an array with one element whose text is valid JSON, is replaced by that JSON value. A .json file containing [1] sends 1, while --data '[1]' sends [1]. A parsed value of false, 0, null or "" is sent as {}. Without any of the three, the function receives {}.

The client context works the same way: --context takes precedence over --contextPath, and the Framework sends the value base64-encoded in the request's client context.

To test a function behind an http or httpApi event, pass an event in the API Gateway Lambda proxy input format, for example in lib/data.json:

{
  "resource": "/",
  "path": "/",
  "httpMethod": "GET"
}

Invocation types and logs

The serverless invoke --type option sets the Lambda invocation type:

  • RequestResponse (default): waits for the function to finish and prints its response.
  • Event: queues the event for asynchronous processing and returns without the function's response.
  • DryRun: checks the parameters and your permission to invoke the function, without running it.

With RequestResponse, --log prints the last 4 KB of the invocation's log after the response, with the START line first and the REPORT line last. The Lambda Invoke API reference describes the types and the log tail.

With --json, standard output holds only one JSON object, on one line, with these keys in this order; a value the response does not carry is null:

KeyValue
statusCodeHTTP status code of the Invoke call: 200 for RequestResponse, 202 for Event.
qualifierVersion or alias the command invoked.
executedVersionVersion that ran.
durableExecutionArnARN of the durable execution, for a durable function.
functionErrorLambda's function error type, such as Unhandled.
payloadThe response, parsed as JSON, or its text when it is not JSON.
logThe decoded log tail, with --log.

Durable functions

serverless invoke sends a durable function's invocation to the alias its deploy publishes, so it needs no --qualifier. The alias is durable, or the SnapStart or provisioned-concurrency alias when the function uses one. With --type Event the command starts an execution and prints its ARN on standard error:

$ serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042

Durable execution started: arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92

A synchronous invoke (the default RequestResponse type) waits for the execution to finish, prints Durable execution: <arn> on standard error, and prints the result on standard output. Lambda runs a durable function synchronously only when its durableConfig.executionTimeout is 900 seconds or less; for a longer timeout, the command stops with an error that suggests --type Event.

Add --json to read the ARN and the result from one JSON object on standard output (printed on one line; formatted here for reading):

serverless invoke --function myDurableFunction --type Event --durable-execution-name order-1042 --json
{
  "statusCode": 202,
  "qualifier": "durable",
  "executedVersion": null,
  "durableExecutionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-service-dev-myDurableFunction:4/durable-execution/order-1042/2f6c0d3e-8a41-4b7e-9c55-1d0e6a7b3f92",
  "functionError": null,
  "payload": null,
  "log": null
}

--durable-execution-name makes the invocation idempotent. With --type Event, a name that already exists returns that execution's ARN, even when the payload differs; the new payload is not used. A synchronous invoke with the same name and a different payload returns a DurableExecutionAlreadyStartedException error.

When the stage has not been deployed with the function's alias, the durable invoke stops with Lambda's ResourceNotFoundException and the advice to run serverless deploy or pass --qualifier.

Invoke an agent

To invoke an AgentCore Runtime agent, use serverless invoke --agent instead of --function. The command reads the agent's runtime ARN from the deployed stack's outputs and streams the agent's response to standard output.

serverless invoke --agent myAgent --data '{"prompt": "Hello!"}'
OptionAliasValueDefaultRequiredDescription
--agent-astringYesAgent to invoke, as named under ai.agents in serverless.yml.
--data-dstringStandard inputNoPayload. A JSON object is sent as it is; any other text is sent as {"prompt": "<text>"}.
--path-pfile pathNoJSON or YAML file holding the payload, relative to the service directory. Ignored with --data.
--session-idat least 33 charactersNoRuntime session ID that keeps a multi-turn conversation together.

--agent cannot be combined with --function, --sandbox or --web-app, and --header and --json are not available with it. The caller needs bedrock-agentcore:InvokeAgentRuntime.

Invoke a sandbox

To send one HTTP request to a sandbox (AWS Lambda MicroVM), use serverless invoke --sandbox. The command starts a fresh MicroVM from the sandbox's image, sends the request through the AWS proxy, prints the response body on standard output, and terminates the MicroVM.

serverless invoke --sandbox mySandbox --path /health
OptionAliasValueDefaultRequiredDescription
--sandboxstringYesSandbox to invoke, as named under sandboxes in serverless.yml.
--path-pstring/NoHTTP request path.
--methodstringGETNoHTTP method.
--header'Name: value'NoRequest header (repeatable). Printable ASCII only; cannot set Host, X-Aws-Proxy-Auth or X-Aws-Proxy-Port.
--data-dstringNoRequest body; not sent with GET.
--portstring8080NoContainer port to send the request to.

--sandbox cannot be combined with --function, --agent or --web-app. The function and agent options (--qualifier, --type, --raw, --context, --contextPath, --tenant-id, --durable-execution-name, --session-id, --log and --json) stop the command with an error, for example ✖ --qualifier is not available with --sandbox. A response with status 400 or above is printed, and then the command exits with Sandbox '<name>' returned HTTP <status>.

The caller needs lambda:RunMicrovm, lambda:GetMicrovm, lambda:CreateMicrovmAuthToken, lambda:TerminateMicrovm, iam:PassRole and lambda:PassNetworkConnector. See Invoking a sandbox in the sandboxes guide.

Invoke a web app

To send one HTTP request to a web app (AWS Lambda Web Function), use serverless invoke --web-app. The command prints the status line and headers on standard error, then the body on standard output as it arrives, so piping the command to jq or a file passes the body alone. A redirect is printed, not followed. Requests to an aws_iam endpoint, or to a web app served on a custom domain, are signed with your AWS credentials.

serverless invoke --web-app api --path /health
OptionAliasValueDefaultRequiredDescription
--web-appstringYesWeb app to invoke, as named under webApps in serverless.yml.
--path-pstring/NoHTTP request path, with an optional query string.
--methodstringGETNoHTTP method.
--header'Name: value'NoRequest header (repeatable). A signed request is signed over these headers too. Cannot set Host, nor, for a signed request, Authorization, X-Amz-Date, X-Amz-Security-Token or X-Amz-Content-Sha256.
--data-dstringNoRequest body; not sent with GET or HEAD, so set --method with it.
--log-lbooleanfalseNoAfter the response, print the request's log lines: JSON lines that carry its request ID. Waits up to 30 seconds, then points to serverless logs --web-app <name>.

--web-app cannot be combined with --function, --agent or --sandbox. The function, agent and sandbox options (--qualifier, --type, --raw, --context, --contextPath, --tenant-id, --durable-execution-name, --session-id, --port and --json) stop the command with an error, for example ✖ --qualifier is not available with --web-app.

$ serverless invoke --web-app api --path /health

HTTP 200 OK
content-length: 11
content-type: application/json; charset=utf-8
date: Thu, 15 Oct 2026 08:03:43 GMT
etag: W/"b-Ai2R8hgEarLmHKwesT1qcY913ys"
lambda-web-logstream: 2026/10/15/my-web-app-dev-api[rev-t8yf1]cc269a07c59a48d19d554992708bda83
lambda-web-request-id: DFWK6UW3VJPQRADPSKLN2OULWA
x-powered-by: Express

{"ok":true}

A response with status 400 or above is printed in full, and then the command exits with code 1 and the error ✖ Web app "api" returned HTTP 404..

The caller needs lambda:InvokeWebFunctionEndpoint for an aws_iam or custom-domain web app, and logs:FilterLogEvents on the web app's /aws/lambda/web/<function-name>.local log group for --log. See Invoking a web app in the web apps guide.

Side effects and CI use

  • serverless invoke --function runs the deployed function in AWS, so every run repeats the function's side effects; --type DryRun checks the call without running the code. The command changes nothing in the service's configuration or stack. The caller needs lambda:InvokeFunction on the function.
  • The command does not prompt. Without --data or --path, it reads the event from standard input whenever standard input is not a terminal, so in CI pass --data or --path, or redirect standard input from /dev/null.
  • The exit code is non-zero when the invocation reports a function error (Invoked function failed, after the response is printed), when a sandbox or web app answers with status 400 or above, or when Lambda returns an error for the call.
  • When a Dev Mode session in the same service directory ran the call on your machine, the command also prints a line naming the request on standard error; standard output and the exit code do not change.

Provided lifecycle events

  • invoke:invoke

Examples

Invoke a function in a specific stage and region

serverless invoke --function hello --stage prod --region eu-central-1

Invoke a function with an event file

serverless invoke --function hello --path lib/data.json

Invoke a function with data from standard input

node dataGenerator.js | serverless invoke --function hello

Invoke a function and print its log

serverless invoke --function hello --log

Invoke a function with a client context file

serverless invoke --function hello --contextPath lib/context.json

Invoke a function asynchronously

serverless invoke --function hello --type Event

Invoke a specific version or alias

serverless invoke --function hello --qualifier 3

Invoke a function for a tenant

serverless invoke --function hello --tenant-id tenant-123

Related commands

  • serverless invoke local runs a function's code on your machine without deploying.
  • serverless logs prints a function's CloudWatch logs.
  • serverless dev runs a stage's real invocations on your working copy.
Edit this page
Prev infoNextinvoke local

Contents

  • serverless invoke
  • Options
  • Event data and client context
  • Invocation types and logs
  • Durable functions
  • Invoke an agent
  • Invoke a sandbox
  • Invoke a web app
  • Side effects and CI use
  • Provided lifecycle events
  • Examples
  • Invoke a function in a specific stage and region
  • Invoke a function with an event file
  • Invoke a function with data from standard input
  • Invoke a function and print its log
  • Invoke a function with a client context file
  • Invoke a function asynchronously
  • Invoke a specific version or alias
  • Invoke a function for a tenant
  • Related commands

Related

GuidesPluginsExamplesSlack CommunitySupport