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>",
  "warning": "<string>",
  "workflow_version_execution_id": 123
}
Initiate the execution of a specific Agent by its name. You can specify input variables, metadata, and choose which version of the Agent to run. Please note that this feature was previously called “Workflows” and is now called “Agents”. Some references to “Workflows” remain in our SDK and will be updated before the feature exits beta.

​
HTTP Request

POST /workflows/{workflow_name}/run

​
Path Parameters

  • workflow_name (string, required): The name of the Agent 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 Agent version to run.
  • workflow_version_number (integer, optional): The version number of the Agent to run.
  • metadata (object, optional): Additional metadata to attach to the execution.
  • input_variables (object, optional): Input variables for the Agent 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 Agent completes. When provided, the API returns HTTP 202 (Accepted) immediately and sends results to this URL asynchronously. Ideal for long-running agents 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 agent 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 | null

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.