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

# List workflows

> Returns the workflows in the caller's account, honoring the optional filters, sort and
pagination. Deleted workflows are excluded by default; pass deleted=true to list them, or deletedAfter to list those deleted since a point in time.
Work-app flows, table automations, connector-internal flows and business rules are not
workflows in this sense and never appear here. An API key pinned to a workspace and environment
lists only that scope's workflows and, with role-based access control on, only those its owner
was granted plus public ones; other credentials list the whole account without the role-based
filter.
            
Results are ordered by workflowId descending unless sort says otherwise. Note
that updatedAt moves when the workflow is enabled or disabled, so paging under that sort
while also updating workflows is not stable.



## OpenAPI

````yaml /developers/api-reference/openapi.json get /v1/workflows
openapi: 3.0.0
info:
  title: Engini API
  version: v1
  description: The Engini public API.
servers:
  - url: https://api.engini.io
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Auth
    description: Identify the caller a Developer API request is authenticated as.
  - name: On-prem agents
    description: >-
      Provision and manage agents that run Engini tasks inside a customer's
      network.
  - name: Applications
    description: >-
      Discover the applications (toolkits) available in Engini and their
      connection requirements.
  - name: Tools
    description: Browse and execute the tools exposed by Engini applications.
  - name: Toolsets
    description: Manage toolsets - named groupings of connections and tools.
  - name: McpServers
    description: >-
      Inspect and maintain MCP servers - the account-wide endpoints that expose
      Engini tools and workflows over the Model Context Protocol. Distinct from
      the MCPClient connection kind, which is Engini consuming a third-party MCP
      server.
  - name: Connections
    description: >-
      Manage connections to applications, including OAuth sign-in and
      default-connection selection.
  - name: Folders
    description: >-
      List the folders that organize workflows in each workspace and
      environment.
  - name: Workflows
    description: >-
      List workflows, and build them from a plan: search the catalog, read
      schemas and options, compile, create and update.
  - name: Executions
    description: >-
      Read execution history for workflows, table automations and app business
      rules, including per-step logs and recorded payloads.
  - name: Triggers
    description: >-
      Create triggers that fire when something changes in a connected app, and
      manage the destinations their events are delivered to.
