---
title: "List workflows"
method: GET
path: "/workflow/runs"
tags: ["Workflow"]
---

# List workflows

`GET /workflow/runs`

## Request

- Base URL: `https://app.amperity.com/api`
- URL: `https://app.amperity.com/api/workflow/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/amperity/apis/amperity-api/docs/workflow/runs/get.ts> (a function with typed inputs; its response is checked against the schema)

Return a list of workflows that exist within the date range defined in the request.

## Query parameters

- `type` string
- `next_token` string
- `state` string
- `limit` integer
- `ended_from` string, date-time
- `created_from` string, date-time
- `api_version` string
- `ended_to` string, date-time
- `created_to` string, date-time
- `with_total` boolean

## Headers

- `Amperity-Tenant` string, required
- `Api-Version` string, required

## Response `200`

List of workflows

- WorkflowListEnvelope: A paginated list of workflows.
  - `data` Workflow[], required: Workflow items in this page
    - `created_at` string, date-time, required: Time the workflow was created
    - `current_version` string: The current ent version associated with the workflow
    - `ended_at` string, date-time: Time the workflow reached a terminal state
    - `error` WorkflowError: An error on the workflow. Populated only for error states.
      - `attribution` string: The underlying cause of the error, either customer or platform.
      - `data` WorkflowErrorData: Any additional data associated with this error.
      - `message` string, required: The error message.
      - `type` string, required: The type of workflow error.
    - `id` string, required: Unique identifier for the workflow
    - `launched_version` string: The ent version that was launched with the workflow
    - `name` string: Human-readable identifier for the workflow
    - `principal_email` string: Email address for who or what created the workflow
    - `principal_id` string: Principal id for who or what created the workflow
    - `principal_name` string: Human-readable name for who or what created the workflow
    - `state` string, required: Current workflow state.
    - `task_instances` Task[]: The list of tasks on the workflow.
      - `created_at` string, date-time, required: Time the task instance was created
      - `ended_at` string, date-time: Time the task reached a terminal state
      - `error` WorkflowError: An error on the workflow. Populated only for error states.
        - `attribution` string: The underlying cause of the error, either customer or platform.
        - `data` WorkflowErrorData: Any additional data associated with this error.
        - `message` string, required: The error message.
        - `type` string, required: The type of workflow error.
      - `execution_type` string: The execution type for the workflow
      - `id` string, required: Unique identifier for the task instance
      - `label` string, required: Human-readable label for a task-instance
      - `run_id` string: Unique identifier for the task instance to support execution engines that can't provide an external run id
      - `state` string, required: Current task instance state.
      - `state_changed_at` string, date-time: Time the task instance most recently changed state
      - `task_definition_id` string, required: Identifier for a task definition
      - `task_definition_type` string, required: A keyword for identify different task types
      - `tenant` string, required: The unique identifier for the tenant.
      - `timeout_ms` number, double: The length of time in milliseconds after which to forcibly kill a running task instance
      - `workflow_id` string, required: Unique identifier for the workflow
    - `tenant` string, required: The unique identifier for the tenant.
    - `type` string, required: Keyword identifying the type of workflow
    - `warn_after_ms` number, double: The time in milliseconds we should send a running long duration warning
  - `next_token` string: The cursor value to use in a subsequent request to return the next page of results.
  - `total` integer: The total count of all results. This property is only returned when `with_total` is set to `true` in a request.

## Other responses

- `400`: Bad Request
- `401`: Authentication Required
- `403`: Not Authorized
- `404`: Not Found
- `405`: Method Not Allowed
- `500`: Internal Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/amperity/apis/amperity-api.md) - [All operations](https://skmtc.dev/amperity/apis/amperity-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amperity/apis/amperity-api/revisions/97ccd051d9dc?raw)