# Create Report Run

> POST /v1/reporting/reports/runs

`POST https://app.untetherlabs.com/api/v1/reporting/reports/runs`

This endpoint is in beta.

<Warning>This is a beta endpoint. Breaking changes may occur without notice, use at your own risk.</Warning>

Create a new report run for the given report ID.

The report parameters depend on the report being executed,
see the report documentation for more info.

Reports are generated asynchronously. The returned object
will always be marked as `running`, you will have to
periodically poll for status changes.

## Request

```bash
curl -X POST 'https://app.untetherlabs.com/api/v1/reporting/reports/runs' \
  -H 'Authorization: Bearer $UNTETHER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d @body.json
```

## Request body (application/json)

- `reportId` (string, required, example "payroll-report")
- `parameters` (object, example {"startDate":"2025-01-01","endDate":"2025-01-31"})

## Response 201

- `reportId` (string, required, example "payroll-report")
- `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
- `createdBy` (ReportUser, required)
  - `name` (string, required, example "Bruce Wayne")
- `status` (ReportStatus, required, one of `running`, `completed`, `failed`)
- `file` (object) — Only present if the report has been completed.
  - `name` (string, required, example "payroll-2025-01-01.csv")
  - `mediaType` (string, required, example "text/csv")
  - `sizeBytes` (number, required, min 0)

## Errors

- `report-parameter-validation` (400) — A report parameter did not pass validation, see message.
- `validation` (400) — Input validation failed.
- `report-not-found` (404) — A specified report does not exist in the system.
- `user-not-found` (404) — A specified user does not exist in the system.