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: <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)"
}

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

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

Any warnings about missing input variables.