Get report status

Poll the status of a report and retrieve its results once generation is complete.

Returns the current status of the report job (PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, or CLOSED) and, on success, either an inline data preview or a signed external download link depending on the is_download flag set when the report was created.

About Get Report Status

This endpoint is the second half of Esper's two-step asynchronous report pattern. After POST /report/v0/reports returns a report_id, poll this endpoint until status reaches a terminal state. When is_download was false, the successful response includes a data_array of up to 10,000 rows along with a schema object describing column names, positions, and types. When is_download was true, the response instead includes an external_link — a signed URL pointing to the full dataset as a downloadable CSV.

Key Fields

report_id (path, required) — UUID returned by POST /report/v0/reports

status — Current job state: PENDING (queued), RUNNING (processing), SUCCEEDED (results available), FAILED, CANCELED, or CLOSED

schema.columns — Array of column metadata objects, each with name, position, type_name, and type_text

data_array — (preview mode only) 2D array of row data, capped at 10,000 rows

external_link — (download mode only) Signed URL to the full CSV export

Common Use Cases

Polling report status after initiating generation via POST /report/v0/reports

Retrieving inline row data for small to mid-sized fleets (preview mode, ≤10,000 rows)

Obtaining a signed download URL for full fleet exports that exceed the 10,000-row preview cap

Best Practices

Poll at a reasonable interval (e.g., every 10–30 seconds) rather than immediately after creating the report, as generation can take several minutes

Check for terminal statuses (SUCCEEDED, FAILED, CANCELED, CLOSED) and stop polling once reached

If status is FAILED, re-submit the report via POST /report/v0/reports rather than retrying the same report_id

For download-mode reports, retrieve the external_link promptly as signed URLs may expire

Workflow

Receive the report_id from POST /report/v0/reports

Poll this endpoint at intervals until status is SUCCEEDED (or a failure terminal state)

If preview mode: read data_array for results and schema for column structure; if download mode: fetch the CSV from external_link