---
title: List Workflow Versions
description: List immutable workflow versions visible to the caller and inspect active and purchase pins.
source: https://www.edgaze.ai/docs/api/list-workflow-versions
section: api
---
# List Workflow Versions

> List immutable workflow versions visible to the caller and inspect active and purchase pins.

**Audience: Developers building with the Edgaze API.**

```apibar
list-workflow-versions
```

## Overview

Use this endpoint to compare the creator's active version with the version attached to a buyer's purchase. Owners see the complete history. Buyers see the versions their entitlement allows them to evaluate.

Do not assume that one workflow id always resolves to one graph. A fixed `pinnedVersionId` continues to run until the buyer accepts an update. A null pin follows `activeVersionId`.

## Authorization

Requires either `run:read` or `run:execute`.

```apiscopes
list-workflow-versions
```

## Parameters

```apiparams
list-workflow-versions
```

## Response

`updateAvailable` is true only when a buyer has a non-null purchase pin that differs from the active version. Review `releaseNotes` and refresh the workflow's input schema before changing versions.

## Edge cases

```apiedges
list-workflow-versions
```

## Related endpoints

- [Get Workflow](/docs/api/get-workflow)
- [Accept Workflow Update](/docs/api/accept-workflow-update)
- [Create Run](/docs/api/create-run)

---

## Endpoint reference
- **Method:** `GET`
- **Path:** `https://api.edgaze.ai/v1/workflows/{workflow_id}/versions`
- **Scopes:** `run:read`, `run:execute`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | Bearer token with run:read or run:execute scope. |
| `workflow_id` | path | string | yes | UUID of the workflow. |
## Example responses

### 200 Success
```json
{
  "isOwner": false,
  "activeVersionId": "8f57e8f7-7b74-4fe2-a425-722a135d93aa",
  "pinnedVersionId": "55c7d7de-34f5-416f-bb0f-e1e7192ffb08",
  "updateAvailable": true,
  "versions": [
    {
      "id": "55c7d7de-34f5-416f-bb0f-e1e7192ffb08",
      "createdAt": "2026-07-01T10:00:00.000Z",
      "releaseNotes": "Initial purchased version.",
      "isActive": false,
      "isPurchased": true
    },
    {
      "id": "8f57e8f7-7b74-4fe2-a425-722a135d93aa",
      "createdAt": "2026-07-20T10:00:00.000Z",
      "releaseNotes": "Improved output schema.",
      "isActive": true,
      "isPurchased": false
    }
  ]
}
```

### 403 Forbidden
```json
{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this workflow."
  }
}
```

### 404 Not found
```json
{
  "error": {
    "code": "not_found",
    "message": "Workflow not found."
  }
}
```

### 400 Missing workflow
```json
{
  "error": {
    "code": "missing_workflow",
    "message": "Workflow id is required."
  }
}
```

### 401 Unauthorized
```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}
```

### 500 Server error
```json
{
  "error": {
    "code": "internal_error",
    "message": "Failed to load workflow versions."
  }
}
```

## Edge cases

### Legacy follow-active purchases

A null pinnedVersionId follows the active version. updateAvailable is false because there is no fixed purchase pin to compare.

### Scope alternatives

Either run:read or run:execute authorizes this read operation.