---
title: "Retrieve Workflows"
method: GET
path: "/v1/workflows"
tags: ["Workflows", "v1"]
---

# Retrieve Workflows

`GET /v1/workflows`

Retrieve the account's workflows as a paginated list, each with its complete definition of triggers and steps.

Only workflows belonging to the account given by `account_id` are ever returned, and only those the authenticated user is allowed to see.

Use `include` to pull in the user who created a workflow, the user who turned it off, its recent run statistics, or the errors it has run into.

Credit Note: Retrieving workflows does not consume credits.

:::info
Requires the `workflows:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required
- `page[cursor]` string
- `page[size]` integer
- `include` string
- `workflow_type` 'company' | 'contact' | 'time' | 'any'
- `enabled` boolean

## Response `200`

Success

- object
  - `data` WorkflowV1[], required
    - `type` 'workflow', required — The type of the object.
    - `id` string, required — The unique identifier for the workflow. It stays the same across updates, including the ones that produce a new `version`.
    - `attributes` object, required
      - `name` string, required — Human-readable name of the workflow.
      - `description` string, nullable, required — Free-text description of what the workflow does.
      - `enabled` boolean, required — Whether the workflow is live. Only an enabled workflow reacts to its triggers. Workflows are always created disabled and are turned on through **Update Workflow**, which is where the definition is validated.
      - `workflow_type` 'company' | 'contact' | 'time' | 'any', nullable, required — The kind of resource the workflow operates on, derived from its triggers (or, when it has none, from its first steps). - `company` — the workflow runs once per company. - `contact` — the workflow runs once per contact. - `time` — the workflow runs on a schedule and is not handed a resource. - `any` — the workflow's steps accept whatever they are given.
      - `version` integer, required — Which revision of the workflow this is. Workflows are versioned internally: every change to the definition stores a new version, and reads always return the latest one. The `id` is unaffected.
      - `definition_version` 'V1', required — The format the `definition` is written in. Only `V1` exists today. A future format would be introduced under a new value rather than by changing the meaning of this one.
      - `definition` object, required — The complete definition of a workflow: what starts it (`triggers`), what it can do (`steps`), and in which order the steps run (`order`). A definition is stored exactly as sent and is **not** validated while the workflow stays disabled, so an incomplete draft is accepted. It is validated in full the moment the workflow is enabled — see **Update Workflow**.
        - `triggers` object[], required — The events that start the workflow. The workflow runs when any one of them fires. All triggers of a workflow must produce the same `entity_type`. An empty array is accepted on a workflow that is still being put together, but a workflow cannot be enabled without at least one trigger.
          - `name` string, required — The name of the trigger definition this entry configures, as returned by **Retrieve Workflow Trigger Definitions**.
          - `filters` object[], required — Narrows down which occurrences of the event start the workflow. A workflow starts when **any** of its filters matches, so listing the same attribute twice widens the trigger rather than narrowing it.
            - `attribute` string, required — The filter to apply, taken from the trigger definition's `filters`.
            - `op` 'eq' — How `value` is compared against the event.
            - `value` union, required — The value to compare against. Its type follows the `entity_type` of the matching filter on the trigger definition.
              - …
          - `options` object — Values for the trigger definition's `options`, keyed by option name. Each value follows the `entity_type` declared for that option.
        - `steps` object, required — The workflow's steps, keyed by step id. Step ids are chosen by the caller, are unique within the workflow, and are what `order` refers to. The id `trigger` is reserved.
        - `order` object, required — How the steps are wired together, keyed by step id. The value is the list of steps that run after that step — several entries mean the workflow branches and each branch runs. The special key `trigger` holds the steps that run first, right after the workflow starts. An entry is either a step id, or a condition object that picks the next step based on the resource flowing through the workflow. A step id that is not defined in `steps`, or a cycle, is rejected when the workflow is enabled.
      - `has_errors` boolean, required — Whether the workflow has run into any error. Request `include=errors` for the details.
      - `disabled_at` string, date-time, nullable, required — When the workflow was last turned off. `null` while it is enabled.
      - `disabled_reason` 'manual' | 'auto_disabled_high_failure_rate', nullable, required — Why the workflow is off. - `manual` — somebody turned it off, through the API or the app. See the `disabled_by` relationship for who. - `auto_disabled_high_failure_rate` — Leadfeeder turned it off because too many of its runs were failing. Fix the cause reported under `include=errors` before enabling it again.
      - `created_at` string, date-time, required — When the workflow was created.
      - `updated_at` string, date-time, required — When the workflow was last changed.
      - `app_url` string, uri, required — Where the workflow can be opened in Leadfeeder, so it can be linked to directly instead of the URL being assembled from the `id`.
    - `relationships` object, required — Reference pointers to related resources. `created_by` and `disabled_by` carry `id` / `type` by default and are inlined in full when requested through `include=`. `run_stats` and `errors` are only present when they are requested — computing them costs a separate lookup, so they are never returned by default.
      - `created_by` union, required — The user who created the workflow. Inlined as a full `user` resource when `include=created_by` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=created_by` is not requested.
          - `id` string, required
          - `type` 'user', required
        - UserV1
          - `type` 'user', required — The type of the object.
          - `id` string, required — The user ID.
          - `attributes` object, required
            - `email` string, required — A standard e-mail address.
            - `first_name` string, nullable, required — The user's first name.
            - `last_name` string, nullable, required — The user's last name.
            - `phone_number` string, required — E.164 representation of a phone number.
            - `country_code` string, nullable, required — This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
            - `team_role` string, nullable, required — The role the user has within their team in Leadfeeder.
      - `disabled_by` union, required — The user who last turned the workflow off. Inlined as a full `user` resource when `include=disabled_by` is set; otherwise an `id` / `type` reference.
        - object — Reference returned by default — `id` / `type` only, when `include=disabled_by` is not requested.
          - `id` string, required
          - `type` 'user', required
        - UserV1
          - `type` 'user', required — The type of the object.
          - `id` string, required — The user ID.
          - `attributes` object, required
            - `email` string, required — A standard e-mail address.
            - `first_name` string, nullable, required — The user's first name.
            - `last_name` string, nullable, required — The user's last name.
            - `phone_number` string, required — E.164 representation of a phone number.
            - `country_code` string, nullable, required — This field indicates the country supported for Leadfeeder operations and requires a two letter country code according to ISO 3166 Alpha-2 (see [https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
            - `team_role` string, nullable, required — The role the user has within their team in Leadfeeder.
      - `run_stats` object — How often the workflow has run recently, and how much of that failed.
        - `type` 'workflow_run_stats', required — The type of the object.
        - `id` string, required — The id of the workflow these statistics belong to.
        - `attributes` object, required
          - `triggered_count` integer, required — How many times the workflow started.
          - `failed_count` integer, required — How many of those runs failed on at least one step. A run that failed is also counted in `triggered_count`.
          - `last_run_at` string, date-time, nullable, required — When the workflow last started. `null` when it has never run.
      - `errors` object[] — The failures the workflow has run into, most recent first. Present only when `include=errors` is set, and empty when there are none.
        - `type` 'workflow_error', required — The type of the object.
        - `id` string, required — A stable identifier for this group of errors. It stays the same for as long as the same step keeps failing in the same way.
        - `attributes` object, required
          - `step_id` string, required — The step that failed, as keyed in the workflow's `definition.steps`.
          - `error_code` string, required — A short machine-readable identifier for the failure.
          - `error_message` string, required — A human-readable description of the failure.
          - `count` integer, required — How many times this failure has occurred.
          - `first_seen_at` string, date-time, required — When this failure was first seen.
          - `last_seen_at` string, date-time, required — When this failure was last seen.
  - `meta` object, required
    - `credits` object, required
      - `charged` number, required — How many credits were consumed for this request.
    - `pagination` object, required
      - `next_cursor` string, nullable
      - `total_count` integer, required
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/3b95d5a53148/schema)