<!-- https://developers.silktide.com/v1/governance/user-flows/get-flows | Governance / User flows -->

# List a website's user flows, how reliably each runs, and the pages it reached

`GET /v1/results/flows`

Lists a website's user flows: each one's last run, how often its runs
succeeded over 30 and 90 days, and the page each of its steps reached.

Only live flows that have run at least once are listed. A draft, or a new
flow that has not run yet, is left out.

`pages` holds one page per step, from the flow's last run, and is not in step
order: sort it by `stepNo`. A step that failed has `isFailedStep: true`. The
same pages also appear, with these `flowId`s, in
[Get contents](https://developers.silktide.com/v1/governance/content/get-contents.md).

User flows belong to the whole website, so this query takes no `sectionId`:
one sent is ignored. Older documentation said it could be read for a section.

`websiteId` is required. Without it the answer is an `InvalidRequest` error
whose `properties.field` is `websiteId`, with status `200`; check for `error`
before reading `result`.

## Request

### Query parameters

- `websiteId` (integer, required, at least 1): The website.

## Response

Status `200`.

- `result` (object, required): The answer.
  - `flows` (list of objects, required): Each live (not draft) user flow of the website that has run at least once.
    - `flowId` (integer, required, at least 1): The user flow's id. Pages it reached carry it as their `flowId`.
    - `name` (string, required): Its name.
    - `description` (string, required): What it does, as its author wrote it. Can be empty.
    - `numSteps` (integer, required): How many steps it has.
    - `downloaded` (integer, required): When it last ran.
    - `screenshotUrl` (string, required): A screenshot of the browser window at the end of its last run. Can be empty.
    - `uptime30Day` (number, required, 0 to 100): The percentage of its runs that succeeded in the 30 days up to its last run.
    - `uptime90Day` (number, required, 0 to 100): The percentage of its runs that succeeded in the 90 days up to its last run.
    - `pages` (list of objects, required): The page each step reached in its last run, in no particular order. Sort by `stepNo`.
      - `url` (string, required): Its URL. A document linked from the website can be on another domain.
      - `title` (string, required): Its title: a page's `<title>`, or a document's title or file name. `Untitled` when a document has neither.
      - `contentType` (string, required): What it is: `html` for a page, `pdf` for a PDF document. Silktide tests no other kind today. One of: `html`, `pdf`, `text`, `word`, `excel`, `powerpoint`, `other`.
      - `httpCode` (integer, required, can be null): The HTTP status it answered with when last downloaded. Null when none was recorded.
      - `mimeType` (string, required): Its content type as the server sent it, such as `text/html`.
      - `downloaded` (integer, required): When Silktide last downloaded it.
      - `discovered` (integer, required): When Silktide first downloaded it.
      - `defaultOrder` (string, required): Sort by this, ascending, to list content in the order Silktide does. Its format can change; only compare it.
      - `flowId` (integer, required): The user flow it was reached by, or `0` when it was crawled.
      - `stepNo` (integer, required): In a user flow, its step, from `0`. `0` when it was crawled.
      - `isFailedStep` (boolean, required): True when it is the step at which its user flow failed.
- `selector` (string, required): The query that answered, as its path: `/v1/results/scores`.
- `duration` (number, required): Seconds Silktide took to answer.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 404 | `ModelNotFound` | No website or section with that id exists in the account, or the API key's user cannot see it. |
| 200 | `InvalidRequest` | No `websiteId` was sent. The error's own `status` is `400` and `properties.field` is `websiteId`. The body is an error despite the status. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: any user of the account
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: A website with one user flow

```bash
curl "https://api.eu.silktide.com/v1/results/flows?websiteId=3" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "result": {
    "flows": [
      {
        "flowId": 3,
        "name": "Submit contact form",
        "description": "Send an inquiry through the contact form",
        "numSteps": 2,
        "downloaded": 1790376639,
        "screenshotUrl": "https://example.com/screenshots/b867ffe979dd014d5241586522485402-desktop-viewport.webp",
        "uptime30Day": 96.7,
        "uptime90Day": 98.9,
        "pages": [
          {
            "url": "https://fakewinebarrel.com/contact-us/",
            "title": "Submit contact form (2/2): Submit form",
            "contentType": "html",
            "httpCode": 200,
            "mimeType": "text/html",
            "downloaded": 1790376655,
            "discovered": 1790222900,
            "defaultOrder": "3003-00102-038-038",
            "flowId": 3,
            "stepNo": 1,
            "isFailedStep": false
          },
          {
            "url": "https://fakewinebarrel.com/contact-us/",
            "title": "Submit contact form (1/2): Load page",
            "contentType": "html",
            "httpCode": 200,
            "mimeType": "text/html",
            "downloaded": 1790376639,
            "discovered": 1790222884,
            "defaultOrder": "3003-00002-038-038",
            "flowId": 3,
            "stepNo": 0,
            "isFailedStep": false
          }
        ]
      }
    ]
  },
  "selector": "/v1/results/flows",
  "duration": 0.029
}
```