Skip to main content
POST
/
workflows
/
{workflow_name}
/
run
Run Workflow
curl --request POST \
  --url https://api.promptlayer.com/workflows/{workflow_name}/run \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "workflow_label_name": "<string>",
  "workflow_version_number": 123,
  "metadata": {},
  "input_variables": {},
  "return_all_outputs": false
}
'
{
  "success": true,
  "message": "<string>",
  "workflow_version_execution_id": 123,
  "warning": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt

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

Initiate the execution of a specific Workflow by its name. You can specify input variables, metadata, and choose which version of the Workflow to run.

​
HTTP Request

POST /workflows/{workflow_name}/run

​
Path Parameters

  • workflow_name (string, required): The name of the Workflow you wish to execute.

​
Request Body

The request body expects a JSON object with the following structure:

​
Schema

{
  "workflow_label_name": "string (optional)",
  "workflow_version_number": "integer (optional)",
  "metadata": {
    "string": "string"
  },
  "input_variables": {
    "string": "any"
  },
  "return_all_outputs": "boolean (default: false)",
  "callback_url": "string (optional)"
}

​
Parameters

  • workflow_label_name (string, optional): The label of the specific Workflow version to run.
  • workflow_version_number (integer, optional): The version number of the Workflow to run.
  • metadata (object, optional): Additional metadata to attach to the execution.
  • input_variables (object, optional): Input variables for the Workflow execution.
  • return_all_outputs (boolean, optional, default: false): Whether to return all node outputs or just the final output.
  • callback_url (string, optional): An HTTP URL where execution results will be POSTed when the Workflow completes. When provided, the API returns HTTP 202 (Accepted) immediately and sends results to this URL asynchronously. Ideal for long-running workflows and webhook-based integrations.

​
Response

Status Code: 201 (Created) or 202 (Accepted) if callback_url is provided When a callback_url is provided, PromptLayer will POST the following to your callback URL when the workflow completes: 
{
  "workflow_version_execution_id": "integer",
  "final_output": {
    "Node Name": {
      "status": "SUCCESS | FAILURE",
      "value": "any",
      "error_message": "string | null",
      "raw_error_message": "string | null",
      "is_output_node": "boolean"
    }
  }
}
The final_output structure matches the response from the GET /workflow-version-execution-results endpoint.

Headers

​
X-API-KEY
string
required

Your API key for authentication.

Path Parameters

​
workflow_name
string
required

The name of the workflow to execute.

Body

application/json

Parameters to run a workflow.

​
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.

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

Any warnings about missing input variables.