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

# Reports

> Create, schedule, and export reports — from one-off risk summaries to recurring executive digests delivered to your team.

**Reports** let you package Causeloop's analysis into shareable, time-bound summaries. You can generate a one-off report on demand, schedule recurring reports on a cron schedule, and export the underlying data in CSV, XLSX, JSON, or PDF format.

## The Reports screen

Navigate to **Reports** in the left sidebar. The top-bar range control (**7D / 30D / 90D**) sets the default data window for new reports and for the live preview.

## Creating a report

<Steps>
  <Step title="Open the Reports screen">
    Click **Reports** in the left sidebar.
  </Step>

  <Step title="Click New report">
    The report creation dialog opens.
  </Step>

  <Step title="Choose a template or type">
    Select from the available templates (see [Report templates](#report-templates) below), or choose a blank report and configure sections manually.
  </Step>

  <Step title="Set the window">
    Choose a data window: **7D**, **30D**, or **90D**.
  </Step>

  <Step title="Choose a format">
    Select **CSV**, **XLSX**, **JSON**, or **PDF**. PDF is recommended for executive sharing; CSV/XLSX for data imports.
  </Step>

  <Step title="Generate">
    Click **Generate**. The report is created asynchronously. A job appears in the Jobs list — poll it until `status` is `succeeded`, then download from the `download_url`.
  </Step>
</Steps>

Report generation is handled by `POST /v1/reports/generate`. The response includes a `job_id` to poll at `GET /v1/reports/jobs/{job_id}`.

## Report templates

Use `GET /v1/reports/templates` to list the available built-in templates. Templates include pre-configured sections tailored to common use cases:

| Template                    | Typical sections                                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Executive summary**       | KPI snapshot, top patterns, risk trend, loops prevented                                                        |
| **Pattern analysis**        | Full pattern list with risk scores, frequency charts, recommendations                                          |
| **Issue digest**            | Filtered issue list with analysis summaries                                                                    |
| **Prediction report**       | Forecast chart, probability matrix, model accuracy (backtest-derived; shows `no_backtest_yet` if none has run) |
| **Recommendation coverage** | Recommendation list with implementation status and attestation state                                           |

## Scheduling reports

Scheduled reports run automatically on a cron expression and deliver results to a list of recipients.

### Creating a schedule

<Steps>
  <Step title="Open Schedules">
    In the Reports screen, click the **Schedules** tab.
  </Step>

  <Step title="Click New schedule">
    The schedule creation dialog opens.
  </Step>

  <Step title="Configure the schedule">
    Fill in:

    * **Name** — a label for this schedule
    * **Cron expression** — e.g. `0 9 * * MON` for every Monday at 09:00
    * **Timezone** — e.g. `America/New_York`
    * **Report type and window** — which report to run and over what period
    * **Recipients** — email addresses or Slack channel IDs to deliver to
    * **Format** — output format (PDF recommended for email delivery)
  </Step>

  <Step title="Save">
    The schedule is active immediately. The `next_run_at` timestamp shows when it will first fire.
  </Step>
</Steps>

Schedules are created via `POST /v1/reports/schedules`. To run a schedule immediately without waiting for the next cron trigger, use `POST /v1/reports/schedules/{id}/run-now`.

### Managing schedules

* **List all schedules**: `GET /v1/reports/schedules`
* **Update a schedule**: `PATCH /v1/reports/schedules/{id}` — update the cron, timezone, recipients, or format
* **Delete a schedule**: `DELETE /v1/reports/schedules/{id}`

You can also attach schedules directly to a specific report definition:

* `POST /v1/reports/{id}/schedules` — add a per-report schedule
* `PATCH /v1/reports/{id}/schedules/{sched_id}` — update it
* `DELETE /v1/reports/{id}/schedules/{sched_id}` — remove it

## Viewing report history

Each saved report definition accumulates a run history. Open a report and switch to the **Runs** tab to see past executions with their status, duration, and download links.

* List runs: `GET /v1/reports/{id}/runs`
* Get a specific run: `GET /v1/reports/{id}/runs/{run_id}`
* Trigger a new run: `POST /v1/reports/{id}/run` (returns `202 Accepted` with a `job_id`)

## Exporting data

In addition to structured reports, you can export the raw data behind any Causeloop entity.

### Creating an export

<Steps>
  <Step title="Click Export">
    The Export button is available in the top bar of the Issues, Patterns, Predictions, and Recommendations list views.
  </Step>

  <Step title="Choose a format">
    Select **CSV**, **XLSX**, **JSON**, or **PDF**.
  </Step>

  <Step title="Apply filters (optional)">
    Exports respect the same filter parameters as the list endpoints. For example, export only P1 issues resolved in the last 30 days.
  </Step>

  <Step title="Download">
    Exports are asynchronous. A job is created via `POST /v1/exports`. Poll `GET /v1/exports/{id}` until `status` is `succeeded`, then download from `download_url`.
  </Step>
</Steps>

Exportable resources:

| Resource          | Description                                       |
| ----------------- | ------------------------------------------------- |
| `issues`          | Issue list with optional AI analysis columns      |
| `patterns`        | Pattern list with risk scores and recommendations |
| `predictions`     | Prediction list with probability and impact       |
| `recommendations` | Recommendation list with status and attestation   |
| `audit_log`       | Workspace audit trail (admin only)                |
| `members`         | Member directory                                  |
| `connectors`      | Connector configuration list                      |

<Note>
  Exports require the `reports:write` scope. PDF exports may take longer to generate than CSV/XLSX. Large exports are automatically chunked.
</Note>

## API reference

| Endpoint                     | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `GET /v1/reports`            | List saved report definitions                |
| `POST /v1/reports`           | Create a report                              |
| `POST /v1/reports/generate`  | Generate a one-off report                    |
| `GET /v1/reports/templates`  | List built-in templates                      |
| `GET /v1/reports/jobs`       | List all report and export jobs              |
| `GET /v1/reports/jobs/{id}`  | Poll a single job                            |
| `GET /v1/reports/{id}`       | Get a report definition                      |
| `PATCH /v1/reports/{id}`     | Update name, description, format, or filters |
| `DELETE /v1/reports/{id}`    | Delete a report                              |
| `POST /v1/reports/{id}/run`  | Trigger an immediate run                     |
| `GET /v1/reports/schedules`  | List workspace-level schedules               |
| `POST /v1/reports/schedules` | Create a workspace-level schedule            |
| `POST /v1/exports`           | Create an async export job                   |
| `GET /v1/exports/{id}`       | Poll an export job                           |

## Related pages

<CardGroup cols={2}>
  <Card title="Dashboard" icon="gauge" href="/product-guide/dashboard">
    The live dashboard — use reports for point-in-time snapshots.
  </Card>

  <Card title="Recommendations" icon="lightbulb" href="/product-guide/recommendations">
    Include recommendation coverage and attestation in reports.
  </Card>

  <Card title="Notifications & Alerts" icon="bell" href="/product-guide/notifications-alerts">
    Get notified when a scheduled report is ready.
  </Card>
</CardGroup>