Create Report

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

{
  "report_type": "device_apps",
  "start_time": "2024-08-28T00:00:00Z",
  "end_time": "2024-08-28T00:00:00Z",
  "filters": {
    "date": "2024-08-28",
    "package_name": [
      "com.android.chrome"
    ],
    "app_state": [
      "SHOW"
    ],
    "device_os": [
      "Android"
    ],
    "platform": [
      "Android"
    ]
  }
}