---
title: "Generate a report"
method: POST
path: "/reports"
tags: ["Reports and Statements"]
---

# Generate a report

`POST /reports`

## Request

- Base URL: `https://api.whatnot.com/seller-api/rest/v2`
- URL: `https://api.whatnot.com/seller-api/rest/v2/reports`
- Auth: OAuth 2
  - Authorization code: `https://api.whatnot.com/seller-api/rest/oauth/authorize`
  - Token URL: `https://api.whatnot.com/seller-api/rest/oauth/token`

Request a report generation run and return it. `report_type` selects the kind of report and the parameters it accepts. The run is created `pending`; generation happens asynchronously. When an identical request is already in flight or recently completed, that existing run is returned instead of starting a new one. Requires write:reports.

## Request body

- GenerateReportRequest
  - `report_parameters` union, required: The parameters of the report to generate. `report_type` selects the kind of report and the other fields it accepts.
    - FinancialReportParameters: Parameters for a `seller_financial_report` run.
      - `report_type` 'seller_financial_report', required: The type of report these parameters describe.
      - `start_date` string, date-time, nullable: Include only transactions completed at or after this time. Defaults to one week before `end_date`.
      - `end_date` string, date-time, nullable: Include only transactions completed before this time. Defaults to one week after `start_date`, or to the current hour when neither end is given.
    - AnalyticsOverviewReportParameters: Parameters for an `analytics_overview_report` run. The report is one row per calendar day of the window.
      - `report_type` 'analytics_overview_report', required: The type of report these parameters describe.
      - `start_at` string, date-time, required: The start of the reported window.
      - `end_at` string, date-time, required: The end of the reported window. Must be after `start_at`.
    - LivestreamsReportParameters: Parameters for an `analytics_livestreams_report` run. Exactly one of `all_matching` and `specific_shows` selects the shows.
      - `report_type` 'analytics_livestreams_report', required: The type of report these parameters describe.
      - `all_matching` MatchingShowsFilter: Which of the seller's shows an `all_matching` report covers.
        - `title` string, nullable: Include only shows whose title matches this text.
        - `start_time` ShowStartTimeRange
          - `start` string, date-time, required: Include only shows that started at or after this time.
          - `end` string, date-time, nullable: Include only shows that started at or before this time. Defaults to the end of the current hour.
      - `specific_shows` SpecificShows
        - `show_ids` string[], required: The shows to report on, in the order their rows appear. Every show must be hosted by the seller.

## Response `201`

The run that will produce the report.

- Report: One asynchronous report generation run. Runs are created `pending`; generation happens asynchronously.
  - `id` string, uuid, required: The report run's ID.
  - `report_type` 'seller_financial_report' | 'analytics_overview_report' | 'analytics_livestreams_report', required
  - `status` 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled', required
  - `report_parameters` union, required: The parameters this run covers, after defaults were applied. The shape depends on `report_type`. Null when the run has no parameters.
    - FinancialReportParameters: Parameters for a `seller_financial_report` run.
      - `report_type` 'seller_financial_report', required: The type of report these parameters describe.
      - `start_date` string, date-time, nullable: Include only transactions completed at or after this time. Defaults to one week before `end_date`.
      - `end_date` string, date-time, nullable: Include only transactions completed before this time. Defaults to one week after `start_date`, or to the current hour when neither end is given.
    - AnalyticsOverviewReportParameters: Parameters for an `analytics_overview_report` run. The report is one row per calendar day of the window.
      - `report_type` 'analytics_overview_report', required: The type of report these parameters describe.
      - `start_at` string, date-time, required: The start of the reported window.
      - `end_at` string, date-time, required: The end of the reported window. Must be after `start_at`.
    - LivestreamsReportParameters: Parameters for an `analytics_livestreams_report` run. Exactly one of `all_matching` and `specific_shows` selects the shows.
      - `report_type` 'analytics_livestreams_report', required: The type of report these parameters describe.
      - `all_matching` MatchingShowsFilter: Which of the seller's shows an `all_matching` report covers.
        - `title` string, nullable: Include only shows whose title matches this text.
        - `start_time` ShowStartTimeRange
          - `start` string, date-time, required: Include only shows that started at or after this time.
          - `end` string, date-time, nullable: Include only shows that started at or before this time. Defaults to the end of the current hour.
      - `specific_shows` SpecificShows
        - `show_ids` string[], required: The shows to report on, in the order their rows appear. Every show must be hosted by the seller.
  - `report_url` string, nullable, required: URL of the generated report file. Null until the run is `completed`. See [Reports and Statements](/reports) for each report type's CSV columns.
  - `created_at` string, date-time, required: When the run was requested.
  - `updated_at` string, date-time, required: When the run was last updated.

## Other responses

- `422`: The report parameters are not valid.

---

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