Reports & delivery

Scheduled reports

Instead of logging in to check your dashboard, SignalGuide runs analysis on your schedule, writes a plain-English briefing, and delivers it to your inbox or Slack channel. Paid plans only — free accounts can still run analysis on demand from the dashboard.

Frequencies

Three frequencies are supported, enforced by the schedule model in api/models/report_schedule.py:

  • Daily — analysis runs over the last 7 days, compared to the 7 days before that. Delivered roughly 24 hours after your last send.
  • Weekly — same 7-day window, delivered 7 days after the last send.
  • Monthly — 30-day window delivered 30 days after the last send.
How the period length is set
The scheduler in api/services/scheduler.py calls run_analysis(site, user, db) with the default days=7 for all schedule frequencies — the 7-day comparison window is fixed today regardless of whether you run daily or weekly. The frequency controls delivery cadence, not the data window.

What the report contains

The report is generated by the AI writer in api/services/report_generator.py. It receives the latest snapshot data and writes a plain-English briefing structured around:

  • Pulse metrics — total users, new users, top pages by views, overall traffic direction.
  • Red flags — ranked P0, P1, P2 findings from the anomaly detector. Bounce rate spikes, traffic drops, CTR gaps, deindexed pages.
  • Opportunities — striking-distance queries, pages with high impressions and low CTR, cluster momentum.
  • Content clusters — per-cluster views, impressions, clicks, average position, bounce rate, and AI referral share.
  • AI referral traffic — sessions from ChatGPT, Gemini, Perplexity, Claude, and other AI sources.
  • Conversion page metrics — views, bounce rate, and source-funnel conversion rates for your configured conversion pages.

The writer has access to your site's business context, goals, and operator notes — so the briefing is written against what you told SignalGuide matters, not against generic SEO best practices.

Setting up a schedule

01

Open Settings → Briefing schedules

Select the site you want to schedule (if you have more than one), then go to the Schedules tab in Settings.

02

Choose frequency and channel

Pick daily, weekly, or monthly. Pick email or Slack. For Slack, paste a webhook URL (see Slack integration).

03

Save

The request hits POST /reports/schedules/{site_id} in api/routes/reports.py. The schedule row is created with next_send = null — the scheduler treats null as “due now” and will fire on the next check cycle.

Free plan restriction
POST /reports/schedules/{site_id} returns a 403 for free accounts: Upgrade to a paid plan for scheduled reports. On-demand analysis from the dashboard is still available on the free plan.

How the scheduler works

The scheduler in api/services/scheduler.py runs as a background job using APScheduler. It checks for due schedules every 15 minutes:

PYTHON
scheduler.add_job(_run_scheduled_reports, "interval", minutes=15, id="scheduled_reports")

On each tick it looks for ReportSchedule rows where next_send is null or in the past. For each due schedule it:

  1. Calls run_analysis(site, user, db) to pull fresh data and write a snapshot.
  2. Calls generate_report(site, user, db) to write the AI briefing.
  3. Delivers via email (api/services/email.py, sent through Resend) or Slack webhook.
  4. Updates last_sent and computes the next next_send based on frequency.

If analysis fails (expired token, empty data), the scheduler logs the error and leaves last_sent unchanged. It will retry on the next 15-minute tick until the schedule is due again.

Email delivery

Email reports are sent to the address on your SignalGuide account — the Google email you signed up with. The email service uses Resend (api/services/email.py). The report is formatted as HTML with the briefing text and a link back to your dashboard.

There is no option to send to a different email address at the schedule level today. The report goes to your account email.

Managing schedules

Viewing schedules

The Settings → Schedules tab lists all active schedules for the selected site, including last sent time and next send time. The data comes from GET /reports/schedules/{site_id}.

Deleting a schedule

Click the delete icon next to a schedule in Settings. The request hits DELETE /reports/schedules/{site_id}/{schedule_id}. Deleting a schedule stops future deliveries immediately.

On-demand report

You can trigger an on-demand report from the dashboard at any time — this runs analysis and generates a fresh briefing without touching the schedule. The endpoint is POST /reports/generate/{site_id}. Available on all plans.

Related: Slack integration.