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

# Report templates

> List Gu1 operational report templates and queue async runs to object storage (optional email).

## Overview

Gu1 publishes a **code-first catalog** of operational templates (alerts by rules, bulk exports, and Metrics Hub views). The same templates power **Reporting** (on demand) and the automation action **`send_report` / Generar reporte** (`reportPresetId` or `reportTemplateCode` + params).

| Method | Path                               | Use                                        |
| ------ | ---------------------------------- | ------------------------------------------ |
| `GET`  | `/report-templates`                | List catalog (optional `category`)         |
| `GET`  | `/report-templates/{code}`         | Detail + `parameterDefinitions`            |
| `POST` | `/report-templates/{code}/preview` | Download CSV/PDF preview with sample data  |
| `POST` | `/report-templates/{code}/run`     | Queue async export (`download` or `email`) |

All operational runs (**including `alerts_by_rules`**) enqueue a background job, store the file in object storage, and return **202** with `result.jobId`. Download later from [Report export jobs](/en/api-reference/entities/report-export-jobs) (Reporting **Descargables**). They share the org export **cooldown** when applicable.

## Authentication and tenant

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY` — see [Authentication](/en/api-reference/authentication).
</ParamField>

<ParamField header="X-Organization-ID" type="string" required>
  Production or sandbox organization UUID — see [Environments](/en/api-reference/environments).
</ParamField>

## Permissions

| Endpoint             | Granular permission |
| -------------------- | ------------------- |
| `GET` list / get     | `reports:read`      |
| `POST` preview / run | `reports:export`    |

## List templates

```
GET http://api.gu1.ai/report-templates
```

<ParamField query="category" type="string">
  Optional filter: `alerts`, `metrics`, `entities`, `transactions`, `investigations`.
</ParamField>

## Get a template

```
GET http://api.gu1.ai/report-templates/{code}
```

Returns `404` with `REPORT_TEMPLATE_NOT_FOUND` if the code does not exist.

## Preview (sample data)

```
POST http://api.gu1.ai/report-templates/{code}/preview
```

Returns a **CSV** or **PDF** file with demo rows (does not query tenant data).

<ParamField body="format" type="string">
  `csv` (default) or `pdf`.
</ParamField>

<ParamField body="emailLocale" type="string">
  Optional: `es`, `en`, or `pt` (PDF copy).
</ParamField>

Response: binary with `Content-Disposition: attachment` (`preview-{code}.csv|pdf`).

## Run a template

```
POST http://api.gu1.ai/report-templates/{code}/run
```

<ParamField body="params" type="object">
  Template parameters (`lookbackDays`, `ruleIds`, `emailLocale`, `filters`, etc.).
</ParamField>

<ParamField body="format" type="string">
  Must be in the template `formats`. Default: `defaultFormat`.
</ParamField>

<ParamField body="delivery" type="string" required>
  `download` (queue job only) or `email` (queue job + send mail). Reporting UI always uses `download`.
</ParamField>

<ParamField body="recipientEmails" type="string[]">
  Required when `delivery` is `email`.
</ParamField>

### Response (202)

```json theme={null}
{
  "success": true,
  "result": {
    "success": true,
    "jobId": "…",
    "status": "queued",
    "delivery": "download"
  }
}
```

### Semantics: `alerts_by_rules`

Exports **already-created alerts** for the tenant whose `alerted_at` falls in the `lookbackDays` window.

* **`ruleIds`** (UUID array, optional): when set, filters `trigger_rule_id IN (...)`. Empty = all rules.
* Columns: entity, tax ID, alert, severity, status, score, rule, investigation number, case/alert link, date.
* Order: entity name, then alert date.
* Does not re-run the matrix or invent thresholds: only lists persisted alerts.

### Rate limit

If another org export ran recently, the API may return **429** with `EXPORT_RATE_LIMIT`, `Retry-After`, and `retryAfterSeconds` / `cooldownSeconds` in `error.details`.

### Example

```json theme={null}
{
  "params": {
    "lookbackDays": 30,
    "ruleIds": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"]
  },
  "format": "xlsx",
  "delivery": "email",
  "recipientEmails": ["ops@example.com"]
}
```

### 202 response (email)

```json theme={null}
{
  "success": true,
  "result": {
    "success": true,
    "code": "alerts_by_rules",
    "delivery": "email",
    "jobId": "…",
    "status": "queued"
  }
}
```

### 202 response (download)

```json theme={null}
{
  "success": true,
  "result": {
    "success": true,
    "code": "alerts_by_rules",
    "delivery": "download",
    "jobId": "…",
    "status": "queued"
  }
}
```

## Automations

Scheduled delivery uses `send_report` (**Generar reporte**) with either:

* **`reportPresetId`** (canonical): runs the frozen preset; always creates an S3 job. Set `sendEmail: true` plus `recipientEmails` to also email the file.
* Legacy: `reportTemplateCode` + `params`, or `reportType` without a preset.

Deep-link from Reporting **Programar**: `/automations/builder?type=scheduled&reportPresetId=…`.

See [Report export jobs](/en/api-reference/entities/report-export-jobs) for Descargables.

## Configurable filters

Operational templates expose a `field → operator → value` builder. Send conditions in `params.filters`; every condition is combined with **AND**. An empty list includes all records. Saved [report presets](/en/api-reference/entities/report-presets) freeze the complete conditions.

Catalog-backed fields change their control according to the operator: `equals` receives one value and `in` receives an array. For example, country accepts `{ "operator": "equals", "value": "AR" }` or `{ "operator": "in", "value": ["AR", "BR"] }`.

```json theme={null}
{
  "params": {
    "filters": [
      { "id": "f1", "field": "tax_id", "operator": "in_custom_list", "value": "11111111-1111-4111-8111-111111111111" },
      { "id": "f2", "field": "age", "operator": "gte", "value": "18" },
      { "id": "f3", "field": "is_pep", "operator": "is_true", "value": "" }
    ]
  },
  "format": "xlsx",
  "delivery": "download"
}
```

* **Alerts:** rule (`in`), severity, status, affected type, score, false-positive flag, alert date and alert type.
* **Entities:** type, status, exact Tax ID or custom-list membership, country, external ID, search, age, score, KYC status, matched rule, creation/enrichment dates, PEP, sanctions, adverse media, MEI, legal proceedings —including criminal proceedings—, shareholders, relationships, electoral activity, economic activities and active investigations.
* **Transactions:** type, status, payment method, score, amount, currency, date, matched rule, related Tax ID, origin/destination external IDs, self-transactions, missing risk evaluation, shadow-rule hits, search, flagged state and alert presence.
* **Investigations:** status, priority, typology, score, target type, creation/update dates and title/description search.

Available operators depend on the field: `equals`, `contains`, `in`, `gte`, `lte`, `between`, `before`, `after`, `is_true`, `is_false`, `in_custom_list`, and `not_in_custom_list`. The catalog returned by `GET /report-templates` includes `filterFields` with each template's valid operators and options.