List user workflows

List workflows for the authenticated user with optional search and filtering.

Features:

Paginated results with cursor-based pagination
Search by workflow name or title
Filter by model endpoints used in the workflow

Authentication: Required. Returns only workflows owned by the authenticated user.

Common Use Cases:

Display user’s workflow library
Search for specific workflows
Find workflows using particular models

Required permissions: workflows:read. Key presets that include them: API, SERVERLESS, READONLY, FULL. See key permissions.

GET

workflows

List user workflows

curl --request GET \
  --url https://api.fal.ai/v1/workflows \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/workflows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "workflows": [
    {
      "name": "my-image-workflow",
      "title": "My Image Generation Workflow",
      "user_nickname": "johndoe",
      "created_at": "2025-01-15T12:00:00Z",
      "thumbnail_url": "https://fal.media/files/example.jpg",
      "description": "A workflow for generating images",
      "tags": [
        "image",
        "generation"
      ],
      "endpoint_ids": [
        "fal-ai/flux/dev"
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total": 1
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the READONLY preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Query Parameters

limit

integer

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Required range: x >= 1

Example:

50

cursor

string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

string

Search by workflow name or title

Example:

"image generation"

used_endpoint_ids

Filter by model endpoint IDs used in the workflow. Can be a single value or comma-separated values.

Example:

["fal-ai/flux/dev"]

Response

Successfully retrieved workflows

Response containing workflow data with pagination support

workflows

object[]

required

Array of workflow items

Hide child attributes

workflows.name

string

required

Unique workflow name/slug within the user's namespace

Example:

"my-image-workflow"

workflows.title

string

required

Human-readable workflow title

Example:

"My Image Generation Workflow"

workflows.user_nickname

string

required

Display name/username of the owner

Example:

"johndoe"

workflows.created_at

string

required

ISO8601 timestamp of workflow creation

Example:

"2024-01-15T10:30:00Z"

workflows.tags

string[]

required

Tags associated with the workflow

Example:

["image-generation", "ai", "flux"]

workflows.endpoint_ids

string[]

required

List of model endpoint IDs used in this workflow

Example:

["fal-ai/flux/dev", "fal-ai/face-swap"]

workflows.thumbnail_url

string

URL to the workflow thumbnail image

Example:

"https://fal.ai/workflows/thumb_abc123.png"

workflows.description

string

Brief description of what the workflow does

Example:

"Generate high-quality images using FLUX model"

Example:

[
  {
    "name": "my-image-workflow",
    "title": "My Image Generation Workflow",
    "user_nickname": "johndoe",
    "created_at": "2024-01-15T10:30:00Z",
    "thumbnail_url": "https://fal.ai/workflows/thumb_abc123.png",
    "description": "Generate high-quality images using FLUX model",
    "tags": ["image-generation", "ai", "flux"],
    "endpoint_ids": ["fal-ai/flux/dev", "fal-ai/face-swap"]
  }
]

next_cursor

string | null

required

Cursor for the next page of results, null if no more pages

Example:

"eyJvZmZzZXQiOjEwfQ=="

has_more

boolean

required

Whether more results are available

Example:

true

total

integer

Total number of workflows matching the query

Example:

42

⌘I

List user workflows

curl --request GET \
  --url https://api.fal.ai/v1/workflows \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/workflows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "workflows": [
    {
      "name": "my-image-workflow",
      "title": "My Image Generation Workflow",
      "user_nickname": "johndoe",
      "created_at": "2025-01-15T12:00:00Z",
      "thumbnail_url": "https://fal.media/files/example.jpg",
      "description": "A workflow for generating images",
      "tags": [
        "image",
        "generation"
      ],
      "endpoint_ids": [
        "fal-ai/flux/dev"
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total": 1
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}