Background jobs console

Summary#

The Job Console shows the four recurring jobs that run without a user pressing anything: scheduled reports, rank alerts, the competitor monitor and tier-2 AI visibility tracking. For each it reports the last run, the next run, how many items it manages and whether any are due. An owner can trigger a job immediately. That trigger is not a forced re-run, and understanding why is most of what this page is for.

Purpose#

When a customer says their weekly report never arrived, there are only three possible causes: the schedule is not enabled, the job has not run, or the job ran and the send failed. This screen settles the first two in a glance, without a database query, and its Run due now button settles the third by making the job run while you watch.

Requirements#

• An active admin identity to read the screen. See Getting admin access.
• The owner role to trigger a job.
• MONITOR_DB bound. Every figure comes from D1.
• For the tier-2 job to do anything, OPENAI_API_KEY set on the environment.

Permissions#

A non-owner gets 403 {"error":"Only an owner can run jobs."} and does not see the button.

Navigation Path#

Admin console → Operations → Jobs

The screen's own title is Job Console.

How scheduling actually works#

This matters more than the screen does, because the console cannot tell you whether the scheduler is alive.

The worker has a scheduled() handler, but the site runs on Cloudflare Pages, and Pages never calls scheduled(). Cron triggers are a Workers feature. The jobs are therefore driven from outside, by an HTTP call:

• POST /api/cron/run runs whatever is due. Every job self-throttles in the database, so calling it often is safe and idempotent.
• A small standalone Cloudflare Worker in cron-worker/ holds a real cron trigger and calls that endpoint every 15 minutes. It is the primary scheduler and is deployed separately from the site.
• A GitHub Actions workflow calls the same endpoint hourly as a backup.

Both callers must present MV_INTERNAL_SECRET. The check fails closed: if the secret is unset on the Pages environment, /api/cron/run returns 503 and nothing runs at all. The same secret must match in three places: the Pages project, the cron worker's secrets, and the GitHub repository secrets.

Reading the table#

The table Scheduled & background jobs has six columns: Job, Status, Last run, Next run, Items, Actions.

Two of those columns need a caveat, and the screen states it in its own explainer: only tier-2 AI visibility records a true job-level last run. For the other three, Last run is derived from the most recently processed item, so an empty job with no items shows unknown even though the scheduler is calling it on time. Rank alerts and the competitor monitor have no computable next run at all, because each item carries its own interval, so their Next run is always —.

The four jobs#

Each row carries a note under the label. For rank alerts and the monitor it reads either <n> alert(s) due now. and <n> URL(s) due now., or the steady state Enabled alerts; each re-checked every 24h. and Enabled URLs; each on its own interval. For scheduled reports it reads Enabled schedules; last run = the last one that fired. For tier-2 it reads Tracked brands (up to 5 measured per run, ~every 22h)., or OPENAI_API_KEY not set — this job is a no-op. when the key is missing.

Step-by-Step Guide#

Check whether a job is running#

1. Select Jobs in the Operations group.
2. Read Last run for the job in question. A time within the expected cadence means the scheduler is reaching the worker.
3. Read Status. Due now for a sustained period means items are queuing up and the job is not being called, or is failing before it processes them.
4. Read Items. A count of zero explains an unknown last run without implying a fault.

Run a job now#

1. Press Run due now on the job's row. The button label becomes Starting….
2. The page shows Triggered <job> — it processes only items that are due. Refreshing status… and reloads the table after four seconds.
3. On failure the message is Error: <message>.

The endpoint returns immediately with {ok:true, job, triggered:true} and the job itself runs in the background, so a successful trigger tells you the job started, not that it finished. Re-read Last run after the refresh, and check the Run Log or the error log for what it did.

Every trigger is audited as jobs.run with the job key as the target. See Audit log.

What the endpoint accepts#

POST /api/admin/jobs/run takes { token, job } where job is one of monitor, schedules, rank_alerts or tier2. Anything else returns 400 {"error":"Unknown job."}. There is no rate limit, and no lock: pressing the button twice starts the job twice, though the due-item throttling means the second pass usually finds nothing left to do.

Troubleshooting#

FAQs#

Can I pause a job? Not from this screen. Three of the four are always enabled and tier-2 is enabled by the presence of an environment variable. Pausing individual work means disabling the individual schedules, alerts or monitored URLs.

Can I see what a job did on its last pass? Not here. The Job Console reports state, not output. Per-run detail lives in the Run Log, and failures group into the error log.

Does triggering a job cost anything? It costs whatever the due work costs in provider and model calls. Tier-2 measures up to five brands per run. Because only due items are processed, pressing the button does not multiply that cost.

Why is the scheduler a separate deploy? Because Pages cannot run cron. The cron worker is a real Cloudflare Worker with a cron trigger whose only job is to call /api/cron/run. Deploying the site does not deploy it.

Do jobs notify anyone when they fail? Not directly. Failures surface as grouped issues in the error log and, for failed automation steps, on the Workflow Failures screen. Nothing pages a human.