Skip to main content
This tutorial walks the Reports flow end-to-end. It assumes you have:

​
1. Create a template

  1. Navigate to Settings → Reports.
  2. Click New Report.
  3. Under Details, give it a name: Weekly digest.
  4. Under the Compose tab, leave the default Offer performance (7 days) source. Click Add source and pick Channel effectiveness.
  5. Under Format & narrative, tick PDF and CSV. Leave Enable AI narrative on. Add a prompt addendum like Flag any offer with >15% week-over-week drop. (optional).
  6. Click Save. The editor navigates to the template-edit page with a populated preview pane.

​
2. Preview

The preview pane on the right renders the executive summary (if the narrator is enabled) and a row-count per section. Preview refreshes automatically 600ms after every change to the form.

​
3. Schedule delivery

Creating a schedule does not automatically fire the report. Schedules depend on an external scheduler (AWS EventBridge) hitting /api/cron/tick on a cadence. During pilot / initial deployment this is usually not wired — see EventBridge Setup for the optional wiring path.Until the cron is wired, use Run Now (next step) whenever you want a scheduled report delivered. Run Now works unconditionally and does not depend on any scheduler being in place.
  1. Still on the template-edit page, switch to the Schedule tab.
  2. Tick the notification destinations you want to deliver to.
  3. Set a Schedule name: Daily 8am UTC.
  4. Leave Timezone as UTC.
  5. Set Cron expression to 0 8 * * *.
  6. Click Add schedule. The schedule appears in the list below with its next run time.
The nextRunAt timestamp is computed and stored but only acts as a trigger when a scheduler invokes /api/cron/tick.

​
4. Run it now (works without EventBridge)

This is the recommended path during pilot — it bypasses the scheduler entirely and delivers the report immediately.
  1. Back at Settings → Reports, click Run now on the template’s row.
  2. A toast announces the run’s ID.
Check your destination:
  • Ops email: arrives with PDF + CSV attachments; body contains the executive summary and key takeaways.
  • Slack/Teams: message with the summary, key takeaways bullets, and a deep link back to /api/v1/reports/runs/[id].
  • Webhook: POST body includes artifact base64 inline.
Equivalent API call: 
curl -X POST "$PLATFORM_URL/api/v1/reports/templates/$TEMPLATE_ID/run-now" \
  -H "X-API-Key: $KEY" -H "X-Tenant-Id: $TENANT"

​
5. Optional — verify cron wiring

Skip this step during pilot unless you’ve already followed EventBridge Setup. Once the cron is wired and CRON_TOKEN is set on the service, you can simulate a scheduled run by invoking the tick manually: 
curl -X POST "$PLATFORM_URL/api/cron/tick" \
  -H "x-cron-token: $CRON_TOKEN"
You should see a JSON response containing reportsEvaluated, reportsRan, and (for this tenant) an updated lastRunAt on the schedule — assuming the schedule’s nextRunAt has already elapsed.

​
6. Browse run history

Runs are persisted as ReportRun rows. You can fetch them: 
curl "$PLATFORM_URL/api/v1/reports/runs?templateId=$TEMPLATE_ID" \
  -H "X-API-Key: $KEY" -H "X-Tenant-Id: $TENANT"
And download a specific artifact: 
curl -O "$PLATFORM_URL/api/v1/reports/runs/$RUN_ID/artifacts/pdf" \
  -H "X-API-Key: $KEY" -H "X-Tenant-Id: $TENANT"

​
Troubleshooting

  • Empty executive summary — either the AI provider isn’t configured or the narrator couldn’t parse the model’s response. The run still produces artifacts; the narrative section is simply empty.
  • Schedule was created but never fires — expected during pilot. The cron must be wired; until then use Run Now. See EventBridge Setup.
  • Schedule stuck at lastStatus: "failed" — check the errorMessage column. Common causes: invalid cron, deleted template referenced by schedule, or a data source querying a table the tenant lacks.
  • Destination delivery failures — visit Settings → Integrations → Notifications and use each provider’s Test Connection button.