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

# Setup a report

> Learn how to create a report via the dashboard.

There are two ways to setup a report, either via the dashboard or via the API.

## Using dashboard

1. Go to Reports in the top bar
2. Choose the type of report to generate
3. Follow the creation steps
4. Check the report's executions in "Generated" tab
5. Download report

## Using API

### 1. Create a report

Use the [`POST {url}/reports/`](/reference/reports/new-report) API to create a report.

<CodeGroup>
  ```json Request theme={"system"}
  {
    "name": "Successful captures",
    "spec": {
      "params": {
        "fields": ["id", "captured_at", "amount"],
        "sort": [
          {
            "field": "created_at",
            "order": "asc"
          }
        ],
        "filters": {
          "status": ["capture_succeeded"]
        }
      }
    }
  }
  ```

  ```json Response theme={"system"}
  {
    "type": "report",
    "id": "71aa8d49-5ec7-43aa-b13c-9b16fdae0f9b",
    "name": "Successful captures",
    "created_at": "2022-10-28T10:15:36.547789+00:00",
    "updated_at": "2022-10-28T10:15:36.547789+00:00",
    "next_execution_at": null,
    "description": null,
    "schedule": "once",
    "schedule_enabled": false,
    "schedule_timezone": "Etc/UTC",
    "spec": {
      "model": "transactions",
      "params": {
        "sort": [
          {
            "field": "created_at",
            "order": "asc"
          }
        ],
        "fields": ["id", "captured_at", "amount"],
        "filters": {
          "method": null,
          "scheme": null,
          "status": ["capture_succeeded"],
          "currency": null,
          "metadata": null,
          "voided_at": null,
          "created_at": null,
          "captured_at": null,
          "authorized_at": null
        }
      }
    },
    "latest_execution": {
      "type": "report-execution",
      "id": "0848ef01-f44a-4564-abdb-52a1344bac63",
      "created_at": "2022-10-28T10:15:36.571232+00:00",
      "updated_at": "2022-10-28T10:15:36.611495+00:00",
      "status": "dispatched",
      "context": {
        "reference_timestamp": "2022-10-28T10:15:36.571232+00:00",
        "reference_timezone": "Etc/UTC"
      }
    }
  }
  ```
</CodeGroup>

### 2. Check report's executions (optional)

Next, [list all the executions for a report](/reference/reports/list-executions-for-report) can be done.

<CodeGroup>
  ```json Response theme={"system"}
  {
    "items": [
      {
        "type": "report-execution",
        "id": "0848ef01-f44a-4564-abdb-52a1344bac63",
        "created_at": "2022-10-28T10:15:36.571232+00:00",
        "updated_at": "2022-10-28T10:15:36.611495+00:00",
        "status": "dispatched",
        "context": {
          "reference_timestamp": "2022-10-28T10:15:36.571232+00:00",
          "reference_timezone": "Etc/UTC"
        },
        "report": {
          "type": "report",
          "id": "71aa8d49-5ec7-43aa-b13c-9b16fdae0f9b",
          "name": "Successful captures"
        }
      }
    ],
    "limit": 20,
    "next_cursor": null,
    "previous_cursor": null
  }
  ```
</CodeGroup>

### 3. Generate report's execution URL

To download the file for an execution, [check the status of the execution](/reference/reports/get-report-execution) is `succeeded`, and
then [request the download URL](/reference/reports/generate-download-url).

<CodeGroup>
  ```json Response theme={"system"}
  {
    "url": "https://url/to/report/file",
    "expires_at": "2022-10-28T10:21:33.345947+00:00"
  }
  ```
</CodeGroup>

The report can be downloaded from the `url` until it expires at `expires_at`.

## Webhooks & error handling

When a report is generated, it triggers a `report-execution.succeeded` [webhook event](/guides/features/webhooks/events).

If the generation fails for some reason, a `report-execution.failed` is sent. This event is triggered when
a report fails to generate due to an unexpected internal technical issue. The report generation is not retried, and instead, the following steps to resolve the issue are recommended.

* **One-off reports:** A new one-off report must be created.
* **Scheduled reports:** As the report does not run for the failed period, creating a new one-off report for the same period to download the data is recommended.

If this event is received frequently, or a one-off report cannot be created, please contact the
support team with the details of the report.