---
title: "Create a routine"
method: POST
path: "/routines"
tags: ["Routines"]
---

# Create a routine

`POST /routines`

## Request

- Base URL: `https://commareports.com/api/v1`
- URL: `https://commareports.com/api/v1/routines`
- Auth: HTTP bearer

Schedule regeneration of a report on a 5-field cron. Provide `trigger_url` (webhook mode — Comma calls your endpoint on each tick) and/or `skill_id` (in-Comma run mode — the skill executes and appends a revision); at least one is required. Requires edit access on `report_id`. Plan ceilings (max routines / schedule floor) return 422. Scope: `routines`.

## Request body

- RoutineCreateRequest: At least one of trigger_url or skill_id is required.
  - `report_id` string, uuid, required
  - `name` string: Defaults to 'Untitled routine'.
  - `schedule_cron` string, required: Valid 5-field cron expression.
  - `trigger_url` string, uri: Webhook mode: Comma POSTs here on each tick.
  - `trigger_auth_header` string, nullable: Encrypted at rest; never returned.
  - `payload` unknown
  - `enabled` boolean
  - `skill_id` string, uuid, nullable: In-Comma run mode: the skill executes and appends a revision. Must be owned by you.
  - `connector_ids` string[]: Connectors the skill may read through. Each must be owned by you.

## Response `201`

Routine created.

- Routine
  - `id` string, uuid, required
  - `report_id` string, uuid, required
  - `name` string, required
  - `schedule_cron` string, required: 5-field cron expression.
  - `trigger_url` string, uri, nullable
  - `payload` unknown
  - `enabled` boolean, required
  - `last_run_at` string, date-time, nullable
  - `last_run_status` string, nullable
  - `last_run_error` string, nullable
  - `next_run_at` string, date-time, nullable
  - `skill_id` string, uuid, nullable
  - `connector_ids` string[]
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Malformed body or invalid field.
- `401`: Missing, invalid, revoked, or expired token.
- `403`: Token missing the required scope, or no access to the resource.
- `422`: Semantically invalid (e.g. plan ceiling exceeded, per-report asset count over 500).
- `429`: Rate limit exceeded. Rate limit: per-token sliding window (plan-aware — Free 60 req/min, Pro 600, Team/Enterprise 6000 by default); 429 responses carry a Retry-After header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/commareports/apis/comma-api.md) · [All operations](https://skmtc.dev/commareports/apis/comma-api/llms.txt) · [OpenAPI document](https://skmtc.dev/commareports/apis/comma-api/revisions/cd5263522ade?raw)