Skip to Content
Browse the Docs▾

Run a workflow now

POST/api/v1/workflows/{id}/runs

Start a workflow's next run within about a minute, without changing its schedule.

curl -X POST -H "Authorization: Bearer $REVNU_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"clientRequestId":"wf-h97-first-run"}' \
  https://revnu.com/api/v1/workflows/h97…/runs

Body

{ clientRequestId? }. Both the body and the field are optional. clientRequestId (1 to 128 characters of A-Z a-z 0-9 _ . : -) makes the call safe to retry: the same id on the same workflow returns the same run.

Response

202 { "run": { id, status: "queued", startedAt }, "deduplicated": false }. The run starts within about a minute and then shows in GET /workflows/{id}/runs under the same id, moving from queued to running and then done or failed.

deduplicated: true means no new run was queued: the clientRequestId was seen before, or the workflow already has a run queued or running, and run is that one.

Code Meaning
409 error is paused (resume it first), not_approved (the agent proposed it, nobody has approved it yet and the account's Proposed Workflows setting is Ask Me First: resume approves it), schedule_pending (the schedule is still being set up, so retry shortly), schedule_error (fix scheduleText) or webhook_trigger (it runs on each event from the webhook its scheduleText names, so send that webhook an event to run it).

Frequently Asked Questions

Does this change the schedule?

No. The workflow keeps running on its schedule. The one exception: when the next scheduled run is less than an hour away, this run replaces it, so the agent doesn't do the same work twice in a row.

Can I call it right after creating a workflow?

Yes. The schedule is set up about a second after POST /workflows, and this call waits up to a few seconds for it. If it still answers 409 with schedule_pending, retry with the same clientRequestId.

Can scheduleText express a one-time run?

Use this route for a one-time run now, and keep scheduleText for the repeating cadence: daily, weekly or monthly.

Does a run send anything without approval?

A run follows your approval settings, like any other work Revnu does. Steps with a gate wait for a person, and anything set to Ask Me First in Settings → Agent → What Needs Your Approval lands in the review queue. Anything set to Just Do It goes out without asking. To make sure a run only researches, set the sending kinds of work to Ask Me First, or put a gate on the step that would send.

Which scope does this need?

workflows:write. A token without it gets 403 with requiredScope in the body. GET /me shows a token's scopes.