Download report files

Once a Reporting API run reaches SUCCEEDED, you can download the file. Fetch the run by id to get a short-lived signed URL, then download from it. See Create and poll a report run to get a run to that state, and Authentication for token setup.

Get the download URL

GET /v2/reporting/runs/{run_id}

A SUCCEEDED run includes a result object:

Field	Type	Description
`row_count`	integer	Number of rows in the file.
`size_bytes`	integer	File size in bytes.
`download`	object	See below.

The download object has two shapes:

`download.status`	Fields	Meaning
`available`	`url`, `expires`	Time-limited signed URL. `expires` is a UTC epoch second.
`unavailable`	None	No download URL is available yet. Re-`GET` the run.

The signed URL only appears when you fetch the single run by id. You won’t find it:

on the POST 201 response
while the run is QUEUED or PROCESSING

curl https://api.goshippo.com/v2/reporting/runs/6b3c8f2a-1d4e-4a9c-bf17-2e5a9c0d8e44 \
  -H "Authorization: ShippoToken <API_TOKEN>"

{
  "id": "6b3c8f2a-1d4e-4a9c-bf17-2e5a9c0d8e44",
  "status": "SUCCEEDED",
  "result": {
    "row_count": 12840,
    "size_bytes": 481223,
    "download": {
      "status": "available",
      "url": "https://<download-host>/<opaque-path>?<signature>",
      "expires": 1706832304
    }
  }
}

Download the file

Send a plain GET to result.download.url.

A Shippo Authorization header is not required for the download request.

curl -o report.csv.gz \
  "https://<download-host>/<opaque-path>?<signature>"

Output formats

You set the file format when you create the run (output_format). The default is csv_gzip.

`output_format`	File	Notes
`csv`	Uncompressed CSV	Header row matches the run’s `columns`.
`csv_gzip`	Gzip-compressed CSV	Default. Decompress before parsing.
`parquet`	Apache Parquet	Columnar format for downstream data tooling.

URL expiry

Each GET /v2/reporting/runs/{run_id} on a run with status: SUCCEEDED returns a new signed URL. The expires field contains its expiry as a UTC epoch second. If a URL has expired, re-GET the run for a new one. You don’t need to recreate the run.

Next steps

Create and poll a report run

Track a run from QUEUED to SUCCEEDED before downloading.

Run reference

Full schema for the run resource and result.download.

Overview

Get started

AI & agents

Guides

Concepts

Get the download URL

Download the file

Output formats

URL expiry

Next steps

Create and poll a report run

Run reference

​Get the download URL

​Download the file

​Output formats

​URL expiry

​Next steps

Create and poll a report run

Run reference

Get the download URL

Download the file

Output formats

URL expiry

Next steps