Backups

Run a backup immediately for an S3 source.

Changed on

Enqueues the backup for asynchronous execution via the BackupRunner (ADR-014). Returns 202 Accepted immediately: a backups row is inserted with state='pending' and a backup_jobs row is enqueued for the ControlPlaneEngine. Poll GET /backups/{id} to observe pending → running → completed.

post/backups/s3-sources/{id}/run

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/backups/s3-sources/{id}/run
  • Auth: HTTP bearer

Path parameters

idinteger required

Request body

backup_typestring required

Type of backup to perform

Example request

{
  "backup_type": "full"
}

Response

Backup enqueued for async execution

attemptsinteger nullable

How many times this job has been claimed and run. null for legacy backups with no backup_jobs row.

backup_idstring required
backup_typestring required
checksumstring nullable
completed_atinteger nullable
compression_typestring required
created_byinteger required
current_stepstring nullable

Name of the engine step currently executing (e.g., "walg_push"). null when no backup_jobs row exists for this backup (legacy rows pre-dating ADR-014), or when the job has not yet completed its first step.

error_messagestring nullable
expires_atinteger nullable
file_countinteger nullable
idinteger required
live_size_bytesinteger nullable

Best-effort partial size while a backup is still running, computed by listing the S3 prefix. Null when the backup is finished (size_bytes is authoritative in that case).

max_attemptsinteger nullable

Maximum attempts before the job is permanently failed. null for legacy backups.

max_runtime_secsinteger nullable

Resolved wall-clock timeout for this backup job (seconds). null for legacy backups. Derived from the three-tier resolution order: caller override → schedule override → engine default.

metadataunknown required
namestring required
s3_locationstring required
s3_source_idinteger required
schedule_idinteger nullable
size_bytesinteger nullable

Final size of the backup once completed. Null while running.

started_atinteger required
statestring required
tagsstring[] required

Example response

{
  "external_service": {
    "service_type": "postgres"
  }
}

Changes

  • 4b228ebed583Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 1dc3e6788214Revision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status