Skip to content
Praxrr

Canary rollout detail

GET
/canary/rollouts/{id}
curl --request GET \
  --url https://example.com/api/v1/canary/rollouts/1

Returns one rollout with its full state: canary diagnostics, remaining targets, per-instance rollout results, durable remaining-preview evidence, and the current stateToken used to guard proceed/abort. Legacy, corrupt, partial, or target-mismatched evidence is returned as safely unavailable rather than as an empty successful preview.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
integer

Responses

Section titled “Responses”

200

Section titled “200”

Canary rollout detail

Media typeapplication/json
object
id
required
integer
arrType
required

Arr family a rollout is scoped to. A rollout never spans types.

string
Allowed values: radarr sonarr lidarr
status
required

Live state machine of a staged rollout:

  • canary_running: canary sync is executing inline
  • awaiting_confirmation: canary passed, waiting at the verification gate
  • rolling_out: batched rollout job is syncing remaining instances
  • completed: all remaining instances synced cleanly
  • aborted: gate declined, or canary failed/partial-abort/skipped (remaining untouched)
  • failed: rollout ran but one or more remaining instances failed
string
Allowed values: canary_running awaiting_confirmation rolling_out completed aborted failed
canaryInstanceId
required
One of:
integer
canaryInstanceName
required
string
canaryStatus
required
One of:

Classified terminal status of the canary sync run.

string
Allowed values: success partial failed skipped
canarySyncHistoryId
required
One of:
integer
sections
required
One of:
Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
maxBatchSize
required
integer
>= 1
partialPolicy
required

How a partial canary outcome is treated:

  • gate: pass-with-warning; continue to the verification gate
  • abort: treat as failure; remaining instances are never touched
string
Allowed values: gate abort
canaryOutput
required
One of:
string
canaryError
required
One of:
string
remainingTargets
required
Array<object>
object
instanceId
required

Arr instance ID selected as a rollout target.

integer
instanceName
required

Denormalized instance name captured at rollout start.

string
remainingPreview
required
One of: discriminator: availability
object
version
required

Persisted Canary remaining-preview evidence schema version.

integer
Allowed value: 1
availability
required
string
Allowed value: available
generatedAt
required

Time the complete exact-target evidence snapshot was generated.

string format: date-time
previews
required

Complete previews for the persisted remaining target set. An empty mutation summary is a valid no-changes result and is distinct from unavailable evidence.

Array<object>

Read-only per-instance preview payload produced by the Canary coordinator. This matches the runtime GeneratePreviewResult contract; it is not a stored Sync Preview and therefore has no preview id, expiry timestamp, or top-level failure field.

object
instanceId
required

Exact remaining-target Arr instance ID.

integer
instanceName
required

Arr instance name at preview-generation time.

string
arrType
required

Arr family a rollout is scoped to. A rollout never spans types.

string
Allowed values: radarr sonarr lidarr
status
required

Preview lifecycle state:

  • generating: build in progress
  • ready: preview fully materialized and runnable
  • applying: preview is being executed as sync
  • applied: execution succeeded
  • failed: generation or execution failed
  • expired: staleness TTL elapsed
string
Allowed values: generating ready applying applied failed expired
createdAtMs
required

Preview generation time as Unix epoch milliseconds.

integer format: int64
sections
required
Array<string>
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
sectionOutcomes
required

Per-section evidence; any failure makes aggregate Canary evidence unavailable.

Array<object>
object
section
required

Sync section handled by preview generation

string
Allowed values: qualityProfiles delayProfiles mediaManagement metadataProfiles
skipped
required

True when the section had no config to preview and was skipped.

boolean
failure
required
One of:

Typed, closed, safe failure evidence for Sync Preview generate/apply. Replaces the former free-form error strings. message and recoveryAction are pre-authored safe copy drawn from a closed vocabulary — they NEVER contain raw exception text, Arr response bodies, credentials, hostnames, or stack traces. Full diagnostics live only in the sanitized server logs.

object
code
required

Closed vocabulary of Sync Preview generate/apply failure reasons. Each value is assigned by matching a thrown error’s TYPE/status (never by parsing message text), so no raw exception or secret-shaped string is ever transported:

  • unreachable: the Arr instance could not be reached (network/DNS/connection).
  • timeout: the Arr instance did not respond in time.
  • unauthorized: the Arr instance rejected the API key (HTTP 401/403).
  • notFound: a required Arr resource was not found (HTTP 404).
  • rejected: the Arr instance rejected the request (other HTTP 4xx).
  • serverError: the Arr instance returned a server error (HTTP 5xx).
  • sectionErrors: one or more sections failed to generate (top-level aggregate).
  • executionFailed: the apply sync run did not complete successfully.
  • stale: the preview is too old to apply safely.
  • internalError: an unexpected error occurred (catch-all for untyped failures).
