Reports and dashboards

A saved report is a query you can run again. A dashboard shows several reports side by side.

What you need first

• Some sends and events to report on.

• A key with analytics:write (analytics:read to run and export only).

Analytics dates are days: YYYY-MM-DD (a full ISO 8601 time is accepted too; its date is used).

1. Look before you save

curl -s "$BASE/v1/analytics/overview?from=2026-10-01&to=2026-11-03" -H "Authorization: Bearer $HERMETICA_API_KEY"
curl -s "$BASE/v1/analytics/messages?from=2026-10-01&to=2026-11-03" -H "Authorization: Bearer $HERMETICA_API_KEY"

2. Save a report

curl -s -X POST "$BASE/v1/analytics/reports" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Outbound funnel by source","query":{"kind":"builder","from":"2026-10-01","to":"2026-12-31",
       "metrics":["sent","delivered","opened_unique","clicked_unique","replied"],"dimensions":["source_kind"]}}'

Other kinds: messages (with groupBy day, channel, source or variant), revenue and engagement.

3. Run it or export it

curl -s "$BASE/v1/analytics/reports/<reportId>/run" -H "Authorization: Bearer $HERMETICA_API_KEY"
curl -s "$BASE/v1/analytics/reports/<reportId>/export" -H "Authorization: Bearer $HERMETICA_API_KEY"   # CSV

4. Email it every week

curl -s -X PATCH "$BASE/v1/analytics/reports/<reportId>/schedule" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"schedule":"weekly","recipients":["gtm@example.com"],"rollingDays":7}'

rollingDays makes each email cover the last 7 days instead of the saved dates.

5. Build a dashboard

curl -s -X POST "$BASE/v1/analytics/dashboards" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Q4 pipeline","widgets":[{"reportId":"<reportId>","title":"Outbound funnel","size":"full"}]}'

curl -s "$BASE/v1/analytics/dashboards/<dashboardId>/run" -H "Authorization: Bearer $HERMETICA_API_KEY"

GET /v1/analytics/dashboards/<id>/export gives every widget as CSV. If a report on it is deleted, that widget says "Report was deleted".

To copy a dashboard to another workspace, GET /v1/analytics/dashboards/<id>/definition/export, then send that JSON to POST /v1/analytics/dashboards/import there. It copies the reports too.

6. Who can see it

curl -s -X PATCH "$BASE/v1/analytics/reports/<reportId>/access" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"visibility":"private"}'

Use "shared" with sharedWith to show it to some people only.

One-off questions

Charts of your own events

curl -s "$BASE/v1/metrics" -H "Authorization: Bearer $HERMETICA_API_KEY"   # every event name with counts

curl -s -X POST "$BASE/v1/metrics/aggregates" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"metric":"Signed up","interval":"month","by":"plan","from":"2026-09-01T00:00:00Z","to":"2026-11-03T00:00:00Z","timezone":"America/New_York"}'

Here from and to are ISO times, not days.

To count several events as one, create a custom metric and aggregate it by its id, not its name:

curl -s -X POST "$BASE/v1/custom-metrics" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Activated workspace","definition":{"sources":[{"event":"Connected provider"},{"event":"Sent first campaign"}]}}'

Next: Business goals and conversions.