# Retrieve an export

`GET /v1/exports/{export_id}`

Returns the current status of an export job. When `status` is
`COMPLETED` and the artifact has not yet expired, `download_url` is
populated with a path to [Download an export artifact](/api/exports/downloadExport).
Authenticate that follow-up GET with the same Bearer token used for
this endpoint — the URL itself does not carry embedded credentials.

Lifecycle:
- `PENDING` / `PROCESSING` → `download_url` is `null`, no `error_code`
- `COMPLETED` (within retention) → `download_url` populated
- `COMPLETED` (past 7-day retention) → `download_url` is `null`,
  `error_code: EXPORT_EXPIRED`
- `ERROR` → `download_url` is `null`, `error_code: EXPORT_FAILED`

Cross-org access is intentionally indistinguishable from "not found";
foreign `export_id`s return `404 EXPORT_NOT_FOUND`.

## Responses

### 200 — Export status. `download_url` populated when artifact is available.

**application/json**

- **object** — Full job descriptor returned by `GET /v1/exports/{export_id}`. The
`download_url` is populated only when `status` is `COMPLETED` and the
artifact has not yet expired; for terminal-error and expired-artifact
states it is `null` and `error_code` identifies why.

**Status casing note.** Export statuses use `SCREAMING_SNAKE_CASE`
(`PENDING`, `PROCESSING`, `COMPLETED`, `ERROR`) — distinct from the
lowercase status values used by the PDP endpoints (`processing`,
`scored`, `error`). Each endpoint family is self-consistent; partners
integrating both surfaces should plan for the difference.

CSV column layouts for each subject are documented in the description
of [Create a bulk export job](/api/exports/createExport).

  - `export_id` (string, required)
  - `subject` (enum: "pdps" | "images", required)
  - `status` (enum: "PENDING" | "PROCESSING" | "COMPLETED" | "ERROR", required) — Job lifecycle:
- `PENDING` — accepted, waiting on a worker slot
- `PROCESSING` — worker has picked it up and is streaming rows
- `COMPLETED` — artifact uploaded and available at `download_url`
- `ERROR` — terminal failure; see `error_code`

  - `requested_at` (string, required)
  - `completed_at` (any) — Set when `status` reaches `COMPLETED` or `ERROR`.
  - `row_count` (any) — Number of rows in the artifact (populated on `COMPLETED`).
  - `byte_size` (any) — Size of the artifact in bytes (populated on `COMPLETED`).
  - `download_url` (any) — Path to [Download an export artifact](/api/exports/downloadExport).
Vizit-served — partners authenticate with the same Bearer token they
use for every other endpoint; the URL itself does not carry any
embedded credentials and is safe to log or share within the partner's
own systems (subject to the partner's own access controls). `null`
when the job is not yet `COMPLETED`, when the artifact has expired,
or on terminal error.

  - `download_url_expires_at` (any) — Absolute expiry of the artifact behind `download_url`. Equal to the
job's own `expires_at` — the download endpoint stays valid for as
long as the underlying artifact is retained (7 days from completion).
No separate URL-level TTL.

  - `expires_at` (any) — Absolute expiry of the artifact itself (`completed_at + 7 days`).
After this time the artifact is removed and the job is reported with
`error_code: EXPORT_EXPIRED`.

  - `error_code` (any) — SCREAMING_SNAKE_CASE error code. Populated when `status` is `ERROR`
or when the artifact has expired. Possible values:
  - `EXPORT_FAILED` — worker hit an unrecoverable failure
  - `EXPORT_EXPIRED` — `status` is still `COMPLETED` but the artifact
    has been removed past its 7-day retention


### 401 — Missing or invalid Bearer token

### 404 — Export not found in the caller's organization.
`error_code: EXPORT_NOT_FOUND`.


**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)