---
title: "Create Report"
method: POST
path: "/report/v0/reports"
tags: ["reports_Reports API"]
---

# Create Report

`POST /report/v0/reports`

Initiate generation of a device or device apps report and receive a report ID for status polling. Report availibity varies by operating system.

Returns a report_id and an initial status of PENDING; poll GET /report/v0/reports/{report_id} to track progress and retrieve results once the status reaches SUCCEEDED.

**About Create Report**

Report generation in Esper is asynchronous. Submitting this request triggers a backend job that ingests and consolidates fleet data — a process that can take several minutes. The is_download flag controls the output mode: set it to false to retrieve an in-memory preview (up to 10,000 rows) or true to generate a full dataset available via a signed download link. Supported report types are device_apps (Android and iOS/iPadOS/tvOS) and device (Android, iOS, Linux, Windows). Note that app reports exclude sideloaded, preloaded, and SDK-installed apps.

**Key Fields / Request Body**

report_type (required) — device_apps for the Device Apps Report or device for the Device Report

start_time — Report window start in UTC (e.g., 2024-08-28T00:00:00Z); must be after July 1, 2024 for device_apps

end_time — Must equal start_time (single-day reports only)

is_download — true to generate a full downloadable CSV; false for an in-console preview (first 10,000 rows)

filters.date — Optional date override in YYYY-MM-DD format; takes precedence over start_time/end_time if provided

filters.package_name — (device_apps only) Array of package names to filter by; omit for all packages

filters.app_state — (device_apps only) Filter by app visibility: SHOW, HIDE, DISABLE, or LAUNCHABLE_BUT_HIDDEN

filters.platform — Filter by platform: Android, Apple, Linux, Windows (platform availability varies by report type)

**Common Use Cases**

Generating a point-in-time snapshot of all app versions across an Android or iOS fleet

Producing a full CSV export of device state, OS version, location, and provisioning data for all managed platforms

Filtering a device apps report to a specific package name to audit version consistency across devices

**Best Practices**

Set end_time equal to start_time; the API supports single-day reports only

Use filters.date as a simpler alternative to start_time/end_time when generating a same-day report

Set is_download: true when your fleet exceeds 10,000 devices or apps, since the preview response is capped at 10,000 rows

Poll GET /report/v0/reports/{report_id} at a reasonable interval (e.g., every 10–30 seconds) rather than immediately, as report generation can take several minutes

**Workflow**

Call GET /report/v0/report-types to confirm the report_type value and check data availability

POST to /report/v0/reports with the desired report_type, date range, is_download flag, and any filters

Store the returned report_id and poll GET /report/v0/reports/{report_id} until status is SUCCEEDED or FAILED

## Request body

- ReportsReport
  - `report_type` 'device_apps' | 'device', required
  - `start_time` string, date-time — Start time of the report in UTC format. Example: "2024-08-28T00:00:00Z". Must be a date and time later than July 1st, 2024.
  - `end_time` string, date-time — End time of the report in UTC format. Example: "2024-08-29T00:00:00Z". Must be a date and time later than July 1st, 2024 and equal to the start_time.
  - `is_download` boolean
  - `filters` union
    - object
      - `date` string, date, nullable — Date of report. If provided, this value will override start_time and end_time values. Example: "2024-08-28". Must be a date later than July 1st, 2024.
      - `package_name` string[], nullable
      - `app_state` string[], nullable
      - `device_os` string[], nullable
      - `platform` string[], nullable
    - object
      - `date` string, date, nullable — Date of report. If provided, this value will override start_time and end_time values. Example: "2025-03-17". Must be a date later than May 17th, 2025.
      - `platform` string[], nullable

## Response `200`

Create Report

- ReportsCreateReportResponse
  - `content` object
    - `id` string
    - `status` 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' | 'CLOSED'

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `500` — Internal server error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)