> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report templates

> Structure, fields, and configuration options for the ReportTemplate model.

A **Report template** is the reusable definition of a report. It binds
together the data sources, output formats, narrative configuration,
default destinations, and ownership metadata. One template can power
many schedules.

<Note>
  Templates can be created, previewed, and **run on demand** regardless of
  whether the background cron is wired. The **Run Now** button and the
  `POST /api/v1/reports/templates/[id]/run-now` API execute the full
  pipeline (sources → narrative → formats → delivery) immediately without
  depending on AWS EventBridge or any external scheduler.

  Templates only rely on the cron when they're attached to a
  [schedule](./report-schedules) and you want the schedule to fire
  automatically. See [EventBridge Setup](../self-host/deploy/eventbridge-setup)
  (optional during pilot).
</Note>

## Schema

```prisma theme={null}
model ReportTemplate {
  id           String   @id @default(uuid())
  tenantId     String
  name         String
  description  String   @default("")
  ownerUserId  String?
  dataSources  Json     @default("[]")
  sections     Json     @default("[]")
  formats      Json     @default("[\"pdf\"]")
  narrative    Json     @default("{\"enabled\":true}")
  filters      Json     @default("{}")
  enabled      Boolean  @default(true)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}
```

## `dataSources`

Ordered array. Each entry references a registered data source by key:

```json theme={null}
[
  { "sourceKey": "offer_performance", "params": { "days": 7, "limit": 20 } },
  { "sourceKey": "channel_effectiveness", "params": { "days": 7 } }
]
```

Parameters are Zod-validated by the adapter at run time. Invalid
parameters surface as a single-row error section rather than aborting
the run.

## `sections`

Optional presentation metadata keyed by `dataSourceIndex`. Use this to
override the auto-generated section title or provide an `id` that is
referenced by the narrator:

```json theme={null}
[
  { "id": "perf", "title": "Offer performance this week", "dataSourceIndex": 0 },
  { "id": "ch",   "title": "Channel breakdown",          "dataSourceIndex": 1 }
]
```

When omitted, sections auto-generate with ids `s1`, `s2`, … and titles
derived from the source's `label` field.

## `formats`

Array of format keys. Each produces one artifact per run. Supported in
the current release:

* `pdf`
* `csv`
* `markdown`
* `html`

## `narrative`

```json theme={null}
{
  "enabled": true,
  "prompt": "Call out retention risks; ignore synthetic test tenants.",
  "modelOverride": "claude-sonnet-4-5-20250929"
}
```

* `enabled`: when `false`, the narrator is skipped entirely.
* `prompt`: optional addendum appended to the system prompt.
* `modelOverride`: provider-specific model name. Falls back to the
  tenant default when omitted.

## `filters`

Arbitrary Json used for cross-section filtering. Currently recognised:

* `filters.destinations`: array of notification-provider UUIDs used as
  fallback destinations when a run is triggered via `/run-now` without
  a schedule.

Future versions will add report-wide time windows, segment filters, and
global parameter overrides here.

## Running a template

Two unconditional invocation paths:

* **Preview** — `POST /api/v1/reports/templates/[id]/preview` runs every
  data source + narrator and returns the rendered result **without**
  persisting a run record or dispatching to destinations. Used by the
  `/settings/reports` live-preview pane.
* **Run Now** — `POST /api/v1/reports/templates/[id]/run-now` executes the
  full pipeline (persists a run record and dispatches to every configured
  destination). Works independently of the cron.

For automated scheduled firing, attach the template to a
[ReportSchedule](./report-schedules) and wire the cron — see
[EventBridge Setup](../self-host/deploy/eventbridge-setup).

## API

See the [Reports API reference](/api-reference/reports) for the full
route table.