Skip to content

Create Report

Request

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

Security
reports_bearerAuth
Bodyapplication/jsonrequired
report_typestringrequired
Enum:"device_apps""device"
Example:"device_apps"
start_timestring, (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.

Example:"2024-08-28T00:00:00Z"
end_timestring, (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.

Example:"2024-08-28T00:00:00Z"
is_downloadboolean
filters(reports_DeviceAppsFilter (object or null)) or (reports_DeviceFilter (object or null))
One of:
cURL
curl -i -X POST \
  https://api.esper.io/_mock/openapi/report/v0/reports \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "report_type": "device_apps",
    "start_time": "2024-08-28T00:00:00Z",
    "end_time": "2024-08-28T00:00:00Z",
    "is_download": true,
    "filters": {
      "date": "2024-08-28",
      "package_name": [
        "com.android.chrome"
      ],
      "app_state": [
        "SHOW"
      ],
      "device_os": [
        "Android"
      ],
      "platform": [
        "Android"
      ]
    }
  }'

Responses

Create Report

Bodyapplication/json
contentobject
Response
{
  "content": {
    "id": "string",
    "status": "PENDING"
  }
}