# Download a bulk address job's results

`GET /api/v1/address/bulk/{jobId}/results`

- Authentication: Secret API key as a bearer token
- Billing: Free.
- Group: Address

The result file as CSV: one row per input address, in input order, with the address as submitted, every field of the single-address response as a column, the datasets behind the answer, the credits the row cost, and whether the account's suppression list answered it (`suppressed`). A run created from an uploaded file carries that file's own columns first. Sources are joined by `;` as `dataset@version` and risk signals as `signal:weight`; `formatted` writes its lines on one line, joined by `, `. Fields containing spaces or commas are quoted. Add `?variant=valid|invalid|low|medium|high` to download only the rows that stand as written or do not, or one risk level; the default `full` returns everything. Available once the job is `completed`, or `cancelled` with at least one processed row; a job still running answers `409 RESULTS_NOT_READY`, a cancelled job with nothing processed `409 JOB_CANCELLED`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `jobId` | path | integer | yes |  |
| `variant` | query | string | no | Restrict the file to the rows that stand as written or do not, or to one risk level. Defaults to full. One of: full, valid, invalid, low, medium, high. |

## Example request

```bash
curl https://spaw.co/api/v1/address/bulk/{jobId}/results \
  -H "Authorization: Bearer sk_live_…"
```

## Responses

### 200 — The CSV file.

```csv
address,valid,reason,country,country_name,continent,is_eu,is_eea,privacy_regime,formatted,organization,street,house_number,unit,po_box,dependent_locality,locality,administrative_area,postal_code,postal_code_valid,postal_code_type,postcode_status,locality_matches_postcode,address_type,address_type_source,is_po_box,is_private_mailbox,exists,match_level,register,register_coverage,latitude,longitude,location_source,companies_registered,is_mail_drop,mail_drop_provider,mail_drop_source,deliverability_checked,is_deliverable,is_cmra,is_vacant,is_residential,risk_score,risk_level,risk_signals,sources,credits_used,suppressed
"1600 Amphitheatre Parkway, Mountain View, CA 94043",true,,US,United States,NA,false,false,ccpa,"1600 AMPHITHEATRE PKWY, MOUNTAIN VIEW, CA 94043",,Amphitheatre Parkway,1600,,,,Mountain View,CA,94043,true,zip,,,street,format,false,,,,,,,,,,,,,false,,,,,0,low,,address-formats@2026-09-01;address-rules@2026-09-01,1,false
```

### 401 — The key is missing, malformed, or revoked.

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 404 — No such record on this account.

```json
{
    "message": "Not Found"
}
```

### 409 — The job is still running (`RESULTS_NOT_READY`) or was cancelled before any row was processed (`JOB_CANCELLED`).

```json
{
    "success": false,
    "error": {
        "code": "RESULTS_NOT_READY",
        "message": "The results are not ready yet.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 429 — Over 5 requests per second for the key. Retry after the limit resets.

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `VALIDATION_FAILED` — https://spaw.co/docs/errors/VALIDATION_FAILED
- `RESULTS_NOT_READY` — https://spaw.co/docs/errors/RESULTS_NOT_READY
- `JOB_CANCELLED` — https://spaw.co/docs/errors/JOB_CANCELLED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED

---

Canonical page: https://spaw.co/docs/api/download-address-bulk-results · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api