---
title: Run a flow
url: https://docs.triply.cc/how-to/run-a-flow/
description: Start a flow by hand, from a preset, on a schedule or over HTTP, follow a run, stop it, and
  find out why it failed.
availability:
- 'Private preview: This feature is switched on per instance, by arrangement. Get in touch if you would
  like access.'
---

# Run a flow

This page covers starting a flow and following its runs. Running a flow takes the
**Run flows** permission on it; see [Permissions](https://docs.triply.cc/reference/flows/#permissions). For run
statuses and the API in full, see the [Flows reference](https://docs.triply.cc/reference/flows/).

## Run it by hand

1. Click **Save** at the top of the flow builder. **Run** is unavailable while there are unsaved
   changes.
2. Click **Run**.
3. If the flow has variables, fill them in. Click a preset at the top of the dialog to fill in its
   values; the default preset's are filled in already.
4. Click **Run**.

The run's page opens. To start a run from a preset directly, click its run button on the
flow's **Presets** page.

## Follow a run

The run's page shows the flow's tasks, each marked as it starts and finishes, and in its header
how the run was started, by whom, and how long it took.

Click a task to see its details: when it started and how long it took, the graphs it wrote, the
files it produced and, for a query, the query as it was run, and for a **Set variables** task, the variables it set. The same details are available over
the API:

```bash
curl -H "Authorization: Bearer $TOKEN" "https://API/flows/taskInstances?runId=RUN"
```

All runs of a flow are listed on its **Runs** page, where they can be filtered by trigger, status
and who started them.

To stop a run in progress, click **Stop run** on its page. Tasks that have finished keep what they
wrote.

## Find out why a run failed

1. Open the run from the flow's **Runs** page. The task that failed is marked, and the run's
   header shows **Failed**; hold the pointer over it to read the error message.
2. For more — a [connector script](https://docs.triply.cc/how-to/run-custom-code-in-a-flow/)'s `script.log`, say — click the
   task to read its details, or get them over the API as [above](#follow-a-run). A file listed under a task's `artifacts` downloads from
   `https://API/flows/taskInstances/TASK/artifacts/ARTIFACT`.
3. If a variable was wrong, run again with a different value; if a task was, fix it in the builder,
   save, and run again.

Whoever started the run gets an email, with the error message, when it fails or times out. To stop those emails, switch
off **Email notifications** under **General** in your user settings.

## Run it on a schedule

1. Open **Schedules** in the flow's navigation and click **Add Schedule**.
2. Give it a **Label**.
3. Under **Schedule**, choose how often — every so many minutes or hours, or every day, week or
   month — and at what time, and choose the **Timezone**. The dialog lists the next five runs.
4. If the flow has variables, fill in the values these runs use.
5. Click **Save**.

The schedule runs as you, with your permissions. To pause it without losing it, switch off
**Enabled**.

## Run it when data is uploaded

1. Open **Hooks** in the flow's navigation and click **Add Hook**.
2. Give it a **Label**.
3. Choose the **Hook type**: **Asset is uploaded to a dataset**, or **Data is uploaded to a
   dataset** for uploads on the dataset's **Graphs** page.
4. Choose the **Dataset** to watch.
5. If the flow has variables, fill in the values these runs use, or pick a preset to fill them in.
6. Click **Save**.

The hook runs as you, with your permissions. A data upload starts one run for each graph it adds.
The first run shows **Waiting for data upload to finish** until the upload is done. Tasks can read
what was uploaded from the [system variables](https://docs.triply.cc/reference/flows/#system-variables): for
example, `?system_uploadedGraphIRI` as the input graph of a SHACL validation. To pause a hook
without losing it, switch off **Enabled**.

## Run it from another system

1. Create an [API token](https://docs.triply.cc/how-to/create-an-api-token/) for an account that may run the flow.
2. Open the flow's **API** page. It shows the address to call, and, once you fill in the
   variables, ready-made requests in cURL, Python and JavaScript.
3. Send a `POST` request to that address, with the token in an `Authorization: Bearer` header and
   each variable as a parameter:

    ```bash
    curl -X POST \
      -H "Authorization: Bearer $TOKEN" \
      "https://API/flows/blueprints/ACCOUNT/FLOW/run?dataset=iris"
    ```

The response describes the new run, including its `id`. To follow it, request
`https://API/flows/runs/RUN`; to stop it, `POST` to `https://API/flows/runs/RUN/abort`. The other
requests are listed under [HTTP API](https://docs.triply.cc/reference/flows/#http-api).

A run started this way does not use the default preset. To use a preset's values, call
`https://API/flows/blueprints/ACCOUNT/FLOW/triggers/PRESET/run` instead.