Enrollment Campaigns Api Cancel Campaign

Enrollment Campaigns Api Cancel Campaign
Cancel an enrollment campaign

Cancels the campaign. Requires the ADMIN role.

Request
URI
POST
https://{api_host}/api/v1/hypervisors/campaigns/{id}/cancel
COPY
Path Parameters
integer
id
Required  

Campaign id

id example
1

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The campaign after the action

Returns CampaignSummaryDto of type(s) application/json
{
    "campaignId": 1,
    "name": "Enroll Production Cluster",
    "scopeType": "CLUSTER",
    "vcenterConnectionId": "db-1",
    "clusterMoRef": "domain-c8",
    "status": "CANCELLED",
    "totalHosts": 3,
    "enrolledHosts": 2,
    "failedHosts": 0,
    "inProgressHosts": 1,
    "concurrencyLimit": 5,
    "securityGroupId": 1,
    "createdAt": "2026-01-15T09:30:00Z",
    "startedAt": "2026-01-15T09:31:00Z",
    "completedAt": "2026-01-15T09:40:00Z",
    "progressPercent": 67
}
integer As int64 As int64
campaignId
Required  

Identifier of the campaign, assigned when it is created

string
name
Required  

Name given at creation, stored trimmed; an automatic campaign is named 'Auto Enrollment - ' followed by the vCenter display name and the creation time

string
scopeType
Required  

Which hosts a campaign targets.

  • FLEET: All registered hosts are resolved as targets, but each job fails with 'Fleet-wide enrollment is not supported' and nothing is enrolled; also the default of the stored campaign
  • VCENTER: The hosts of the vCenter connection named in vcenterConnectionId; a job runs only while that vCenter has Auto Enrollment enabled and otherwise fails
  • CLUSTER: The hosts whose parentLocator equals clusterMoRef
  • SELECTION: The hosts named in hypervisorPks
  • AUTO_DISCOVERY: Created by the Console for a vCenter with Auto Enrollment enabled; its jobs wait while automatic enrollment is paused
Enumeration: FLEET, VCENTER, CLUSTER, SELECTION, AUTO_DISCOVERY
string
vcenterConnectionId
Optional

Identifier of the vCenter connection given at creation: it selects the hosts of a VCENTER campaign and is the vCenter of an AUTO_DISCOVERY campaign; null when none was given

string
clusterMoRef
Optional

Cluster identifier given at creation; a CLUSTER campaign targets the hosts whose parentLocator equals it; null when none was given

string
status
Required  

Campaign state.

  • CREATED: The campaign exists and has not been started, which is the case for autoStart false
  • RUNNING: Jobs are being worked; set at creation with autoStart, by the start and resume operations, and for an automatic campaign at creation
  • PAUSED: Paused by the pause operation, which accepts only a RUNNING campaign; jobs are not worked until it is resumed
  • COMPLETED: Every host has a result and at least one was enrolled, or no host needed enrolling at creation
  • CANCELLED: Cancelled by the cancel operation or by the removal of its vCenter; its queued jobs are cancelled
  • FAILED: Every host has a result and none was enrolled
Enumeration: CREATED, RUNNING, PAUSED, COMPLETED, CANCELLED, FAILED
integer As int32 As int32
totalHosts
Required  

Number of hosts the campaign has to enroll, one per queued job; hosts that were already ENROLLED at creation are not counted, and an AUTO_DISCOVERY campaign adds to it as jobs are appended

integer As int32 As int32
enrolledHosts
Required  

Number of hosts whose enrollment job completed successfully

integer As int32 As int32
failedHosts
Required  

Number of hosts whose enrollment job ended in a permanent failure; retrying the failed jobs lowers it

integer As int32 As int32
inProgressHosts
Required  

Number of enrollment jobs that have started and have not yet completed, failed permanently or been queued for a retry

integer As int32 As int32
concurrencyLimit
Required  

Most jobs of one vCenter that may be started at the same time for this campaign; set from the request (5 when absent or not above 0), and for an automatic campaign from the maxConcurrentPerVcenter setting

integer As int64 As int64
securityGroupId
Optional

Identifier of the Security Group given when the campaign was created; null when none was given

string As date-time As date-time
createdAt
Required  

Time the campaign was created

string As date-time As date-time
startedAt
Optional

Time the campaign was first started, at creation when autoStart applies or by the start operation; null while it has not been started

string As date-time As date-time
completedAt
Optional

Time the campaign reached COMPLETED, FAILED or CANCELLED, including a campaign that found no host to enroll at creation; null otherwise

integer As int32 As int32
progressPercent
Required  

Share of totalHosts that has finished, enrolled or failed, as a whole percentage rounded and capped at 100; 0 when totalHosts is 0


400

400 Bad Request: INVALID_ARGUMENT when the id path variable is not a number

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: CAMPAIGN_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' https://{api_host}/api/v1/hypervisors/campaigns/{id}/cancel