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

# Create a new runbook run

`POST /runbook-runs/create/v1`

## Request

- Base URL: `https://demo.octopus.app/api`
- URL: `https://demo.octopus.app/api/runbook-runs/create/v1`
- Auth: one of:
  - API key in header `X-Octopus-ApiKey`
  - API key in query parameter `ApiKey`
  - API key in header `X-NuGet-ApiKey`

## 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.dev/octopus/apis/octopus-server-api.md) - [All operations](https://skmtc.dev/octopus/apis/octopus-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octopus/apis/octopus-server-api/revisions/fe937c07da34?raw)