Pass runtime arguments in an execution request

You can pass runtime arguments in a workflow execution request and access thosearguments using workflow variables.

Note: Themaximum size of the arguments you can pass toyour workflow is 512 KB.

Set up a workflow that receives runtime arguments

To set up a workflow to receive runtime arguments that you pass to it aspart of an execution request, do the following:

  1. Follow the steps tocreate anew workflow, or choose an existing workflow toupdate, butdon't deploy it yet.

  2. Add aparams field to the main workflow's definition. Ensure that theargument name is placed inside square brackets, and that the main workflow isplaced in amain block:

    YAML

    main:params:[ARG_NAME]steps:...

    JSON

    {"main":{"params":["ARG_NAME"],"steps":[...]...}}

    Themain block accepts a single argument that is the name of any valid JSONdata type; for example, an array, an object, or a string.

    As a best practice, passing in an object with multiple, named arguments makesit easier to understand their purpose, and to add arguments. You can also thenuse dot notation to access the arguments.

    Other subworkflows can have multiple arguments.

    For example, the following workflow returns a "Hello" greeting to a personwhose first and last name you pass as runtime arguments:

    YAML

    main:params:[args]steps:-step1:assign:-outputVar:${"Hello, " + args.firstName + " " + args.lastName + "!"}-step2:return:${outputVar}

    JSON

    {"main":{"params":["args"],"steps":[{"step1":{"assign":[{"outputVar":"${\"Hello \" + args.firstName + \" \" + args.lastName}"}]}},{"step2":{"return":"${outputVar}"}}]}}

  3. Deploy your workflow to finish creating or updating it.

Pass data in an execution request

Once your workflow is set up to receive runtime arguments, you can pass a stringin JSON format, such as{"firstName":"Workflows","lastName":"User"}, to the workflow in anexecution request.

Console

  1. To execute a workflow, in the Google Cloud console, go to theWorkflows page:

    Go to Workflows

  2. On theWorkflows page, select a workflow to go to itsdetails page.

  3. On theWorkflow Details page, clickExecute.

  4. On the "Execute workflow" page that displays, enter a JSON stringcontaining your parameter names and argument values, such as{"firstName":"Workflows","lastName":"User"}, into the "Input" area:

    Input area populated with the example JSON string

  5. ClickExecute.

    On theExecution details page, you can view the results of theexecution including the outputHello, Workflows User!, the execution IDand state, and the current or final step of the workflow execution. Formore information, seeAccess workflow execution results.

gcloud

Add the--dataflag to thegcloud workflows executecommand that you use to execute your workflow. This flag takes a JSONstring of your data. For example, to pass afirstName andlastName tothe previous example workflow:

gcloudworkflowsrunWORKFLOW_NAME\--data='{"firstName":"FIRST","lastName":"LAST"}'

Replace the following:

  • WORKFLOW_NAME: the workflow's name
  • FIRST: the string you want to pass to your workflow forfirstName
  • LAST: the string you want to pass to your workflow forlastName

The output should be similar to the following:

Waiting for execution [9379b067-306a-4db1-a58d-c9fc99aebfd4] to complete...done.argument: '{"firstName":"Workflows","lastName":"User"}'endTime: '2022-07-19T13:52:47.659199466Z'name: projects/1051295516635/locations/us-central1/workflows/workflow-6/executions/9379b067-306a-4db1-a58d-c9fc99aebfd4result: '"Hello, Workflows User!"'startTime: '2022-07-19T13:52:47.623862835Z'state: SUCCEEDEDstatus:  currentSteps:  - routine: main    step: step2workflowRevisionId: 000002-138

Client libraries

Depending on the client library language, you can pass a runtime argumentin an execution request.

For example, using #"no" dir="ltr" is-upgraded syntax="JavaScript">// Execute workflowtry{constcreateExecutionRes=awaitclient.createExecution({parent:client.workflowPath(projectId,location,workflow),execution:{argument:JSON.stringify({"firstName":"Workflows","lastName":"User"})}});constexecutionName=createExecutionRes[0].name;

Or, using Java:

// Creates the execution object.CreateExecutionRequestrequest=CreateExecutionRequest.newBuilder().setParent(parent.toString()).setExecution(Execution.newBuilder().setArgument("{\"firstName\":\"Workflows\",\"lastName\":\"User\"}").build()).build();

For more information about executing a workflow using theGoogle API Client Libraries, seeExecute a workflow.

REST API

  1. Append thedata flag to the command that you use to execute yourworkflow. The value ofdata is a JSON formatted string with an argumentwhose value is one or more escaped parameter-value pairs. For example, topass afirstName andlastName to the previous example workflow:

    curl--requestPOST\--header"Authorization: Bearer "$(gcloudauthapplication-defaultprint-access-token)\--header'Content-Type: application/json'\--data'{"argument":"{\"firstName\":\"FIRST\",\"lastName\":\"LAST\"}"}'\"https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions"

    Replace the following:

    • PROJECT_NUMBER: your Google Cloud projectnumber
    • WORKFLOW_NAME: the workflow's name
    • FIRST: the string you want to pass to yourworkflow forfirstName
    • LAST: the string you want to pass to yourworkflow forlastName

    The output should be similar to the following:

    {  "name": "projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID",  "startTime": "2020-11-09T23:51:31.765761331Z",  "state": "ACTIVE",  "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",  "workflowRevisionId": "000001-08c"} ```

  2. To get the execution results, run the following command:

    curl--requestGET\--header"Authorization: Bearer "$(gcloudauthapplication-defaultprint-access-token)\--header'Content-Type: application/json'\"https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID"

    ReplaceEXECUTION_ID with the ID from the outputyour first command returned.

    This output contains lines similar to the following:

    "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}","result": "\"Hello, Workflows User!\"",

For more information about executing a workflow using the REST API, seeExecute a workflow.

Access runtime arguments

This sample accesses runtime arguments passed to the workflow as part of theexecution request. All arguments are stored in the same map, declared as aparameter of the main workflow.

When running this workflow, pass in runtime arguments using the following format:

{"firstName":"Sherlock","lastName":"Holmes"}

YAML

main:params:[args]steps:-step1:assign:-outputVar:${"Hello " + args.firstName + " " + args.lastName}-step2:return:${outputVar}

JSON

{"main":{"params":["args"],"steps":[{"step1":{"assign":[{"outputVar":"${\"Hello \" + args.firstName + \" \" + args.lastName}"}]}},{"step2":{"return":"${outputVar}"}}]}}

You can usedefault with the standard library function,map.get, to accessoptional runtime arguments, and return a default value if the key is notfound. In the following example, if aregion is not specified,northamerica-northeast1 is used:

YAML

main:params:[input]steps:-init:assign:-region:${default(map.get(input, "region"), "northamerica-northeast1")}

JSON

{"main":{"params":["input"],"steps":[{"init":{"assign":[{"region":"${default(map.get(input, \"region\"), \"northamerica-northeast1\")}"}]}}]}}

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.