Run Amazon Bedrock flows asynchronously with flow executions

Start a flow execution

To run a flow execution, send a StartFlowExecution request with an Agents for Amazon Bedrock runtime endpoint. In the request, specify the flow ID and flow alias ID of the flow that you want to run. You can also specify the following:

{
    "inputs": [{
        "nodeName": "FlowInputNode",
        "nodeOutputName": "document",
        "content": {
            "document": "Test"
        }
    }],
    "name": "MyExecution"
}

The response is the Amazon Resource Name (ARN) of the flow execution. You can use the executionArn to poll for the current state of the flow, such as when the flow execution finishes or a condition node evaluates its conditions.

{
      "executionArn": "arn:aws:bedrock:us-west-2:111122223333:flow/FLOWID/alias/TSTALIASID/execution/MyExecution"
}

Track the progress of a flow execution

Use the GetFlowExecution operation to get the current status of a flow that you identify by its execution ARN. A flow status is either Running, Succeeded, Failed, TimedOut, or Aborted.

{
      "endedAt": null,
      "errors": null,
      "executionArn": "arn:aws:bedrock:us-west-2:111122223333:flow/FLOWID/alias/TSTALIASID/execution/MyExecution",
      "flowAliasIdentifier": "TSTALIASID",
      "flowIdentifier": "FLOWID",
      "flowVersion": "DRAFT",
      "startedAt": "2025-03-20T23:32:28.899221162Z",
      "status": "Running"
}

Errors (such as a Lambda node that times out) are returned in the errors array like the following example:

"errors": [{
    "nodeName": "LambdaNode1",
    "errorType": "ExecutionTimedOut",
    "message": "Call to lambda function timed out"
}],

Get the results of a flow execution

Amazon Bedrock writes the outputs of a flow to the flow's output nodes. You can get the outputs once the flow completes or while the flow is running (depending on your use case).

If you want the flow to complete first, make a call to GetFlowExecution and make sure that the value of the status field in the response is Succeeded.

To get a list of output events from the flow execution, make a call to ListFlowExecutionEvents. In the response, check for flowOutputEvent objects in flowExecutionEvents. For example, you can get a flow's output in the content field:

{
      "flowOutputEvent": {
        "content": {
          "document": "The model response."
        },
        "nodeName": "FlowOutputNode"
      }
}

You can limit the output from ListFlowExecutions to just input and output nodes by setting the eventType query parameter to Flow.

View events

To help debug your flow execution, you can use the ListFlowExecutionEvents operation to view events that nodes generate while the flow is running. Set the eventType query parameter to Node to see the inputs and outputs of all nodes (including intermediate nodes) in the response that's similar to the following example:

{
    "flowExecutionEvents": [{
            "nodeOutputEvent": {
                "fields": [{
                    "content": {
                        "document": "History book"
                    },
                    "name": "document"
                }],
                "nodeName": "FlowInputNode",
                "timestamp": "2025-05-05T18:38:56.637867516Z"
            }
        },
        {
            "nodeInputEvent": {
                "fields": [{
                    "content": {
                        "document": "History book"
                    },
                    "name": "book"
                }],
                "nodeName": "Prompt_1",
                "timestamp": "2025-05-05T18:38:57.434600163Z"
            }
        },
        {
            "nodeOutputEvent": {
                "fields": [{
                    "content": {
                        "document": "Here's a summary of the history book."
                    },
                    "name": "modelCompletion"
                }],
                "nodeName": "Prompt_1",
                "timestamp": "2025-05-05T18:39:06.034157077Z"
            }
        },
        {
            "nodeInputEvent": {
                "fields": [{
                    "content": {
                        "document": "Here's a summary of the history book."
                    },
                    "name": "document"
                }],
                "nodeName": "FlowOutputNode",
                "timestamp": "2025-05-05T18:39:06.453128251Z"
            }
        }
    ]
}

Get a snapshot of your flow execution

Amazon Bedrock automatically takes a snapshot of a flow definition and metadata when a flow execution starts. This is helpful since a flow can be updated while it's running asynchronously. To retrieve this snapshot, call the GetExecutionFlowSnapshot operation. The response includes the following flow fields:

{
      "customerEncryptionKeyArn": null,
      "definition": "{flow-definition}",
      "executionRoleArn": "arn:aws:iam::111122223333:role/name",
      "flowAliasIdentifier": "TSTALIASID",
      "flowIdentifier": "FLOWID",
      "flowVersion": "DRAFT"
}

List your flow executions

You can get a list of your flow executions by calling the ListFlowExecutions operation. The response includes a flowExecutionSummaries array with information about each of your flow executions in the current AWS Region for a flow or flow alias. Each element includes information such as the execution ARN, the start time, and the current status of the flow.

{
    "flowExecutionSummaries": [{
        "createdAt": "2025-03-11T23:21:02.875598966Z",
        "endedAt": null,
        "executionArn": "arn:aws:bedrock:us-west-2:111122223333:flow/FLOWID/alias/TSTALIASID/execution/MyExecution",
        "flowAliasIdentifier": "TSTALIASID",
        "flowIdentifier": "FLOWID",
        "flowVersion": "DRAFT",
        "status": "Running"
    }]
}

Stop a running flow execution

If you need to stop a running flow execution, call the StopFlowExecution operation and pass the flow ID, flow alias ID, and the flow execution ID for the execution that you want to stop.