Skip to main content

Scheduling and Delivery

A report that has to be run by hand is a report that stops being run. This page covers the operational half of reporting: putting a report on a recurrence, getting the timezone right, sending the output somewhere useful, and reading the run history afterward to confirm it worked and to see what it cost. Everything here happens on Configuration → Report Scheduler (/v2/configuration/report-scheduler; v1: Reports → Scheduler, /reports/scheduler).

The Scheduler Page​

What the Table Shows​

One row per schedulable report, with Group, Name, Description / Arguments, Schedule, Prior Runs, Updated On (UTC), and Actions. Group is the category or origin of the report (a vendor name, or System), or – when it has none. An unscheduled report shows Not scheduled in the Schedule column; a scheduled one shows its interval, such as daily.

Report Scheduler page with a Refresh button, a Search reports field, a Last Updated sort drop-down, and a table of reports with Group, Name, Description / Arguments, Schedule, Prior Runs, Updated On (UTC), and Edit and Schedule actions on each row

The page header carries a Back to Configuration link above the title Report Scheduler, with a Refresh button on the right that reloads the table. A Search reports field and a sort drop-down sit above the table.

Finding a Report​

Type in Search reports to narrow the table to the matching reports, and sort by Last Updated (most recently changed first, the default), Report Name: A–Z, or Report Name: Z–A.

Row Actions​

Edit and Schedule sit on every row, and a red Delete on reports the site can remove (it asks for confirmation first). Schedule is covered below.

Edit opens Edit FPL Report, which holds the report's read-only Report Name, its Description, the Processor the report runs as a link (the processor can carry a different name than the report), the report's FPL in a code editor (read-only for a report that runs a processor: the Processor link opens the processor in the report editor, where its code is changed), and, for a report that takes arguments, an arguments table with Name, Description, Type, and Default Value, one row per declared argument. Update saves the changes; Cancel closes without saving.

Edit FPL Report dialog for System_Event_Ingress_Report, with the read-only Report Name, the Description field, the Processor link, the report's FPL in a code editor, the start of its arguments table, and Cancel and Update buttons

Running a Report on Demand​

The Run Dialog​

The Report Scheduler has no run action. To run a report now, open it on the FPL reports tab of Reports and click Run in the editor; the run and its output are then listed on Admin console → Management → Report Tasks. The run dialog, with its editable arguments table, is in the v1 interface: the green play icon on Reports → Scheduler.

Supplying Arguments for a Run​

Overriding the declared defaults for this run only: for example setting from to ago(7d) and to to now(), or naming the user a per-subject investigation report should cover. The argument model itself is in Creating a Report.

Scheduling a Report​

Enabling the Schedule​

Schedule opens Schedule Report, with the read-only Report Name and a Set Schedule switch. With the switch off, the report runs only when started by hand, and the dialog shows nothing more than Daily archive. Turning it on reveals an Interval drop-down (hourly, daily, weekly, or monthly) and the fields that interval needs:

IntervalFields
hourlyMinute: the minute past each hour, 0 to 59.
dailyHour (0–23), Minute, and Timezone.
weeklyWeekday, Hour, Minute, and Timezone.
monthlyDay of the month, Hour, Minute, and Timezone.

Below them are Daily archive and Exports. Schedule saves, with the notice Report schedule updated., and the row's Schedule column shows the new interval; Cancel closes without saving. For an already-scheduled report the dialog opens with Set Schedule on and the current settings loaded.

Schedule Report dialog for a daily report, with Set Schedule on, Interval daily, Hour and Minute 0, Timezone GMT, the Daily archive switch off with its note, and Cancel and Schedule buttons

Timezone​

The timezone selector (for example GMT) that the hour and minute are interpreted in. This is the single most common source of "the report ran at the wrong time" tickets: the schedule's timezone, the timezone the data is stamped in, and the timezone the reader is in are three separate things and need not agree.

Archiving Daily Results​

A report can keep every day's result for 12 months. With the archive on, the report runs once a day over exactly the previous calendar day, so the stored days fit together with no gaps or overlaps. A week, a month or a quarter can then be assembled from them without one long run, even for a report that refuses ranges that long. The run history on this page keeps only a report's 24 most recent runs.

