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. |
And that's it
You've now used the Backup API to start a backup run and follow it through to completion.