Run Workflow

POST /workflows/{workflow_name}/run

cURL

runLatest

curl --request POST \
  --url https://api.promptlayer.com/workflows/{workflow_name}/run \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "input_variables": {
    "user_message": "I need help with billing"
  },
  "metadata": {
    "environment": "production"
  },
  "return_all_outputs": false
}
'

201

{
  "success": true,
  "message": "Workflow execution started",
  "warning": null,
  "workflow_version_execution_id": 98765
}

{
  "success": true,
  "message": "Workflow execution accepted",
  "warning": null,
  "workflow_version_execution_id": 98765
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Initiate an execution of a Workflow by name. You can run the latest version, choose a version by label or version number, pass input variables and metadata, and optionally receive results asynchronously with a callback URL.

Behavior Notes

• workflow_label_name and workflow_version_number identify a specific version; omit both to run the latest version.
• When callback_url is provided, the API accepts the run immediately and posts results to your callback when execution finishes.
• Use Get Workflow Version Execution Results to poll for execution output.

Related

• Create Workflow
• Get Workflow Version Execution Results
• Workflows

Authorizations

X-API-KEY · string · header · required

Path Parameters

workflow_name · string · required

The name of the workflow to execute.

Body

application/json

Parameters to run a workflow by label, version number, or latest version. workflow_label_name and workflow_version_number are mutually exclusive.

workflow_label_name · string | null

Specify a workflow label name to run a specific labeled version.

workflow_version_number · integer | null

Specify a workflow version number to run a specific version.

metadata · object | null

A dictionary of metadata key-value pairs.

Show child attributes

input_variables · object

A dictionary of input variables required by the workflow.

return_all_outputs · boolean · default: false

If set to true, all outputs from the workflow execution will be returned.

callback_url · string<uri> | null

HTTP URL where execution results are posted asynchronously. When provided, the API returns 202 Accepted immediately.

Response

201

application/json

Workflow execution created successfully

Response after initiating a workflow execution.

success · boolean · required

Indicates if the request was successful.

message · string · required

A message describing the result.

workflow_version_execution_id · integer · required

The ID of the created workflow execution.

warning · string | null

Warning about missing or unused input variables, if any.