Start a Workflow Run

  • Published on Feb 11, 2026
  • 1 minute(s) read
  • CC
 Prev Next
Post
/workflow/{workflow_id}/run

This page will help you get started with starting a Workflow Run.

Start a workflow run

To start a workflow run, send a POST request to <https://api.copy.ai/api/workflow/><workflow_id>/run with a JSON body containing the starting value(s) for the run.

For example:

JSON
{
  "startVariables": {
	  "Input 1": "<Inputs vary depending on the workflow used.>",
	  "Input 2": "<The best way to see an example is to try it!>"
	},
	"metadata": {
    "api": true  /* example optional metadata to set on the workflow run */
	}
}

You will receive a response with the ID of the started workflow run:

JSON
{
  "status": "success",
  "data": {
    "id": "<run_id>"
  }
}

This ID can be used to track the progress of the workflow run and will also be included in the webhook request when the run is completed.


Track or poll for progress

To track a workflow run, send a GET request to <https://api.copy.ai/api/workflow/><workflow_id>/run/<run_id>. You will get a response in the following format:

JSON
{
    "status": "success",
    "data":
    {
        "id": "<run_id>",
        "input":
        { 
          	"Input 1": "Inputs vary depending on the workflow used.",
			      "Input 2": "The best way to see an example is to try it!" 
        },
        "status": "PROCESSING",
        "output":
        {
            "Output 1": "<Outputs vary depending on the workflow used.>",
						"Output 2": "<The best way to see an example is to try it!>"
        },
        "createdAt": "2022-11-18T20:30:07.434Z"
    }
}

To learn more about the workflow run details and statuses available, visit this page: Get Workflow Run


Run completion

When the run is complete, the status will change to COMPLETE and we will send a POST request to any webhooks registered to receive completion events for the workflow.

Example request:

JSON
{
    "type": "workflowRun.completed",
    "workflowRunId": "<run_id>",
    "workflowId": "<workflow_id>",
    "result":
    {
      "Output 1": "<Outputs vary depending on the workflow used.>",
			"Output 2": "<The best way to see an example is to try it!>"
    },
    "metadata":
    {
      /* any metadata set on the workflow run */
    },
    "credits": 2 
}

To learn more about registering a webhook, see this page: Register Webhook

Security
API Key: ApiKeyAuth
Header parameter namex-copy-ai-api-key

Copy.ai API key for authentication

Header parameters
x-copy-ai-api-key
stringRequired
Path parameters
workflow_id
stringRequired

ID of the workflow

Body parameters
example1
{
  "startVariables": {
    "input_text": "Generate a blog post about AI",
    "tone": "professional"
  },
  "metadata": {
    "api": "True",
    "user_id": "user_12345"
  }
}
Expand All
object
startVariables
object Required
metadata
object
Responses
200

Success

success
{
  "status": "success",
  "data": {
    "id": "some-UUID-1234"
  }
}
Expand All
object
status
string
data
object
id
string
400

Bad Request or Credit Limit Reached

creditLimit
{
  "status": "error",
  "errorCode": "WORKFLOW_CREDIT_LIMIT_REACHED"
}
404

Not Found

422

Validation Error