# Routines — scheduled report refresh · Comma Docs

Canonical: https://commareports.com/docs/routines

> Routines re-run a skill on a schedule and append the output as a new revision of the same report. Setup, cadence, compute billing, manual runs, and the API surface.

# Routines

A routine is a cron for a report: on a schedule it runs a **skill**
(instructions for the model, optionally using **connectors** for external
data) and appends the output as a new revision of the same report. The URL
your team bookmarked on Monday shows Friday's numbers on Friday.

If you're evaluating the concept, the marketing overview is at
[Routines →](/features/routines); this page is the operational reference.

## The three pieces

- **Skill** — what to produce. A reusable instruction set the model runs
  ("query last week's signups, render the trend table…").
- **Connector** — what it may touch. Credentials for an external service
  (Slack, Stripe, your warehouse), encrypted at rest, granted to skills
  explicitly.
- **Routine** — when to run it and which report receives the revision.

## Creating a routine

In the app: **Routines → New routine**, pick or write a skill, set the
cadence, choose the destination report. Over the API:

```bash
curl -X POST https://commareports.com/api/v1/routines \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Weekly metrics", "skill_id": "…", "schedule": "…", "report_id": "…" }'
```

Agents can do the same through the MCP tools `create_routine` /
`update_routine` / `run_routine` — the `routines` token scope gates all of
it.

## Cadence and compute

Routines run at any cadence — manual, monthly, daily, hourly, or sub-hourly —
on every plan. There's no cadence gate.

Each run consumes AI compute, billed one of two ways:

- **Bring your own AWS Bedrock key** — runs bill to your AWS account, free on
  Comma, on any plan.
- **Prepaid credit** — use Comma's keys and draw down a prepaid balance
  (drawn at cost plus 20%). Hosted runs pause at a $0 balance, so there's
  never a surprise invoice.

Pooled credit across a team is a **Team** add-on (sales-led). Check your
numbers any time with `GET /api/v1/me/plan-caps` and `GET /api/v1/me/usage`.

## Running on demand

Every routine can be kicked outside its schedule:

```bash
curl -X POST https://commareports.com/api/v1/routines/ROUTINE_ID/run \
  -H "Authorization: Bearer $COMMA_API_TOKEN"
```

This is also the escape hatch for *external* schedulers — if your
orchestration already lives in Airflow or GitHub Actions, call `run` from
there and keep Comma as the publishing layer.

## What a run produces

- A new **revision** on the destination report — same URL, full history,
  [diffable](/docs/api) against any earlier revision.
- An automatic **changelog comment** summarizing what changed (rate-limited
  to one per report per 12 hours, so hourly routines don't spam the thread).
- Optional **webhook notifications** on `revision.created` — Slack, Discord,
  or plain JSON. See the [API reference →](/docs/api).

## Reviewers close the loop

Pair a routine with a standing **AI reviewer** and every refresh gets
checked — the reviewer reads the new revision and posts findings as
anchored comments before a human ever opens it. See
[Standing AI reviewers →](/launch/review-layer-for-ai-reports).