---
title: "Run the published version of this Runbook"
method: POST
path: "/runbooks/{runbookId}/run"
tags: ["Runbooks"]
---

# Run the published version of this Runbook

`POST /runbooks/{runbookId}/run`

## Path parameters

- `runbookId` string, required

## Request body

- RunRunbookCommandV1
  - `ChangeRequestSettings` ChangeRequestSettings[] — Change Request Settings.
    - `Type` 'ServiceNow' | 'JiraServiceManagement'
  - `Comments` string — Any additional information/context
  - `DebugMode` string — If set to true contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the runbook run
  - `EnvironmentId` string — Legacy single-environment field; prefer EnvironmentIds. If set, this environment is added to the ones the runbook runs in. At least one of EnvironmentIds or EnvironmentId is required.
  - `EnvironmentIds` string[] — The environments to run the runbook in — the preferred way to specify targets, one run per environment. At least one of EnvironmentIds or EnvironmentId is required.
  - `ExcludedMachineIds` string[] — A collection of machines in the target environment that should be excluded from the runbook run.
  - `ExcludedTargetTagIds` string[] — A collection of target tag IDs that should be excluded from the deployment. Only deployment targets that have none of these tags will be deployed to. Tag IDs are in the format "TagSets-{id}/Tags-{id}".
  - `FailTargetDiscovery` boolean — Whether to skip or fail cloud discovery steps with no matching target (default false).
  - `ForcePackageDownload` boolean — Whether to force downloading of already installed packages (flag, default false).
  - `FormValues` object — Variables
  - `Priority` string
  - `ProjectId` string — ID of the project that the runbook belongs to
  - `QueueTime` string, date-time — The time to execute the runbook run
  - `QueueTimeExpiry` string, date-time — The time at which the runbook run will timeout if it has not started executing.
  - `RunbookId` string, required — ID of the runbook to run
  - `RunbookSnapshotNameOrId` string — Name or ID of a specific snapshot to run. Leave unset to run the published snapshot; when you set this, also set UseDefaultSnapshot to false.
  - `SkipActions` string[] — Actions that are to be skipped for this runbook.
  - `SpaceId` string, required — The ID of the space containing the resource(s).
  - `SpecificMachineIds` string[] — A collection of machines in the target environment that the runbook should be run on. If the collection is empty, all enabled machines are used.
  - `SpecificTargetTagIds` string[] — A collection of target tag IDs that should be included in the deployment. Only deployment targets that have at least one of these tags will be deployed to. Tag IDs are in the format "TagSets-{id}/Tags-{id}".
  - `TenantId` string — Legacy single-tenant field; prefer TenantIds. If set, this tenant is added to the ones the runbook runs for.
  - `TenantIds` string[] — The tenants to run the runbook for — the preferred way to specify tenants, creating one run per environment/tenant combination. Leave empty for an untenanted run.
  - `TenantTagNames` string[] — The tenant tags to filter tenants to run the runbook.
  - `UseDefaultSnapshot` boolean — Whether to run the runbook's published (default) snapshot. Leave true to run the published snapshot; set to false when you name a specific snapshot in RunbookSnapshotNameOrId.
  - `UseGuidedFailure` boolean — If set to true, the runbook will prompt for manual intervention (Fail/Retry/Ignore) when failures are encountered in activities that support it. May be overridden with the Octopus.UseGuidedFailure special variable.

## Response `200`

OK

## Other responses

- `400` — Bad request. Either the payload was not structurally valid or business rules did not permit the operation.
- `404` — Not found. One or more of the entities involved in the operation was not found.

---

[API](https://skmtc.net/octopus/apis/octopus-server-api.md) · [All operations](https://skmtc.net/octopus/apis/octopus-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octopus/octopus-server-api/revisions/b296c3a60aa5/schema)