string
Allowed values: unreachable timeout unauthorized notFound rejected serverError sectionErrors executionFailed stale internalError
message
required

Safe, user-facing summary of the failure. Never raw exception or secret text.

string
recoveryAction
required

Actionable next step the operator can take to recover.

string
qualityProfiles
required
One of:
object
section
required
string
Allowed values: qualityProfiles
customFormats
required

Custom-format change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityProfiles
required

Quality-profile change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
delayProfiles
required
One of:
object
section
required
string
Allowed values: delayProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaManagement
required
One of:
object
section
required
string
Allowed values: mediaManagement
naming
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
qualityDefinitions
required

Quality definition change set

Array<object>
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
mediaSettings
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
metadataProfiles
required
One of:
object
section
required
string
Allowed values: metadataProfiles
profile
required
One of:
object
entityType
required

Sync target entity kind (e.g., customFormat, qualityProfile)

string
name
required

Entity display name (namespace-stripped where applicable)

string
action
required
string
Allowed values: create update delete unchanged
remoteId
required

Arr entity ID when present

integer
nullable
fields
required

Field-level diff; empty for unchanged/create where no deltas are tracked

Array<object>
object
field
required

Dot-notated field path

string
type
required
string
Allowed values: added changed removed
current
required
Any of:
string
desired
required
Any of:
string
summary
required
object
totalCreates
required

Number of create actions

integer
totalUpdates
required

Number of update actions

integer
totalDeletes
required

Number of delete actions

integer
totalUnchanged
required

Number of unchanged entities

integer
batchCursor
required

Index into remainingTargets the rollout job has reached (resumable).

integer
rolloutResults
required
Array<object>
object
instanceId
required
integer
instanceName
required
string
status
required

Per-instance outcome status following JobRunStatus semantics.

string
Allowed values: success failure skipped cancelled
output

Human-readable sync summary from executeSyncJob.

string
error

Per-instance diagnostics on failure.

string
trigger
required

How the rollout was initiated.

string
Allowed values: manual system schedule
startedAt
required
string format: date-time
finishedAt
required
One of:
string format: date-time
stateToken
required

Value-guard token for /proceed and /abort; re-issued on every transition.

string
createdAt
required
string
updatedAt
required
string
Example
{
  "arrType": "radarr",
  "status": "canary_running",
  "canaryStatus": "success",
  "sections": [
    "qualityProfiles"
  ],
  "partialPolicy": "gate",
  "remainingPreview": {
    "version": 1,
    "availability": "available",
    "previews": [
      {
        "arrType": "radarr",
        "status": "generating",
        "sections": [
          "qualityProfiles"
        ],
        "sectionOutcomes": [
          {
            "section": "qualityProfiles",
            "failure": {
              "code": "unreachable"
            }
          }
        ],
        "qualityProfiles": {
          "section": "qualityProfiles",
          "customFormats": [
            {
              "action": "create",
              "fields": [
                {
                  "type": "added"
                }
              ]
            }
          ],
          "qualityProfiles": [
            {
              "action": "create",
              "fields": [
                {
                  "type": "added"
                }
              ]
            }
          ]
        },
        "delayProfiles": {
          "section": "delayProfiles",
          "profile": {
            "action": "create",
            "fields": [
              {
                "type": "added"
              }
            ]
          }
        },
        "mediaManagement": {
          "section": "mediaManagement",
          "naming": {
            "action": "create",
            "fields": [
              {
                "type": "added"
              }
            ]
          },
          "qualityDefinitions": [
            {
              "action": "create",
              "fields": [
                {
                  "type": "added"
                }
              ]
            }
          ],
          "mediaSettings": {
            "action": "create",
            "fields": [
              {
                "type": "added"
              }
            ]
          }
        },
        "metadataProfiles": {
          "section": "metadataProfiles",
          "profile": {
            "action": "create",
            "fields": [
              {
                "type": "added"
              }
            ]
          }
        }
      }
    ]
  },
  "rolloutResults": [
    {
      "status": "success"
    }
  ],
  "trigger": "manual"
}

400

Section titled “400”

Invalid id

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

404

Section titled “404”

Rollout not found

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

Failed to read canary rollout

Media typeapplication/json
object
error
required

Error message

string
Examplegenerated
{
  "error": "example"
}