Scheduler

The Scheduler drives every recurring task in eCommerce Insights: PDP audits, Prompt Runs sessions, alert checks, and review re-pulls. Configure cadence per task (daily, weekly, monthly, custom cron). For users who run their own infrastructure, there is a /?api=cron_tick heartbeat endpoint.

What it does

The Scheduler is the heartbeat. Every recurring task in eCommerce Insights is registered with the scheduler and runs on its configured cadence.

Available cadences

Hourly

Useful for review re-pulls when the underlying source supports an API.

Daily

Useful for Agent Lens spot checks against a small set of canonical URLs.

Weekly

Default for PDP audits and Prompt Runs sessions. Balances signal freshness against cost.

Monthly

Useful for Persona re-clustering and brand-wide Sentiment rollups, both of which produce noisy drift if run more often.

Custom cron

A standard 5-field cron expression. Validated on save.

Per-task scheduling

Each registered task has its own cadence. Workspace-level defaults can be overridden per task. The most-used overrides:

• PDP audits scheduled twice weekly (Monday + Thursday) for fast-moving catalogues.
• Prompt Runs scheduled daily for the top-ten "must-win" prompts.
• Persona re-clustering scheduled quarterly instead of monthly for brands with stable customer bases.

Run history

The Schedule page exposes the last 100 runs per task with status, duration, error message (if any), and a one-click "view detail" link. Useful for diagnosing why a Prompt Runs session took 4x its usual time or why a PDP audit batch failed mid-run.

Cron-as-a-service heartbeat

Endpoint: GET /?api=cron_tick. Hitting this URL advances every task that is due.

# Every 5 minutes from your own cron host
*/5 * * * * curl -s "https://app.ecommerceinsights.ai/?api=cron_tick&workspace=YOUR_WORKSPACE_ID&token=YOUR_TOKEN" > /dev/null

Or from Render Cron / Vercel Cron / GitHub Actions:

# GitHub Actions
on:
  schedule:
    - cron: "*/5 * * * *"
jobs:
  tick:
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsSL "https://app.ecommerceinsights.ai/?api=cron_tick&workspace=${{ secrets.SHELFSCOPE_WS }}&token=${{ secrets.SHELFSCOPE_TOKEN }}"

Calls to the heartbeat are idempotent. Hitting it twice in the same minute is harmless — tasks only advance when they are due.

Manual "Run now"

Every task has a per-task "Run now" button on the Schedule page. There is also a workspace-level "Run scheduler now" button that triggers every due task in one shot.

Common questions