Run Workflow

Trigger a workflow run manually

Published ·Updated

POST
/v1/workflows/{id}/run
curl -X POST "https://api.orshot.com/v1/workflows/<ID>/run" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>"

Overview#

Queue a manual run of a workflow. The run executes asynchronously; the response returns immediately with a runId you can poll via the run detail endpoint.

Each successful run uses one automation credit.

Endpoint
https://api.orshot.com/v1/workflows/:id/run

Path Parameters#

ParameterTypeRequiredDescription
idIntegerYesThe unique ID of the workflow

Request#

JavaScript
await fetch("https://api.orshot.com/v1/workflows/44/run", {
  method: "POST",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
JSON
{
  "runId": 5121,
  "status": "queued"
}

Returns 202 Accepted. Poll GET /v1/workflows/:id/runs/:runId for progress and per-step results.

Error Responses#

Workflow Not Runnable (400)#

JSON
{
  "error": "Workflow is not runnable",
  "details": ["no_destination"],
  "hints": ["Add a destination step so every render is delivered somewhere."]
}

Plan Gated Steps (403)#

JSON
{
  "error": "This workflow uses steps that need a higher plan",
  "code": "plan_gated"
}

Run Already Queued (409)#

JSON
{
  "error": "A run is already queued"
}

Workflow Not Found (404)#

JSON
{
  "error": "Not found"
}

Notes#

  • The workflow does not need to be active for a manual run; a complete draft runs fine.
  • A manual run of a polling workflow reads and advances the poll cursor, exactly like a scheduled run.

Rate Limits#

  • 60 requests per minute per workspace
Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 50+ integrations
  • White-label embed for your own app
  • 30 free credits — no credit card required