What the Archive Does​

  • Fixed daily windows. Each run covers 00:00 to 24:00 of the previous day in the archive timezone. The platform passes that window to the report as RFC 3339 values of its from and to arguments, in place of their defaults. On a daylight-saving changeover a local day is 23 or 25 hours long.
  • Twelve months of days. Each day's result is kept with its row count and the version of the report script it ran on. A day is completed, aborted or running; days older than 12 months are removed.
  • Today is never in it. A day is archived after it ends.

If the report is also scheduled, give it a daily interval, and pick a run time a little after midnight in the archive timezone, so late-arriving data for the previous day has landed before the run reads it.

Turning the Archive On​

Turn on the Daily archive switch in Schedule Report. Its note reads Archiving does not require a report schedule. If scheduling is enabled, use a daily interval. Archived results are kept for 12 months. Turning it on does not schedule the report. It adds three fields:

  • Archive timezone: where each day starts and ends; UTC by default.
  • Window start argument and Window end argument: leave them empty when the report's window arguments are named from and to; otherwise enter the report's own argument names.

If Set Schedule is also on, the Interval must be daily: turning the archive on while the interval is hourly clears it, and the list then offers only daily. Schedule without a daily interval reports Scheduled archiving requires a daily interval. Select daily or turn off the report schedule. The dialog is described on Report Scheduler.

On the report's definition, the archive is an archive block next to the schedule:

"scheduleFlag": true,
"schedule": { "interval": "daily", "hour": 3, "minute": 15, "timezone": "GMT" },
"archive":  { "enabled": true, "timezone": "UTC" }
FieldMeaning
enabledTurns the archive on. A report that is also scheduled must run daily; any other interval is refused.
timezoneWhere a day starts and ends, as an IANA name such as America/New_York. The default is UTC. It is separate from schedule.timezone, which only sets when the run fires.
argFrom, argToThe names of the report's window arguments, when they are not from and to. The two must differ, and the report must declare both.

Once days are stored, the archive timezone cannot be changed; a different timezone means starting a new archive. For a report managed in git, add the archive block to the report's file in the Scripts repo, next to schedule.

Days exist from the moment the archive is on. Earlier days can be backfilled, up to 92 at a time, while their source data is still in the datalake.

Using the Archive​

The archived reports are listed on Admin console → Management → Archived Reports: which days each archive covers and which it misses, each run's stored output, and a Backfill for the missing days.

The archive is also read through the MCP server: list_report_archive shows which days exist and which are missing, download_report_archive fetches up to 92 days at a time, and backfill_report_archive runs the report for missing past days. In Claude, the fluency-report-rollup skill from the ingext_skills repository does the assembling: ask for a month, a quarter or a trend, and it checks coverage, merges the days the way the report computes its numbers, and states on the page which days it covers. The merge rules and a worked example are in the Report Archive release notes.

Delivery and Exports​

The Exports Setting​

Exports in the Schedule dialog lists the Export destinations the report's output is sent to, picked from an Add… drop-down of the site's notification endpoints, such as Email:BehaviorSummary_Export. Each one picked shows as a chip with an × that removes it. The endpoints themselves are set up on Configuration → Notifications; see Notifications.

Exporting the Report Definition​

Distinct from delivering output: report definitions are exported and imported in the v1 interface, with the Export and Import buttons on Reports → Scheduler.

This is how reports move between accounts and into source control.

Run History​

Prior Runs​

The number in the Prior Runs column opens the Prior Runs dialog, headed with the report's name, which lists its runs newest first: ID, Status, Launched On (UTC), Time Taken, Cost, and an Actions column whose View button shows that run's output below the table, with a Refresh result button. Close closes the dialog.

Prior Runs dialog for a report, listing its runs with ID, Status, Launched On (UTC), Time Taken, Cost, and a View button on each row

Every report's runs, scheduled or not, are also listed on Admin console → Management → Report Tasks, with the user who started each one; click a row to open the report with that run's output loaded.

Run Status​

completed for a normal finish and aborted for a run that did not. Timeouts, errors in the processor and missing indexes are the usual causes; see Troubleshooting.

Cost​

The Cost column shows what a run was billed. Cost follows bytes scanned, so narrower windows, fewer indexes and earlier filtering are what bring a costly report down. See the Usage Report (v1: Platform → Usage).

Last updated on