---
title: "[beta] Create a custom report run"
method: POST
path: "/reports/runs"
tags: ["Beta APIs"]
---

# \[beta\] Create a custom report run

`POST /reports/runs`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/reports/runs`
- Auth: HTTP bearer

Triggers a new custom report run based on the provided configuration.

 <b>Rate limit:</b> 50 requests/hour (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Custom Reports** under the Custom Reports category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- ReportsCreateReportRunRequestBody: Contains information required to trigger report run
  - `reportConfig` CreateReportConfigObjectRequestBody, required: Contains report config for a given report run.
    - `columns` CreateReportConfigColumnRequestBody[]: Columns to include in the report. Only one of ID or datasetId and columns must be provided.
      - `fieldName` string, required: Name of the field from the dataset.
    - `datasetId` string: ID of the dataset that is going to be used for the report. Only one of ID or datasetId and columns must be provided.
    - `filters` FiltersRequestBody: Contains filters that are going to be applied to this report run.
      - `primaryTimeRange` PrimaryTimeRangeRequestBody: Primary time range of the report that not all datasets and report configs support.
        - `endTime` string, date-time, required: End time of the time range filter in RFC3339 format.
        - `startTime` string, date-time, required: Start time of the time range filter in RFC3339 format.
    - `id` string: ID of the custom report config. Only one of ID or datasetId and columns must be provided.

## Response `202`

Accepted response.

- ReportsCreateReportRunResponseBody
  - `data` ReportRunObjectResponseBody, required: Base custom report run response object.
    - `createdAtTime` string, date-time, required: Time when the report run was created in RFC3339 format.
    - `id` string, required: ID of report run.
    - `status` 'complete' | 'pending' | 'failed' | 'canceled' | 'unknown', required: Status of the report run. Valid values: `complete`, `pending`, `failed`, `canceled`, `unknown`
    - `updatedAtTime` string, date-time, required: Time when the report run was last updated in RFC3339 format.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)