Skip to main content
Some requests start work that takes a while, such as importing an invoice, checking it against your agreements or syncing from your accounting system. Watchdog tracks each of these as a workflow run. A run is made up of items, one per piece of work: a sync has one item per invoice, for example. You often don’t need runs at all. The import, invoice or sync you started usually tells you what you need. Use runs when you want to follow progress, see what failed, or cancel or retry the work.

​
Follow a run

Imports and checks return a workflow_run_id, and a sync’s id is its run ID. Read the run every few seconds until its status is no longer queued or running:
progress counts the items in each state. While Watchdog is still finding work, for example during a sync, progress.total is null. A finished run ends in one of these states:
  • completed: everything succeeded. A run with nothing to do also ends here.
  • completed_with_errors: some items succeeded and some didn’t.
  • failed: nothing succeeded, or the run itself failed. failure says why.
  • cancelled: someone stopped it. Items that had already finished keep their results.
A failed run is still a normal answer (200), with the failure in the body.

​
See the results

GET /v1/workflow-runs/{id}/items lists the items with their results. Each item’s result is available as soon as that item finishes, even if the rest of the run is still going. Filter with statuses=failed to see only what went wrong.

​
Find runs

GET /v1/workflow-runs lists runs, newest first. Filter by status, type or the record a run belongs to.

​
Cancel or retry

  • Cancel with POST /v1/workflow-runs/{id}/cancel. Work that hasn’t finished stops; finished items keep their results. A run that has already finished can’t be cancelled.
  • Retry a failed invoice import, invoice check or accounting sync with POST /v1/workflow-runs/{id}/retry. An import or check retry starts a new run, linked to the old one through retry_of_run_id. A sync retry picks up the same run where it stopped.