---
title: "Create a new runbook run"
method: POST
path: "/spaces/{spaceIdentifier}/runbook-runs/create/v1"
tags: ["RunbookRuns"]
---

# Create a new runbook run

`POST /spaces/{spaceIdentifier}/runbook-runs/create/v1`

## Path parameters

- `spaceIdentifier` string, required

## Request body

- CreateRunbookRunCommandV1
  - `DebugMode` string — Contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the execution. One of "None", "Log" or "Debug"; leave unset for the default of "None".
  - `DeploymentFreezeNames` string[] — Active deployment freezes to override so this execution can proceed despite them. Overriding a freeze bypasses a deliberate block on deploying, so only set this when explicitly asked to. Requires DeploymentFreezeOverrideReason.
  - `DeploymentFreezeOverrideReason` string — Required, and must not be blank, whenever DeploymentFreezeNames is non-empty. Recorded against the override.
  - `EnvironmentNames` string[], required
  - `ExcludedMachineNames` string[] — A collection of machines in the target environment that should be excluded from the deployment.
  - `ExcludedTargetTagNames` string[] — A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be excluded from the deployment.
  - `ForcePackageDownload` boolean — Whether to force downloading of already installed packages (flag, default false).
  - `NoRunAfter` string, date-time — Time at which a scheduled execution should expire if it has not started, specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Only meaningful alongside RunAt.
  - `Priority` string — Whether this execution jumps the task queue ahead of other queued tasks. One of "LifecycleDefault" (use the lifecycle's configured setting), "On" or "Off".
  - `ProjectName` string, required
  - `RunAt` string, date-time — Time at which the execution should start (scheduling it for later), specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone.
  - `RunbookName` string, required
  - `SkipStepNames` string[] — Steps that are to be skipped for this execution. A name that matches no step is logged as a warning rather than failing the command, so check the step name carefully.
  - `Snapshot` string — Name or ID of the snapshot to run. If not supplied, the command will attempt to use the published snapshot.
  - `SpaceId` string, required
  - `SpaceIdOrName` string, required — Both this and SpaceId are required, and normally hold the same space ID; set both.
  - `SpecificMachineNames` string[] — A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. A name that matches no machine fails the command.
  - `SpecificTargetTagNames` string[] — A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be included in the deployment.
  - `Tenants` string[] — The tenants to deploy.
  - `TenantTags` string[] — The tenant tags to filter tenants to deploy.
  - `UseGuidedFailure` boolean — If set to true, the deployment 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.
  - `Variables` object — Name/value pairs for prompted variables. A prompted variable that is required and has no value supplied here fails the command, naming the variable.

## Response `200`

Server tasks associated with the newly-created Runbook Run

- CreateRunbookRunResponseV1
  - `RunbookRunServerTasks` RunRunbookServerTask[], required
    - `RunbookRunId` string, required
    - `ServerTaskId` string, required

## 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)