Runs

Download schema

Endpoints for the runs of the team's backup jobs: backups and maintenance operations such as retention cleanup, pruning and integrity checks. A backup run is a recovery point, which can be kept forever or expired.

List runs

GET

https://backup.chief.app/api/v1

/runs

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the runs of all the team's backup jobs, newest first.

List runs › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

status

string | null · enum

Only return runs with this status.

Enum values:

pending

running

complete

partial

failed

cancelled

skipped

unresolved

kind

string | null · enum

Only return backups, or runs of this maintenance operation.

Enum values:

backup

forget

prune

check_metadata

check_data

snapshot_inventory

trigger

string | null · enum

Only return runs someone started (manual) or the schedule started (scheduled).

Enum values:

manual

scheduled

job

string | null

Only return the runs of this backup job.

server

string | null

Only return the runs on this server.

List runs › Responses

Paginated set of BackupRun

BackupRun[] · required

object · required

GET/runs

curl https://backup.chief.app/api/v1/runs \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "job": {
        "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "kind": "backup",
      "trigger": "manual",
      "status": "pending",
      "status_label": "Succeeded",
      "result_code": "success",
      "summary": "summary",
      "source_files": {},
      "source_bytes": {},
      "stored_bytes": {},
      "statistics": [
        "1,204 files",
        "2.3 GB processed",
        "+12 MB added"
      ],
      "repository_bytes": 0,
      "repository_bytes_delta": 0,
      "snapshots_count": "snapshots_count",
      "available_snapshots_count": "available_snapshots_count",
      "restorable": true,
      "kept_forever_at": "kept_forever_at",
      "has_log": true,
      "repositories": [
        {
          "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
          "storage_destination": {
            "id": "id",
            "name": "name"
          },
          "status": "pending",
          "result_code": "success",
          "summary": "summary",
          "diagnostic": "diagnostic",
          "attempt_count": 0,
          "repository_bytes": 0,
          "started_at": "started_at",
          "finished_at": "finished_at"
        }
      ],
      "scheduled_for": "scheduled_for",
      "started_at": "started_at",
      "finished_at": "finished_at",
      "created_at": "created_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

List the runs of a backup job

GET

https://backup.chief.app/api/v1

/jobs/{job}/runs

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the runs of one backup job, newest first.

List the runs of a backup job › path Parameters

job

string · required

List the runs of a backup job › query Parameters

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

status

string | null · enum

Only return runs with this status.

Enum values:

pending

running

complete

partial

failed

cancelled

skipped

unresolved

kind

string | null · enum

Only return backups, or runs of this maintenance operation.

Enum values:

backup

forget

prune

check_metadata

check_data

snapshot_inventory

trigger

string | null · enum

Only return runs someone started (manual) or the schedule started (scheduled).

Enum values:

manual

scheduled

job

string | null

Only return the runs of this backup job.

server

string | null

Only return the runs on this server.

List the runs of a backup job › Responses

Paginated set of BackupRun

BackupRun[] · required

object · required

GET/jobs/{job}/runs

curl https://backup.chief.app/api/v1/jobs/:job/runs \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "job": {
        "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "server": {
        "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "name": "name"
      },
      "kind": "backup",
      "trigger": "manual",
      "status": "pending",
      "status_label": "Succeeded",
      "result_code": "success",
      "summary": "summary",
      "source_files": {},
      "source_bytes": {},
      "stored_bytes": {},
      "statistics": [
        "1,204 files",
        "2.3 GB processed",
        "+12 MB added"
      ],
      "repository_bytes": 0,
      "repository_bytes_delta": 0,
      "snapshots_count": "snapshots_count",
      "available_snapshots_count": "available_snapshots_count",
      "restorable": true,
      "kept_forever_at": "kept_forever_at",
      "has_log": true,
      "repositories": [
        {
          "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
          "storage_destination": {
            "id": "id",
            "name": "name"
          },
          "status": "pending",
          "result_code": "success",
          "summary": "summary",
          "diagnostic": "diagnostic",
          "attempt_count": 0,
          "repository_bytes": 0,
          "started_at": "started_at",
          "finished_at": "finished_at"
        }
      ],
      "scheduled_for": "scheduled_for",
      "started_at": "started_at",
      "finished_at": "finished_at",
      "created_at": "created_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Get a run

GET

https://backup.chief.app/api/v1

