> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Download backup

> Download one backup file for a database.

Downloads a single `.sql.gz` backup file as an attachment.

If you do not already know the exact filename, call [list backups](/api-reference/backups/list) first and use one of the returned `filename` values.

## Path parameters

| Parameter  | Type   | Description                                        |
| ---------- | ------ | -------------------------------------------------- |
| `id`       | uuid   | Database ID                                        |
| `filename` | string | Backup filename in `YYYYMMDD_HHMMSS.sql.gz` format |

## Example

```bash theme={null}
curl -L \
  -H "Authorization: Bearer dbh_your_api_key_here" \
  https://dbhost.app/api/v1/databases/550e8400-e29b-41d4-a716-446655440000/backups/20260326_222551.sql.gz \
  -o 20260326_222551.sql.gz
```

## Response

Returns the raw gzip file with `Content-Type: application/gzip` and `Content-Disposition: attachment`.

## Errors

| Status | Code                      | Description                                                                      |
| ------ | ------------------------- | -------------------------------------------------------------------------------- |
| 400    | `INVALID_BACKUP_FILENAME` | Filename is not in the expected backup format                                    |
| 401    | `UNAUTHORIZED`            | Missing or invalid API key                                                       |
| 404    | `DATABASE_NOT_FOUND`      | Database doesn't exist, isn't owned by this user, or isn't in scope for this key |
| 404    | `BACKUP_NOT_FOUND`        | Backup file does not exist                                                       |
| 503    | `AGENT_ROUTE_UNAVAILABLE` | Backup downloads are unavailable until the configured agent is updated           |
| 500    | `AGENT_ERROR`             | The VPS agent failed to stream the backup                                        |