paths:
  /v1/workflows:
    get:
      tags:
        - Workflows
      summary: List workflows
      description: >-
        Returns the workflows in the caller's account, honoring the optional
        filters, sort and

        pagination. Deleted workflows are excluded by default; pass deleted=true
        to list them, or deletedAfter to list those deleted since a point in
        time.

        Work-app flows, table automations, connector-internal flows and business
        rules are not

        workflows in this sense and never appear here. An API key pinned to a
        workspace and environment

        lists only that scope's workflows and, with role-based access control
        on, only those its owner

        was granted plus public ones; other credentials list the whole account
        without the role-based

        filter.
                    
        Results are ordered by workflowId descending unless sort says otherwise.
        Note

        that updatedAt moves when the workflow is enabled or disabled, so paging
        under that sort

        while also updating workflows is not stable.
      operationId: Workflows_ListWorkflows
      parameters:
        - name: name
          in: query
          description: Optional substring match on the workflow name.
          schema:
            type: string
            nullable: true
          x-position: 1
        - name: folderName
          in: query
          description: Optional substring match on the containing folder's name.
          schema:
            type: string
            nullable: true
          x-position: 2
        - name: folderId
          in: query
          description: >-
            Optional filter to one folder, by the id GET /v1/folders returns.
            Pass 0 for workflows in no folder. Combines with folderName.
          schema:
            type: integer
            format: int32
            nullable: true
          x-position: 3
        - name: enabled
          in: query
          description: Optional filter on whether the workflow is enabled.
          schema:
            type: boolean
            nullable: true
          x-position: 4
        - name: blocked
          in: query
          description: Optional filter on whether the workflow is blocked from running.
          schema:
            type: boolean
            nullable: true
          x-position: 5
        - name: deleted
          in: query
          description: Whether to return soft-deleted workflows. Defaults to false.
          schema:
            type: boolean
            nullable: true
          x-position: 6
        - name: deletedAfter
          in: query
          description: >-
            Optional inclusive lower bound on the deletion timestamp. Implies
            deleted=true; combining it with deleted=false is a 400. Workflows
            deleted through the legacy Solutions route before this release have
            no deletion timestamp and never match.
          schema:
            type: string
            format: date-time
            nullable: true
          x-position: 7
        - name: type
          in: query
          description: Optional trigger-type filter.
          schema:
            type: string
            nullable: true
            enum:
              - instant
              - automated
              - scheduled
              - workflowMCPTool
              - onRefreshObjectList
              - onRefreshObject
              - onSaveSelectedObjects
              - onActivityExecute
              - onBeforeRequest
          x-position: 8
        - name: connectionId
          in: query
          description: Optional filter to workflows with a step using this connection.
          schema:
            type: integer
            format: int32
            nullable: true
          x-position: 9
        - name: createdBy
          in: query
          description: Optional account-user id filter on who created the workflow.
          schema:
            type: integer
            format: int32
            nullable: true
          x-position: 10
        - name: updatedBy
          in: query
          description: Optional account-user id filter on who last updated the workflow.
          schema:
            type: integer
            format: int32
            nullable: true
          x-position: 11
        - name: updatedAfter
          in: query
          description: Optional inclusive lower bound on the last-updated timestamp.
          schema:
            type: string
            format: date-time
            nullable: true
          x-position: 12
        - name: updatedBefore
          in: query
          description: Optional inclusive upper bound on the last-updated timestamp.
          schema:
            type: string
            format: date-time
            nullable: true
          x-position: 13
        - name: lastRunAfter
          in: query
          description: Optional inclusive lower bound on the last-run timestamp.
          schema:
            type: string
            format: date-time
            nullable: true
          x-position: 14
        - name: lastRunBefore
          in: query
          description: Optional inclusive upper bound on the last-run timestamp.
          schema:
            type: string
            format: date-time
            nullable: true
          x-position: 15
        - name: sort
          in: query
          description: >-
            Optional sort over workflowId, name, updatedAt, lastRunAt.
            Comma-separated keys, each "field asc" or "field desc", highest
            priority first - e.g. "name asc,updatedAt desc". At most 3 keys; a
            field may appear once; every key needs an explicit direction when
            there is more than one; nothing may follow workflowId. A single key
            may omit the direction: workflowId then sorts descending, any other
            field ascending. Defaults to workflowId desc.
          schema:
            type: string
            nullable: true
          x-position: 16
        - name: offset
          in: query
          description: Zero-based index of the first item to return. Defaults to 0.
          schema:
            type: integer
            format: int32
            default: 0
          x-position: 17
        - name: top
          in: query
          description: Maximum number of items to return, capped at 100. Defaults to 100.
          schema:
            type: integer
            format: int32
            default: 100
          x-position: 18
      responses:
        '200':
          description: A paginated list of workflows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponseOfWorkflowPublicDTO'
        '400':
          description: Bad request - malformed body or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid bearer token or API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - the caller lacks access to the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - rate limit exceeded.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - an unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - Bearer: []
        - ApiKey: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            from engini import Engini


            client = Engini()  # reads ENGINI_API_KEY


            # one page; list_page also returns total_count. Without top, list()
            drains every match

            page = client.workflows.list_page(name="lead alert", folder_id=7,
            top=20)

            for wf in page.items:
                print(wf.workflow_id, wf.name)
        - lang: typescript
          label: TypeScript
          source: >-
            import { Engini } from "@engini/sdk";


            const client = new Engini(); // reads ENGINI_API_KEY


            // one page; listPage also returns totalCount. Without top, list()
            drains every match

            const page = await client.workflows.listPage({ name: "lead alert",
            folderId: 7, top: 20 });

            for (const wf of page.items ?? []) console.log(wf.workflowId,
            wf.name);
        - lang: bash
          label: CLI
          source: engini workflows list --name 'lead alert' --folder-id 7 --top 20
