Download Entity Export Run
Downloads the file a succeeded export run produced — the file half of
POST /entities/{entityType}/export-runs.
By default (format=csv, or no format at all) the response is the CSV
itself (text/csv; charset=utf-8, served as an attachment), streamed from
storage: the first row is the header (each requested column’s label, in
the requested order), followed by one row per exported record. A zero-row
export downloads as a header-only CSV.
format=xlsx downloads the same export as an Excel workbook
(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet): one
worksheet carrying exactly the CSV’s cells — the conversion changes the
file format, never the values. The workbook is produced server-side on the
first request and cached, so repeat downloads are cheap. An export whose
rows would not fit on one Excel worksheet (1,048,576 rows including the
header) is refused with a 409 — the CSV download still works and carries
every row.
Only a succeeded run downloads. Every other status is a 404:
queued and running have no file yet, failed never produced one, and
expired means the file passed its retention horizon and was deleted. Poll
GET .../export-runs/{runId} to learn which — the poll stays readable
for every status — and start a new export when the run failed or expired.
The file stays downloadable until the run’s expiresAt, and can be
downloaded any number of times until then.
Required permission: company.{entity}:list — the exact key varies by
type (Policy uses company.policy:export), derived from the path’s
{entityType}. See
Permissions.
Authorizations
User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as Authorization: Bearer <jwt>. The request resolves to the user's identity and is authorized by their Role on the {companyId} in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both BearerAuth and ApiKeyAuth.
Path Parameters
Company identifier
Field Model V1 EXPORTABLE entity type (lowercase kebab-case URL slug): the six
CRUD entity types plus policy. Unlike the CRUD entity routes, policy IS
valid here — a Policy export reads the segment in effect on the asOf date
(defaulting to today).
event, exposure, quote, submission, person, organization, policy The run identifier returned by POST /entities/{entityType}/export-runs. Runs are scoped to their company
AND their entity type: a run id belonging to another company, or started
under a different entity type, returns 404, exactly as an id that
exists nowhere does.
Query Parameters
The file format to download: csv (the default) for the export's CSV,
xlsx for its Excel workbook rendition. Any other value is a 400 —
never silently defaulted, because that would serve a different file
than the one asked for.
csv, xlsx Response
The exported file, streamed as an attachment named
{entityType}-export-{runId}.{format}.
The response is of type string.
