# Get a version

**GET** `/api/workflows/{id}/versions/{versionId}`

Returns one published version, with the exact tree it ran.

Needs [an API token](https://docs.gorunner.io/api/authentication#scopes) with the **Read** permission for workflows (`workflow:read`).

## Parameters

### Path

- `id` · Required · UUID: The workflow’s ID.
- `versionId` · Required · UUID: The version’s ID, from List versions or the workflow’s `latestVersionId`.

## Use it

Run a version as it ran with [Run a workflow](https://docs.gorunner.io/api/runs/run-workflow) and `versionId`, or bring it back into the draft with [Go back to a version](https://docs.gorunner.io/api/publish/restore-workflow-version).

Here `onCanvas` is always `false`: only the list works it out.

## Responses

- 200 OK

  The version and its tree.

- 400 `VALIDATION_ERROR`

  `id` or `versionId` isn’t a UUID.

- 403 `FORBIDDEN`

  The token lacks the **Read** permission for workflows.

- 404 `NOT_FOUND`

  No such workflow in the workspace, or no such version of it.

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`403 FEATURE_OFF`](https://docs.gorunner.io/errors#FEATURE_OFF) · [`403 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`403 ACCOUNT_SUSPENDED`](https://docs.gorunner.io/errors#ACCOUNT_SUSPENDED) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 BUSY`](https://docs.gorunner.io/errors#BUSY) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Request

**curl**

```bash
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for workflows
WORKFLOW_ID="your-workflow-id"
VERSION_ID="your-version-id"  # from List versions

URL="$GORUNNER/api/workflows/$WORKFLOW_ID/versions/"
URL="${URL}$VERSION_ID"
curl "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"
```

**JavaScript**

```js
const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const WORKFLOW_ID = process.env.WORKFLOW_ID;
const VERSION_ID = process.env.VERSION_ID; // from List versions

const res = await fetch(
  `${GORUNNER}/api/workflows/${WORKFLOW_ID}/` +
    `versions/${VERSION_ID}`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
WORKFLOW_ID = os.environ["WORKFLOW_ID"]
VERSION_ID = os.environ["VERSION_ID"]  # from List versions

res = requests.get(
    f"{GORUNNER}/api/workflows/{WORKFLOW_ID}/"
    f"versions/{VERSION_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
```

Response · 200 OK, shortened

```json
{
  "data": {
    "id": "f20f671a-2c8e-4b9d-a7f1-6e3b0d5c9a12",
    "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
    "versionNumber": 3,
    "definition": {
      "schemaVersion": 2,
      "trigger": {
        "name": "trigger",
        "displayName": "Order received",
        "type": "webhook",
        "pieceId": "webhook",
        "pieceVersion": "1.0.0",
        "actionId": "catch_webhook",
        "config": {
          "methods": [
            "POST"
          ]
        },
        "valid": true,
        "nextAction": {
          "name": "forward",
          "displayName": "Forward to fulfilment",
          "type": "PIECE",
          "pieceId": "http",
          "pieceVersion": "1.0.0",
          "actionId": "send_request",
          "config": {
            "method": "POST",
            "url": "https://example.com/fulfilment",
            "body_type": "json",
            "body_json": "{{trigger.body}}"
          },
          "valid": true
        }
      },
      "settings": {}
    },
    "publishedBy": "5d8e1f3a-0b6c-4e2d-9f7a-1c3b5e8d2a40",
    "changeMessage": "",
    "createdAt": "2026-10-24T16:41:00Z",
    "onCanvas": false
  }
}
```

**Every field**

It takes no body.

### Response · 200 OK

- `data` · object: An immutable published snapshot.
  - `id` · UUID
  - `workflowId` · UUID
  - `versionNumber` · integer: 1-based, increasing.
  - `definition` · object: OMITTED from the versions LIST; present on the single-version read. A workflow definition: its fields are in [Workflow definition](https://docs.gorunner.io/api/workflow-definition).
  - `publishedBy` · UUID: Who published it (a user id). Absent — never null — when a machine principal or the dev principal published it: a version names a person or nobody.
  - `changeMessage` · string: Kept for old clients: nothing writes it, so it is empty. `change.summary` (on the list) says what changed.
  - `createdAt` · time
  - `onCanvas` · boolean: Marks the AT MOST ONE version whose snapshot equals the current DRAFT. Computed only by the LIST (`false` on a single read). Distinct from LIVE, which is the workflow’s `latestVersionId`.
  - `change` · object: LIST only: what this version changed against the one before it, keyed on step name, as the list shows it. Absent on the single-version read, and on the last row of a page when the version before it is not in hand.
    - `first` · boolean: The first version: nothing to compare with.
    - `added` · array of strings: Steps added, by display name, in canvas order.
    - `removed` · array of strings: Steps removed, by display name.
    - `changed` · array of strings: Steps changed, by display name.
    - `trigger` · string: How the way it starts changed, in words ("Webhook replaced Schedule", "Webhook reconfigured"); absent when it did not.
    - `settings` · boolean: The workflow-level settings changed (timeout, concurrency, error workflow).
    - `summary` · string: The one-line form the row shows.

Related: [List versions](https://docs.gorunner.io/api/publish/list-workflow-versions) · [Go back to a version](https://docs.gorunner.io/api/publish/restore-workflow-version)

Source: https://docs.gorunner.io/api/publish/get-workflow-version