components:
  schemas:
    PaginatedResponseOfWorkflowPublicDTO:
      type: object
      description: Offset-based paginated wrapper for a list of items.
      additionalProperties: false
      required:
        - items
        - totalCount
        - offset
        - top
      properties:
        items:
          type: array
          description: The items in the current page.
          items:
            $ref: '#/components/schemas/WorkflowPublicDTO'
        totalCount:
          type: integer
          description: Total number of items available across all pages.
          format: int32
        offset:
          type: integer
          description: Number of items skipped before this page (the requested offset).
          format: int32
        top:
          type: integer
          description: Maximum number of items requested for this page.
          format: int32
    ErrorResponse:
      type: object
      description: >-
        Unified machine-readable error envelope returned by every non-200
        Developer API response.
      additionalProperties: false
      required:
        - errorCode
        - message
        - requestId
        - timestamp
      properties:
        errorCode:
          type: string
          description: Machine-readable error code identifying the failure.
        message:
          type: string
          description: Human-readable error message.
        requestId:
          type: string
          description: Identifier of the request, for support/correlation.
        timestamp:
          type: string
          description: Timestamp when the error occurred (ISO 8601).
        details:
          type: array
          description: Per-field validation details, when applicable.
          nullable: true
          items:
            $ref: '#/components/schemas/ErrorDetail'
    WorkflowPublicDTO:
      type: object
      description: Public shape of a workflow, as returned by GET /v1/workflows.
      additionalProperties: false
      required:
        - workflowId
        - name
        - type
        - enabled
        - deleted
        - blocked
        - consecutiveFailures
        - maxConsecutiveFailures
        - createdAt
        - createdBy
        - historyRetentionDays
        - workflowConcurrency
        - applyConcurrencyLimitOnWaitingWorkflow
        - stepsCount
        - connections
      properties:
        workflowId:
          type: integer
          description: Identifier of the workflow.
          format: int32
        workspace:
          description: >-
            The workspace the workflow belongs to; omitted for a row that
            predates workspaces.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/WorkspaceRefPublicDTO'
        environment:
          description: >-
            The environment (of Workspace) the workflow belongs to; omitted for
            a row that predates workspaces.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/EnvironmentRefPublicDTO'
        slug:
          type: string
          description: >-
            Canonical slug of the workflow. This is the identifier the /v1/tools
            surface addresses a

            workflow-backed tool by, so it is what joins a tool back to its
            workflow. Omitted when the

            workflow has no slug (only workflow-backed MCP tools are assigned
            one).
          nullable: true
        name:
          type: string
          description: Display name of the workflow.
        folderName:
          type: string
          description: >-
            Name of the folder the workflow lives in; omitted when it is not in
            a folder.
          nullable: true
        folderId:
          type: integer
          description: >-
            Identifier of the folder the workflow lives in (see GET
            /v1/folders); omitted when it is not

            in a folder. Prefer it over FolderName for joins: names are unique
            only within

            one workspace + environment.
          format: int32
          nullable: true
        type:
          type: string
          description: >-
            Trigger type of the workflow. A type this API version does not
            publish is returned in the

            escape form "unknown:{id}" rather than being dropped, so a workflow
            created by a newer

            release is still identifiable rather than appearing to have no
            trigger.
        enabled:
          type: boolean
          description: Whether the workflow is enabled and will run when triggered.
        deleted:
          type: boolean
          description: >-
            Whether the workflow has been deleted. Deleted workflows are
            excluded from

            GET /v1/workflows by default and returned when the caller passes
            deleted=true.
        deletedAt:
          type: string
          description: >-
            When the workflow was deleted (UTC). Omitted entirely - not null -
            for a workflow that has

            not been deleted.
          format: date-time
          nullable: true
        deletedBy:
          description: >-
            The account user who deleted the workflow. Omitted entirely for a
            workflow that has not been

            deleted, and for a system delete.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/AccountUserRefPublicDTO'
        blocked:
          type: boolean
          description: Whether the workflow is blocked from running.
        blockReason:
          type: string
          description: >-
            Why the workflow is blocked: maxConsecutiveFailures, creditLimit or
            manualBlock.

            Omitted when the workflow is not blocked - never returned as "none".
          nullable: true
        blockedDate:
          type: string
          description: When the workflow was blocked (UTC); omitted when it is not blocked.
          format: date-time
          nullable: true
        consecutiveFailures:
          type: integer
          description: >-
            Number of consecutive failed runs so far. Together with
            MaxConsecutiveFailures

            this lets an integrator alert before a workflow is blocked rather
            than after.
          format: int32
        maxConsecutiveFailures:
          type: integer
          description: Number of consecutive failures after which the workflow is blocked.
          format: int32
        createdAt:
          type: string
          description: When the workflow was created (UTC).
          format: date-time
        createdBy:
          description: The account user who created the workflow.
          oneOf:
            - $ref: '#/components/schemas/AccountUserRefPublicDTO'
        updatedAt:
          type: string
          description: >-
            When the workflow was last updated (UTC); omitted when it has never
            been updated. Note that

            PUT /v1/workflows/{workflowId}/enabled counts as an update and moves
            this timestamp.
          format: date-time
          nullable: true
        updatedBy:
          description: >-
            The account user who last updated the workflow; omitted when the
            workflow has never been

            updated or the stored row has no valid updater.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/AccountUserRefPublicDTO'
        lastRunAt:
          type: string
          description: When the workflow last ran (UTC); omitted when it has never run.
          format: date-time
          nullable: true
        nextRun:
          type: string
          description: >-
            Next scheduled run (UTC); omitted for workflows that are not
            scheduled.
          format: date-time
          nullable: true
        historyRetentionDays:
          type: integer
          description: Number of days execution history is retained for this workflow.
          format: int32
        workflowConcurrency:
          type: integer
          description: >-
            Maximum number of executions of this workflow allowed to run at the
            same time.

            Read together with ApplyConcurrencyLimitOnWaitingWorkflow, which
            changes what

            this limit counts.
          format: int32
        applyConcurrencyLimitOnWaitingWorkflow:
          type: boolean
          description: >-
            Whether executions that are waiting (for example on a delay) count
            towards

            WorkflowConcurrency.
        description:
          type: string
          description: >-
            Description of the workflow; omitted when not set. Read-only in v1 -
            it cannot be changed

            through the public API.
          nullable: true
        stepsCount:
          type: integer
          description: Number of designer steps in the workflow.
          format: int32
        connections:
          type: array
          description: Connections used by the workflow's steps, deduplicated.
          items:
            $ref: '#/components/schemas/WorkflowConnectionPublicDTO'
    ErrorDetail:
      type: object
      description: A single field-level error detail within an ErrorResponse.
      additionalProperties: false
      required:
        - field
        - issue
      properties:
        field:
          type: string
          description: Name of the field the issue relates to.
        issue:
          type: string
          description: Description of the issue with the field.
    WorkspaceRefPublicDTO:
      type: object
      description: >-
        The workspace a /v1 item belongs to, as it appears in the item's
        workspace member.
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          description: Identifier of the workspace.
          format: uuid
        name:
          type: string
          description: >-
            Display name of the workspace; null for an API key, for a workspace
            the caller cannot open, and when the name could not be read.
          nullable: true
    EnvironmentRefPublicDTO:
      type: object
      description: >-
        The environment a /v1 item belongs to, as it appears in the item's
        environment member. Same rules as

        WorkspaceRefPublicDTO: Name and Type are null whenever the name is.
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: string
          description: Identifier of the environment.
          format: uuid
        name:
          type: string
          description: >-
            Display name of the environment; null when the caller cannot be
            shown it.
          nullable: true
        type:
          type: string
          description: >-
            Kind of environment: Production, Staging or Development; null when
            the name is.
          nullable: true
    AccountUserRefPublicDTO:
      type: object
      description: >-
        Reference to an account user. When present, emitted as an object rather
        than a bare identifier,

        so a consumer never has to make a second call to turn an id into
        something displayable.
      additionalProperties: false
      required:
        - id
      properties:
        id:
          type: integer
          description: Identifier of the account user.
          format: int32
        name:
          type: string
          description: >-
            Display name of the account user, or null when the name could not be
            resolved (for

            example while the user directory is unavailable). The object itself
            is never omitted.
          nullable: true
    WorkflowConnectionPublicDTO:
      type: object
      description: A connection used by one or more of a workflow's steps.
      additionalProperties: false
      required:
        - connectionId
        - connectionName
        - applicationName
      properties:
        connectionId:
          type: integer
          description: Identifier of the connection.
          format: int32
        connectionName:
          type: string
          description: Display name of the connection.
        applicationSlug:
          type: string
          description: >-
            Slug of the connection's application. Omitted when the application
            is outside the public

            catalog, which is the only case in which it has no slug - it never
            falls back to an

            internal application identifier.
          nullable: true
        applicationName:
          type: string
          description: Display name of the connection's application.
  securitySchemes:
    Bearer:
      type: http
      description: Enter your JWT token
      scheme: bearer
      bearerFormat: JWT
    ApiKey:
      type: apiKey
      description: >-
        Opaque Developer API key (prefix `eng_`). Authenticates as the key's
        owner and resolves the account automatically.
      name: x-api-key
      in: header

````

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