# List Workflows

`GET /api/v1/workflows`

## Description
Retrieve all workflows in a workspace with cursor-based pagination.

## Parameters

- **workspaceId** (query) (required) — `string`: The unique identifier of the workspace.

- **folderId** (query) — `string`: Filter results to only include workflows within this folder.

- **deployedOnly** (query) — `boolean`: When true, only return workflows that have been deployed. Useful for listing workflows available for API execution.

- **limit** (query) — `integer`: Maximum number of workflows to return per page. Must be between 1 and 100.

- **cursor** (query) — `string`: Pagination cursor returned from a previous request's nextCursor field. Omit for the first page.

## Responses

### 200 — A paginated list of workflows.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "Array of workflow summary objects for the current page.",
      "items": {
        "type": "object",
        "description": "Summary representation of a workflow returned in list operations.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique workflow identifier.",
            "example": "wf_1a2b3c4d5e"
          },
          "name": {
            "type": "string",
            "description": "Human-readable workflow name.",
            "example": "Customer Support Agent"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Optional description of what the workflow does.",
            "example": "Routes incoming support tickets and drafts responses"
          },
          "color": {
            "type": "string",
            "description": "Hex color code used for the workflow icon in the dashboard (e.g., #4874ff).",
            "example": "#4874ff"
          },
          "folderId": {
            "type": "string",
            "nullable": true,
            "description": "The folder this workflow belongs to. null if at the workspace root.",
            "example": "folder_abc123"
          },
          "workspaceId": {
            "type": "string",
            "description": "The workspace this workflow belongs to.",
            "example": "ws_xyz789"
          },
          "isDeployed": {
            "type": "boolean",
            "description": "Whether the workflow is currently deployed and available for API execution.",
            "example": true
          },
          "deployedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "ISO 8601 timestamp of the most recent deployment. null if never deployed.",
            "example": "2025-06-15T10:30:00Z"
          },
          "runCount": {
            "type": "integer",
            "description": "Total number of times this workflow has been executed.",
            "example": 142
          },
          "lastRunAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "ISO 8601 timestamp of the most recent execution. null if never run.",
            "example": "2025-06-20T14:15:22Z"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the workflow was created.",
            "example": "2025-01-10T09:00:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the workflow was last modified.",
            "example": "2025-06-18T16:45:00Z"
          }
        }
      }
    },
    "nextCursor": {
      "type": "string",
      "nullable": true,
      "description": "Cursor for fetching the next page of results. null when there are no more results."
    },
    "limits": {
      "type": "object",
      "description": "Rate limit and usage information attached to the /api/v1 workflows, logs, and audit logs responses. The Execute Workflow and Get Job Status responses do not include it.",
      "properties": {
        "workflowExecutionRateLimit": {
          "type": "object",
          "description": "Current rate limit status for workflow executions.",
          "properties": {
            "sync": {
              "description": "Rate limit bucket for synchronous executions.",
              "$ref": "#/components/schemas/RateLimitBucket"
            },
            "async": {
              "description": "Rate limit bucket for asynchronous executions.",
              "$ref": "#/components/schemas/RateLimitBucket"
            }
          }
        },
        "usage": {
          "type": "object",
          "description": "Current billing period usage and plan limits.",
          "properties": {
            "currentPeriodCost": {
              "type": "number",
              "description": "Total spend in the current billing period in USD.",
              "example": 1.25
            },
            "limit": {
              "type": "number",
              "description": "Maximum allowed spend for the current billing period in USD.",
              "example": 50
            },
            "plan": {
              "type": "string",
              "description": "Your current subscription plan (e.g., free, pro, team).",
              "example": "pro"
            },
            "isExceeded": {
              "type": "boolean",
              "description": "Whether the usage limit has been exceeded. Executions may be blocked when true.",
              "example": false
            }
          }
        }
      }
    }
  }
}
```

### 400 — Invalid request parameters. Check the details array for specific validation errors.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message describing the validation failure."
    },
    "details": {
      "type": "array",
      "description": "List of specific validation errors with field-level details.",
      "items": {
        "type": "object"
      }
    }
  }
}
```

### 401 — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 429 — Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message with rate limit details."
    }
  }
}
```
