Skip to main content
POST
/
workflows
/
{workflow_name}
/
run
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
}
'
{
  "success": true,
  "message": "Workflow execution started",
  "warning": null,
  "workflow_version_execution_id": 98765
}

Documentation Index

Fetch the complete documentation index at: https://promptlayer-claude-nice-fermi-nop3f.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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.

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

A dictionary of metadata key-value pairs.

​
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

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.