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

# Generate and download a report (API)

> Upload a template to Reporter, request a report from it, follow its status, and download the file.

Turn a template and the data in your data sources into a report file, and download the file when it is ready.

## Participants

***

* **Your institution.** Your system that calls the Reporter API.
* **Reporter.** Checks the template and the request, generates the report and serves the file.

## Before you start

***

* You have a bearer token that Access Manager issues for Reporter.
* You connected each data source that your template reads. See [Connect a data source](https://docs.lerian.studio/en/diagrams/lerian-products/reporter-connect-a-data-source.md).

## Diagram

***

![Generate and download a report](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-reporter-generate-a-report.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=4140f96b833f53190adf5aeb5969ffc0)

## Steps through the API

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Reporter | Lerian API | [`POST /v1/templates`](https://docs.lerian.studio/en/reference/products/reporter/upload-template) | Upload the template as a multipart form with the `template` file, `outputFormat`, `description` and `category`. |
| 2 | Reporter | Reporter | Internal step | | Reporter checks each data source, table and field that the template reads against the schema of the data source. |
| 3 | Reporter | Your institution | Response | | Reporter returns the template with its `id`. |
| 4 | Your institution | Reporter | Lerian API | [`POST /v1/reports`](https://docs.lerian.studio/en/reference/products/reporter/create-report) | Send `templateId` and `filters`. Add `parameters` when the template declares them, and an `X-Idempotency` key. |
| 5 | Reporter | Reporter | Internal step | | Reporter checks the filters and the parameters, records the report and starts the generation. |
| 6 | Reporter | Your institution | Response | | Reporter returns the report with its `id` and the status `Processing`. |
| 7 | Reporter | Reporter | Internal step | | Reporter extracts the data from each data source. The report ends as `Finished`, `Partial` or `Error`. For `Finished` and `Partial`, Reporter renders the template and stores the file. |
| 8 | Your institution | Reporter | Lerian API | [`GET /v1/reports/{id}`](https://docs.lerian.studio/en/reference/products/reporter/check-report-status) | Read the report. |
| 9 | Reporter | Your institution | Response | | Reporter returns the report with its `status`. |
| 10 | Your institution | Reporter | Lerian API | [`GET /v1/reports/{id}/download`](https://docs.lerian.studio/en/reference/products/reporter/download-report) | Download the file of a `Finished` report. |
| 11 | Reporter | Your institution | Response | | Reporter returns the file with the content type of its format and the `X-Report-Status` header. |

## Rules

***

* The `outputFormat` is `html`, `pdf`, `csv`, `xml` or `txt`. Write a `pdf` template in HTML. The `description` and the `category` are required.
* Reporter refuses a template that reads a data source, table or field that does not exist. When Reporter cannot reach a data source, it creates the template and returns a warning.
* A filter can only name a table that the template reads.
* Reporter refuses a request without a required parameter that has no default value.
* When you registered more than one institution in Reporter, send `institution` with an institution ID or with `all`.
* For 30 seconds, a repeat with the same `X-Idempotency` key returns the first report, with the header `X-Idempotency-Replayed: true`.
* Reporter refuses the download while the report is `Processing`, and when it is `Partial` or `Error`.

## How you know it finished

***

The report shows `Finished`, and the download returns the file with `X-Report-Status: Finished`.

## What can go wrong

***

| Situation | What you see | What to do |
| - | - | - |
| The template reads a data source that does not exist | `400` with `RPT-0031` | Connect the data source, or correct its name in the template. |
| A filter names a table that the template does not read | `400` with `RPT-0076` | Filter one of the tables that the message lists. |
| The same request is still in progress | `409` with `RPT-0039` | List the reports of the template before you send the request again. |
| The request times out | No answer | The report can exist. [List the reports](https://docs.lerian.studio/en/reference/products/reporter/retrieve-reports.md) of the template with `template_id` before you send the request again. |
| You download before the report is `Finished` | `422` with `RPT-0029` | Read the status, and download when it shows `Finished`. |
| The report ends as `Partial` or `Error` | `metadata` describes what failed | Read the cause, then request a new report. |

## Related

***

* [Connect a data source](https://docs.lerian.studio/en/diagrams/lerian-products/reporter-connect-a-data-source.md)
* [Receive the report result as an event](https://docs.lerian.studio/en/diagrams/lerian-products/reporter-receive-the-report-result.md)
* [How report generation works](https://docs.lerian.studio/en/products/reporter/how-report-generation-works.md)
* [Reporter template engine](https://docs.lerian.studio/en/products/reporter/reporter-template-engine.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.