As well as running to their schedule, backup jobs can be started on demand through the API. That's handy if you want to take a backup at a particular point in your release process, rather than waiting for the next scheduled run.
This article walks through starting a run of a backup job and following it through to completion.
Before you start
You'll need two things to hand:
An API token
The ID of the backup job you want to run
See Getting started with the Gearset Backup API for how to get both.
Starting a run
First, ask Gearset to run the job now. Copy the following and run it, replacing the token and job ID with your own:
curl -X POST \
-H "Authorization: token <APIToken>" \
https://api.gearset.com/public/backup/jobs/<jobID>/backup-now
If all's well you'll get a 202 back with an empty response body. The 202 means we've accepted your request. The run hasn't necessarily started yet, so the next step is to go and check its status.
Checking the status of the run
To find out what became of your request, ask the job for its most recent run. Copy the following, replacing the token and job ID as before:
curl -H "Authorization: token <APIToken>" \
https://api.gearset.com/public/backup/jobs/<jobID>/runs/latest
You should get a response like this:
{"RunId":"5872d0a8-bc64-4766-bbee-8aefd4ee1e97",
"JobId":"263ba833-0bd6-4361-ab22-6ef7ca20b6e8",
"Status":"InProgress",
"StartTime":"2026-07-23T09:00:00Z"}
One thing to watch for: if you've only just asked us to run the job, this may still be describing the previous run, because the new one hasn't started yet. Check again after a few seconds delay.
The possible statuses are:
Status | Meaning |
| The run is currently backing up your data. |
| The run is being cancelled. |
| The run completed. Binary data such as attachments may still be being backed up. |
| The run didn't complete. |
| The run was cancelled before it completed. |
Seeing what the run backed up
Once a run has succeeded, you can ask the same job what it actually backed up: for every object in the backup, how many records are stored and how many were added, changed, and deleted in that run. See Getting a summary of your most recent backup run with the Backup API for the call to make and what each field means.