> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/rest-api-reference/workflows/list-workflow-runs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# List workflow runs

GET https://api.videogen.io/v1/workflows/runs

List workflow runs started via the API, most recently created first. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all runs for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide.

Reference: https://docs.videogen.io/rest-api-reference/workflows/list-workflow-runs

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Query parameters

- `limit` (integer, optional, default: 50) — Maximum number of items to return in the page. Defaults to 50; capped at 200. See [Pagination](/pagination).
- `cursor` (string, optional) — Opaque pagination cursor returned as `nextCursor` by the previous page. Omit on the first request. Cursors are tied to the endpoint that produced them and must be passed unmodified. See [Pagination](/pagination).
- `selfOnly` (boolean, optional, default: false) — When true, returns only items created by the API key's owner. When false (default), returns all items accessible to the team.

## Response

### 200

Paginated list of workflow runs.

- `workflowRuns` (list of WorkflowRun, required)
- `hasMore` (boolean, required) — When true, there are more runs available. Pass `nextCursor` as the `cursor` query param to fetch the next page.
- `nextCursor` (string, required, nullable) — Opaque cursor to fetch the next page. `null` when `hasMore` is false.

## Types

### WorkflowRun

- `workflowRunId` (string, required) — Opaque workflow run id.
- `status` (enum, required) — Lifecycle status shared by every asynchronous job (tool executions, workflow runs, remix actions, project exports, and timeline interchange jobs). `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal.
  - Allowed values: `pending`, `running`, `succeeded`, `failed`, `cancelled`
- `workflowType` (enum, required) — Workflow type identifier.
  - Allowed values: `SCRIPT_TO_VIDEO`, `VOICEOVER_TO_VIDEO`, `SLIDESHOW_TO_VIDEO`, `STORYBOARD_TO_VIDEO`, `PROMPT_TO_VIDEO_CLIP`
- `progressPercentage` (double, required) — Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`.
- `attemptIndex` (integer, required) — Zero-based index of the current or most recent execution attempt.
- `projectId` (string, required) — Id of the project created for this workflow run (e.g. `vg_proj_...`).
- `projectUrl` (string, required) — Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.
- `error` (ApiError, required, nullable) — Error details. Always present as a field; `null` unless `status` is `failed`.
- `exportId` (string, required, nullable) — Opaque export id (e.g. `vg_expo_...`) when this run was started with `autoExport: true` and the export succeeded. Always present as a field; `null` otherwise.
- `downloadUrl` (string, required, nullable) — Private signed MP4 download URL when `autoExport` succeeded. Always present as a field; `null` otherwise. Valid for 7 days from when it was signed. This endpoint re-signs the URL when it is within an hour of expiring.
- `downloadUrlExpiresAt` (integer, required, nullable) — Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` while `downloadUrl` is null.
- `thumbnailUrl` (string, required, nullable) — Private signed thumbnail URL when `autoExport` succeeded. Always present as a field; `null` otherwise (and when no thumbnail is available). Re-signed automatically on the same terms as `downloadUrl`.
- `thumbnailUrlExpiresAt` (integer, required, nullable) — Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` while `thumbnailUrl` is null.
- `exportFileId` (string, required, nullable) — File id (e.g. `vg_file_...`) of the rendered MP4 when `autoExport` succeeded. Always present as a field; `null` otherwise. Pass it to `POST /v1/files/{fileId}/hydrate` for a fresh signed URL.

### ApiError

Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details: - `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error. Common `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.

- `message` (string, required) — Human-readable error description. For display and logging only; do not branch on its exact text.
- `code` (string, optional, nullable) — Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies.
- `requirement` (ErrorRequirement, optional, nullable) — What is needed to resolve the error. Present when the error can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on); `null` otherwise.
- `internalErrorCode` (string, optional, nullable) — Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable.

### ErrorRequirement

What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).

- `type` (string, required) — Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`).
- `details` (map from string to string, optional) — Key-value pairs with requirement-specific context (e.g. the add-on id to purchase).

## Examples

**Response**

```json
{
  "workflowRuns": [
    {
      "workflowRunId": "string",
      "status": "pending",
      "workflowType": "SCRIPT_TO_VIDEO",
      "progressPercentage": 1.1,
      "attemptIndex": 1,
      "projectId": "string",
      "projectUrl": "string",
      "error": {
        "message": "string",
        "code": "string",
        "requirement": {
          "type": "string",
          "details": {}
        },
        "internalErrorCode": "string"
      },
      "exportId": "string",
      "downloadUrl": "string",
      "downloadUrlExpiresAt": 1,
      "thumbnailUrl": "string",
      "thumbnailUrlExpiresAt": 1,
      "exportFileId": "string"
    }
  ],
  "hasMore": true,
  "nextCursor": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.videogen.io/v1/workflows/runs"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

> HTTP API with TypeScript and Python SDKs for generating image, video, and audio assets with VideoGen.