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

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": "[e-mail]"
       }
     }' \
     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

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:

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

Poll status:

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