> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/reports.md).

# Reports

Reports give you scheduled or on-demand exports of your account data — useful for invoicing pipelines, weekly summaries to stakeholders, or BI tools.

## Endpoints

| Method   | Path                 | Purpose                                 |
| -------- | -------------------- | --------------------------------------- |
| `GET`    | `/reports`           | List reports (scheduled + recent runs)  |
| `POST`   | `/reports`           | Schedule a new report                   |
| `GET`    | `/reports/{id}`      | Get a report definition                 |
| `PATCH`  | `/reports/{id}`      | Update schedule, fields, or destination |
| `DELETE` | `/reports/{id}`      | Delete a report                         |
| `POST`   | `/reports/{id}/run`  | Run on demand (returns a run ID)        |
| `GET`    | `/reports/runs/{id}` | Get run status and download URL         |

## Schedule

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name":   "weekly-traffic",
       "type":   "traffic",
       "filters": {
         "products": ["residential", "mobile"]
       },
       "schedule": "0 9 * * MON",
       "format":   "csv",
       "destination": {
         "type":  "email",
         "email": "ops@acme.com"
       }
     }' \
     https://api.helodata.com/v1/reports
```

### Report types

| `type`        | Content                                           |
| ------------- | ------------------------------------------------- |
| `traffic`     | Aggregated bandwidth per sub-user / product / day |
| `requests`    | Sampled per-request log                           |
| `invoices`    | Invoice line items                                |
| `subusers`    | Sub-user inventory snapshot                       |
| `isp_batches` | ISP batch inventory with per-IP health            |

### Destinations

| `type`    | Fields                                                   |
| --------- | -------------------------------------------------------- |
| `email`   | `email`                                                  |
| `webhook` | `url`, `signing_secret`                                  |
| `s3`      | `bucket`, `prefix`, `role_arn` (for cross-account write) |
| `gcs`     | `bucket`, `prefix`, `service_account_email`              |

### Schedules

`schedule` accepts standard 5-field cron in UTC. Or omit `schedule` to keep it on-demand only.

## Run on demand

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"from":"2026-05-01","to":"2026-05-28"}' \
     "https://api.helodata.com/v1/reports/rep_01HX2K3PQ4M5/run"
```

Returns:

```json
{
  "run_id":  "run_01HX2K3PQ4M5",
  "status":  "queued"
}
```

Poll status:

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/reports/runs/run_01HX2K3PQ4M5
```

When `status` becomes `completed`, the response includes a `download_url` (signed, valid for 1 hour) — or the report was already pushed to your `destination`.

## Formats

| `format`  | Notes                              |
| --------- | ---------------------------------- |
| `csv`     | UTF-8, comma-separated, header row |
| `tsv`     | UTF-8, tab-separated               |
| `json`    | Newline-delimited JSON (NDJSON)    |
| `parquet` | Best for `s3` / `gcs` destinations |

## Retention

Report runs and their downloadable artifacts are retained for **90 days**. For longer retention, push to `s3` / `gcs`.

## Errors

| Status | Code                      | Meaning                                      |
| ------ | ------------------------- | -------------------------------------------- |
| `422`  | `invalid_cron`            | Bad cron expression                          |
| `422`  | `destination_unreachable` | Webhook URL failed pre-flight                |
| `403`  | `feature_not_in_plan`     | Reports are a Pro+ feature; upgrade required |