> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.

# Download report files

> Download the file from a SUCCEEDED Reporting API run and handle URL expiry.

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](/reporting-api/create-and-poll) to get a run to that state, and [Authentication](/guides/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`

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

```json theme={null}
{
  "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`.

<Info>A Shippo `Authorization` header is not required for the download request.</Info>

```shell theme={null}
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

<CardGroup cols={2}>
  <Card title="Create and poll a report run" icon="clock" href="/reporting-api/create-and-poll">
    Track a run from `QUEUED` to `SUCCEEDED` before downloading.
  </Card>

  <Card title="Run reference" icon="code" href="/api-reference/report-runs/get-report-run">
    Full schema for the run resource and `result.download`.
  </Card>
</CardGroup>


## Related topics

- [Reporting API overview](/reporting-api/overview.md)
- [Reporting API Quickstart](/reporting-api/quickstart.md)
- [Create Report Run](/api-reference/report-runs/create-report-run.md)