/runs/{run}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get one run with its outcome, figures and the result per repository, including diagnostics of failures.

Get a run › path Parameters

run

string · required

Get a run › Responses

BackupRun

BackupRun · required

GET/runs/{run}

curl https://backup.chief.app/api/v1/runs/:run \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Get the log of a run

GET

https://backup.chief.app/api/v1

/runs/{run}/log

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Return the complete log the agent uploaded for the run, as plain text. Logs are kept for a limited time; has_log on the run tells whether one is available.

Get the log of a run › path Parameters

run

string · required

Get the log of a run › Responses

The run log.

string

Cancel a run

POST

https://backup.chief.app/api/v1

/runs/{run}/cancel

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Ask the agent to stop a pending or running run. The agent stops it the next time it checks in; follow the run's status. Asking again while a cancellation is pending changes nothing.

Cancel a run › path Parameters

run

string · required

Cancel a run › Responses

The cancellation was queued.

BackupRun · required

POST/runs/{run}/cancel

curl https://backup.chief.app/api/v1/runs/:run/cancel \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Retry a maintenance run

POST

https://backup.chief.app/api/v1

/runs/{run}/retry

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Run a finished maintenance operation again with the plan it was started with, such as a retention cleanup that failed for an extra copy. Backups are not retried this way: run the job again instead. The response is the original run; the retry shows up as a new run of the job.

Retry a maintenance run › path Parameters

run

string · required

Retry a maintenance run › Responses

The retry was queued.

BackupRun · required

POST/runs/{run}/retry

curl https://backup.chief.app/api/v1/runs/:run/retry \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Keep a recovery point forever

PUT

https://backup.chief.app/api/v1

/runs/{run}/keep-forever

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Exclude a backup run and all its snapshots from the job's retention policy, so automatic cleanup never removes them. The job must be active on an enrolled server and every snapshot of the run must still be restorable.

Keep a recovery point forever › path Parameters

run

string · required

Keep a recovery point forever › Responses

BackupRun

BackupRun · required

PUT/runs/{run}/keep-forever

curl https://backup.chief.app/api/v1/runs/:run/keep-forever \
  --request PUT \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Stop keeping a recovery point forever

DELETE

https://backup.chief.app/api/v1

/runs/{run}/keep-forever

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Put a recovery point that was kept forever back under the job's retention policy, which may then remove it at its next cleanup.

Stop keeping a recovery point forever › path Parameters

run

string · required

Stop keeping a recovery point forever › Responses

BackupRun

BackupRun · required

DELETE/runs/{run}/keep-forever

curl https://backup.chief.app/api/v1/runs/:run/keep-forever \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Expire a recovery point

POST

https://backup.chief.app/api/v1

/runs/{run}/expire

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Ask the agent to remove a backup run's snapshots from its repositories now, regardless of the retention policy. This cannot be undone: the data can no longer be restored once the agent removed it. The newest complete recovery point and recovery points kept forever cannot be expired.

Expire a recovery point › path Parameters

run

string · required

Expire a recovery point › Responses

The removal was queued.

BackupRun · required

POST/runs/{run}/expire

curl https://backup.chief.app/api/v1/runs/:run/expire \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "run_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "job": {
      "id": "job_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "server": {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "name"
    },
    "kind": "backup",
    "trigger": "manual",
    "status": "pending",
    "status_label": "Succeeded",
    "result_code": "success",
    "summary": "summary",
    "source_files": {},
    "source_bytes": {},
    "stored_bytes": {},
    "statistics": [
      "1,204 files",
      "2.3 GB processed",
      "+12 MB added"
    ],
    "repository_bytes": 0,
    "repository_bytes_delta": 0,
    "snapshots_count": "snapshots_count",
    "available_snapshots_count": "available_snapshots_count",
    "restorable": true,
    "kept_forever_at": "kept_forever_at",
    "has_log": true,
    "repositories": [
      {
        "id": "repository_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "storage_destination": {
          "id": "id",
          "name": "name"
        },
        "status": "pending",
        "result_code": "success",
        "summary": "summary",
        "diagnostic": "diagnostic",
        "attempt_count": 0,
        "repository_bytes": 0,
        "started_at": "started_at",
        "finished_at": "finished_at"
      }
    ],
    "scheduled_for": "scheduled_for",
    "started_at": "started_at",
    "finished_at": "finished_at",
    "created_at": "created_at"
  }
}

json

application/json

Source inspections Snapshots