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

# List Workflows

> The workflows the caller can see, ordered and filtered server-side.

Sorting and the status/tag/favourite filters depend on facts outside the
workflows collection (run history, cost, the caller's preferences), so the
whole visible scope is read, enriched, filtered and ordered before the
requested page is cut. Visible scopes are small (an organization's
workflows), which keeps this cheaper than a multi-collection aggregation.

API key permission: Agents (Admin also opens it).



## OpenAPI

````yaml /api-reference/openapi.json get /workflows/list
openapi: 3.1.0
info:
  title: Neural Factory API
  version: 0.1.0
  description: >-
    The endpoints a program can call with an API key. Exchange the key's secret
    for a token at POST /apikeys/token and send it as a Bearer token.
servers:
  - url: https://api.neuralfactory.ai
    description: SaaS
  - url: https://{apiHost}
    description: 'Enterprise: the API address of your own deployment'
    variables:
      apiHost:
        default: api.example.com
        description: Your deployment's API host
security:
  - bearerAuth: []
tags:
  - name: API keys
  - name: Chat
  - name: Runs
  - name: Agents
  - name: Workflows
  - name: Schedules
  - name: Knowledge bases
  - name: Documents
  - name: Search
  - name: Skills
  - name: Toolkits
  - name: Files
  - name: Interactions
  - name: Usage and billing
  - name: Catalogue
  - name: Browser
  - name: Users
  - name: Groups
  - name: Builds
paths:
  /workflows/list:
    get:
      tags:
        - Workflows
      summary: List Workflows
      description: >-
        The workflows the caller can see, ordered and filtered server-side.


        Sorting and the status/tag/favourite filters depend on facts outside the

        workflows collection (run history, cost, the caller's preferences), so
        the

        whole visible scope is read, enriched, filtered and ordered before the

        requested page is cut. Visible scopes are small (an organization's

        workflows), which keeps this cheaper than a multi-collection
        aggregation.


        API key permission: Agents (Admin also opens it).
      operationId: list_workflows_workflows_list_get
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            title: Page
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Page Size
        - name: search
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Search
        - name: sort_by
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              name, last_run, run_count, cost_30d, created_by_email or
              updated_at
            title: Sort By
          description: name, last_run, run_count, cost_30d, created_by_email or updated_at
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            pattern: ^(asc|desc)$
            default: desc
            title: Sort Order
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: pending_approval or failing
            title: Status
          description: pending_approval or failing
        - name: tag
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Only workflows carrying this tag
            title: Tag
          description: Only workflows carrying this tag
        - name: favourites_only
          in: query
          required: false
          schema:
            type: boolean
            description: Only the caller's favourite workflows
            default: false
            title: Favourites Only
          description: Only the caller's favourite workflows
        - name: env
          in: query
          required: false
          schema:
            title: Env
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WorkflowList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WorkflowEntry'
          type: array
          title: Items
        meta:
          additionalProperties: true
          type: object
          title: Meta
        available_tags:
          items:
            type: string
          type: array
          title: Available Tags
      type: object
      required:
        - items
        - meta
      title: WorkflowList
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WorkflowEntry:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        version:
          type: string
          title: Version
          default: 1.0.0
        status:
          type: string
          title: Status
          default: active
        step_count:
          type: integer
          title: Step Count
          default: 0
        steps:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Steps
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
        output_schema:
          additionalProperties: true
          type: object
          title: Output Schema
        error_handling:
          additionalProperties: true
          type: object
          title: Error Handling
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        toolkits:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Toolkits
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_by_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By Email
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
        visibility:
          type: string
          title: Visibility
          default: private
        allowed_groups:
          items:
            type: string
          type: array
          title: Allowed Groups
        allowed_user_ids:
          items:
            type: string
          type: array
          title: Allowed User Ids
        revision:
          type: integer
          title: Revision
          default: 1
        edit_seq:
          type: integer
          title: Edit Seq
          default: 0
        published_revision:
          anyOf:
            - type: integer
            - type: 'null'
          title: Published Revision
        from_use_case:
          anyOf:
            - $ref: '#/components/schemas/FromUseCase'
            - type: 'null'
        governance_warnings:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Governance Warnings
        last_run:
          anyOf:
            - $ref: '#/components/schemas/WorkflowLastRun'
            - type: 'null'
        run_count:
          type: integer
          title: Run Count
          default: 0
        pending_approvals:
          type: integer
          title: Pending Approvals
          default: 0
        last_run_execution_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Run Execution Id
        recent_statuses:
          items:
            type: string
          type: array
          title: Recent Statuses
        cost_30d:
          anyOf:
            - type: number
            - type: 'null'
          title: Cost 30D
        tags:
          items:
            type: string
          type: array
          title: Tags
        is_favourite:
          type: boolean
          title: Is Favourite
          default: false
      type: object
      required:
        - id
        - name
      title: WorkflowEntry
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FromUseCase:
      properties:
        id:
          type: string
          title: Id
        version:
          type: integer
          title: Version
      type: object
      required:
        - id
        - version
      title: FromUseCase
      description: >-
        The use case an agent or a workflow was activated from, and the artifact
        version copied.
    WorkflowLastRun:
      properties:
        status:
          type: string
          title: Status
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
      type: object
      required:
        - status
      title: WorkflowLastRun
      description: Most recent execution summary shown on the workflows list (B1).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The access_token returned by POST /apikeys/token for an API key's
        secret.

````

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