Export Databases

Export a Paused Database

GET /v1/databases/{uuid}/export

A paused database can be exported as often as you like, whatever the plan: an export is a gzipped SQL dump of the whole database, like a backup. Paused here means closed (closed: true on the database): over the plan's database limit, on a plan that doesn't include databases, or a paused WordPress site's own database. This route says whether the database can be exported now and returns its latest export. See Export a closed database for the dashboard side (Export data on the database's Backups tab).

Every export route needs the role's Database data read permission, like a backup download, and no plan entitlement. They are also on the agent plane under /v1/agent/databases/{uuid}/export, for account-scoped agent tokens. A database of another account answers 404. While the account is suspended, whatever the reason, nothing can be exported: every export route answers 403 account_suspended.

Response (200 OK)

database object

{uuid, name, status}.

closed bool

true when the database is paused, so it can be exported. false for an open database: back it up instead.

pausing bool

true while the database is being paused: export it once closed is true.

can_export bool

An export can be started now: the database is paused and ready, and no backup or export of it is running.

in_progress bool

A backup or an export of the database is pending or running.

export object | null

The database's latest export since it was paused, or null when there is none.

Export object

uuid string (uuid)

The export's id. On a plan that includes databases, the export is also in the database's backup list, as a backup with trigger_source: "manual".

status string

pending → running → completed, or failed. A failed export can't be downloaded: export the database again.

size_bytes int

Size of the .sql.gz file; 0 until it has completed.

created_at, started_at, completed_at string

When it was requested, started and finished. The last two are present once they happened.

Errors

403

Insufficient permissions for this action (no Database data read), No active account for this request, or account_suspended (the account is suspended).

404

database not found.

503

database_backups_unavailable or databases_unavailable: the feature isn't available yet.

Request
curl "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/export" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK (paused, an export ready)
{
  "database": {
    "uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
    "name": "orders-db",
    "status": "ready"
  },
  "closed": true,
  "pausing": false,
  "can_export": true,
  "in_progress": false,
  "export": {
    "uuid": "019c4d63-9f50-7d74-a3e6-7ab12d5f8c3a",
    "status": "completed",
    "size_bytes": 1052160,
    "created_at": "2026-11-04T10:15:00Z",
    "started_at": "2026-11-04T10:15:03Z",
    "completed_at": "2026-11-04T10:15:19Z"
  }
}

Response — 200 OK (an open database)
{
  "database": {
    "uuid": "019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18",
    "name": "orders-db",
    "status": "ready"
  },
  "closed": false,
  "pausing": false,
  "can_export": false,
  "in_progress": false,
  "export": null
}

Start an Export

POST /v1/databases/{uuid}/export

Export the paused database now (the dashboard's Export data). No body is needed. The export is created pending; ngris then dumps the whole database (its tables, data and views) to a gzipped SQL file and it turns completed. Poll GET /v1/databases/{uuid}/export for the status, then download it. One backup or export of a database runs at a time.

Each export replaces the previous one. Starting an export deletes the earlier exports taken since the database was paused, and a backup taken with POST /v1/databases/{uuid}/backups while it was paused: a paused database's data can't change, so the latest export has all of it. Automatic backups, and backups taken before the database was paused, are kept as they are. A paused database takes one backup while it is paused, and an export counts as that one: after an export, POST /v1/databases/{uuid}/backups answers 409 database_closed, so export again instead.

Response (202 Accepted)

{"export": {…}}: the new export object, status: "pending".

Errors

403

No Database data read, no active account, or account_suspended (the account is suspended).

404

database not found.

409

database_not_paused: Only a paused database can be exported. Back this one up instead.
database_pausing: This database is being paused. Try again in a minute.
backup_in_progress: This database is already being exported. Wait for it to finish. (an export or a backup of it is pending or running)
database_status: the database isn't ready (e.g. Not possible while the database is deleting.); resource and status say which.

503

database_backups_unavailable or databases_unavailable.

Request
curl -X POST "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/export" \
  -H "X-API-KEY: <your_api_key>"

Response — 202 Accepted
{
  "export": {
    "uuid": "019c4d63-9f50-7d74-a3e6-7ab12d5f8c3a",
    "status": "pending",
    "size_bytes": 0,
    "created_at": "2026-11-04T10:15:00Z"
  }
}

Response — 409 (an open database)
{
  "error": "Only a paused database can be exported. Back this one up instead.",
  "code": "database_not_paused"
}

Download the Export

GET /v1/databases/{uuid}/export/download

Stream the paused database's latest completed export: the gzipped SQL dump, Content-Type: application/gzip, as an attachment named <database name>-<export uuid>.sql.gz (characters other than letters, digits, ., _ and - in the name become -). The dump has no DROP TABLE statements: import it into an empty database. Download it as many times as you need.

Errors

403

No Database data read, no active account, or account_suspended (the account is suspended).

404

export_not_found: This database has no export yet. Export it first.; database not found; or backup artifact not found (the stored file is gone: export the database again).

409

export_not_ready: The export isn't ready yet. Download it when it has finished., or The last export failed. Export the database again.
database_not_paused or database_pausing, as for Start an Export.

502

failed to read backup artifact: the storage couldn't be read; retry.

503

Backup storage is not configured., database_backups_unavailable or databases_unavailable.

Request
curl -L -o orders-db.sql.gz \
  "https://api.ngris.com/v1/databases/019c2a41-7d3e-7b52-a1c4-5e9f0b3d6a18/export/download" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK (headers)
Content-Type: application/gzip
Content-Disposition: attachment; filename="orders-db-019c4d63-9f50-7d74-a3e6-7ab12d5f8c3a.sql.gz"
Content-Length: 1052160

Audit trail

Every export started and every download is recorded in the account audit log with event_type database: Database export requested: <name> and Database export downloaded: <name>.