> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow runs

> Follow work that runs in the background, see its results, and cancel or retry it.

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`:

```bash theme={null}
curl "$API_URL/v1/workflow-runs/$RUN_ID" \
  -H "Authorization: Bearer $API_KEY" -H "X-Organization-Id: $ORGANIZATION_ID"
```

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.