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

# List flow runs

> Lists the workspace's flow runs, the newest first, each with its state, the record it ran on and when it started. Filter with `flow` for one flow's runs (an unknown or deleted flow is a 404). Filter with `status` (default: every state but queued), `since` / `until` (when it started), and `record_object` / `record_id` (the record it ran on). The first page (no `cursor`) also has `summary`: the counts the Executions page shows above its grid, over every run the filters match; later pages have `summary: null`. A run is one time an Agent Studio flow ran, on one record or on its schedule; Agent Studio's Executions page lists them. Runs of deleted flows are not listed. Same access as the Executions page: the workspace's plan includes Agent Studio (else 403 not_entitled) and the person's role can open Agent Studio, admins and builders (else 403 insufficient_scope).



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/automations/runs
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/automations/runs:
    get:
      tags:
        - automations
      summary: List flow runs
      description: >-
        Lists the workspace's flow runs, the newest first, each with its state,
        the record it ran on and when it started. Filter with `flow` for one
        flow's runs (an unknown or deleted flow is a 404). Filter with `status`
        (default: every state but queued), `since` / `until` (when it started),
        and `record_object` / `record_id` (the record it ran on). The first page
        (no `cursor`) also has `summary`: the counts the Executions page shows
        above its grid, over every run the filters match; later pages have
        `summary: null`. A run is one time an Agent Studio flow ran, on one
        record or on its schedule; Agent Studio's Executions page lists them.
        Runs of deleted flows are not listed. Same access as the Executions
        page: the workspace's plan includes Agent Studio (else 403 not_entitled)
        and the person's role can open Agent Studio, admins and builders (else
        403 insufficient_scope).
      operationId: automations_list_runs
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            default: 25
            maximum: 100
            minimum: 1
            type: integer
        - description: '`next_cursor` from the previous page'
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
        - description: >-
            Only runs in these states (comma-separated, or repeated). Default:
            every state but queued
          explode: false
          in: query
          name: status
          required: false
          schema:
            anyOf:
              - items:
                  enum:
                    - queued
                    - running
                    - completed
                    - failed
                    - waiting
                    - awaiting_approval
                  type: string
                type: array
              - type: 'null'
            default: null
          style: form
        - description: >-
            Only runs that started at or after this, ISO 8601 (UTC when no
            offset)
          in: query
          name: since
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            default: null
        - description: Only runs that started before this, ISO 8601
          in: query
          name: until
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            default: null
        - description: Only runs on this kind of record
          in: query
          name: record_object
          required: false
          schema:
            anyOf:
              - enum:
                  - account
                  - contact
                  - opportunity
                  - project
                  - task
                  - user
                  - activity
                  - meeting
                  - warehouse_row
                  - other
                type: string
              - type: 'null'
            default: null
        - description: Only runs on the record with this id
          in: query
          name: record_id
          required: false
          schema:
            anyOf:
              - maxLength: 255
                type: string
              - type: 'null'
            default: null
        - description: >-
            Only this flow's runs, an id from GET /v1/automations/flows. An
            unknown or deleted flow is a 404
          in: query
          name: flow
          required: false
          schema:
            anyOf:
              - maxLength: 64
                type: string
              - type: 'null'
            default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunPage'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    RunPage:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AutomationRun'
          title: Data
          type: array
        has_more:
          default: false
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        summary:
          anyOf:
            - $ref: '#/components/schemas/RunSummary'
            - type: 'null'
          description: >-
            Counts over every run the filters match, not just this page. On the
            first page only (no `cursor`); null on later pages, so paging does
            not count again
      required:
        - data
      title: RunPage
      type: object
    AutomationRun:
      properties:
        app_url:
          description: The run on Agent Studio's Executions page
          title: App Url
          type: string
        flow_id:
          description: The flow it ran (GET /v1/automations/flows/{flow_id})
          title: Flow Id
          type: string
        flow_name:
          title: Flow Name
          type: string
        id:
          title: Id
          type: string
        record:
          anyOf:
            - $ref: '#/components/schemas/RunRecord'
            - type: 'null'
          description: The record it ran on; null for a run with none (a schedule)
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When it started, ISO 8601 UTC; null while queued
          title: Started At
        status:
          description: >-
            queued (waiting for a worker), running, completed, failed, waiting
            (a wait step: a sleep or an email reply) or awaiting_approval (an
            approval step)
          enum:
            - queued
            - running
            - completed
            - failed
            - waiting
            - awaiting_approval
          title: Status
          type: string
        triggered_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When it was queued, ISO 8601 UTC
          title: Triggered At
      required:
        - id
        - flow_id
        - flow_name
        - status
        - record
        - triggered_at
        - started_at
        - app_url
      title: AutomationRun
      type: object
    RunSummary:
      description: >-
        The counts above the Executions page's grid, over every run the same
        filters list.
      properties:
        awaiting_approval:
          title: Awaiting Approval
          type: integer
        completed:
          title: Completed
          type: integer
        failed:
          title: Failed
          type: integer
        flows:
          description: Distinct flows among them
          title: Flows
          type: integer
        in_progress:
          description: running, and queued when `status` asks for queued runs
          title: In Progress
          type: integer
        total:
          description: Runs the filters match, on every page
          title: Total
          type: integer
        waiting:
          title: Waiting
          type: integer
      required:
        - total
        - flows
        - completed
        - failed
        - in_progress
        - waiting
        - awaiting_approval
      title: RunSummary
      type: object
    RunRecord:
      properties:
        id:
          description: The record's id, as GET /v1/objects/<object>/records gives it
          title: Id
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: Its name; null when it has none or no longer exists
          title: Name
        object:
          description: What kind of record the run ran on
          enum:
            - account
            - contact
            - opportunity
            - project
            - task
            - user
            - activity
            - meeting
            - warehouse_row
            - other
          title: Object
          type: string
      required:
        - object
        - id
        - name
      title: RunRecord
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

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