Reports
Overview
The Reports module lets you schedule recurring collection of Tenant-level usage metrics and download the results as summary reports.
Report configurations and usage metrics are not scoped to an individual Org. A Usage Job periodically collects platform usage metrics — such as active device count and data point count — and you download the generated data as a summary report for a chosen date range.
Usage Jobs
A Usage Job is a scheduled task that periodically collects Tenant usage metrics until a defined end date.
Metrics
| Metric key | Description |
|---|---|
ActiveDeviceCount | Count of devices that have not been deleted, across the Tenant or the specified Orgs — this includes Deactivated devices; it does not reflect actual online/connected status |
DataPointCount | Volume of telemetry data points collected during the job's period, measured from the previous scheduled trigger to the start of the current one |
Operations
| Operation | API | Description |
|---|---|---|
| Create Usage Job | POST /api/v1/reports/usage-jobs | Define a new usage job |
| List Usage Jobs | GET /api/v1/reports/usage-jobs | List usage jobs (paginated) |
| Get Usage Job | GET /api/v1/reports/usage-jobs/{usageJobId} | Get one job by ID |
| Update Usage Job | PUT /api/v1/reports/usage-jobs/{usageJobId} | Replace the job configuration |
| Delete Usage Job | DELETE /api/v1/reports/usage-jobs/{usageJobId} | Remove the job |
| Download Summary | GET /api/v1/reports/usage-jobs/{usageJobId}/summaries | Download usage summary data for a date range |
Create Usage Job
POST /api/v1/reports/usage-jobs
See Create Usage Job for full field reference. All of the following fields are required:
| Field | Description |
|---|---|
name | A label for the usage job |
repeatPeriod | Collection period: Daily, Weekly, or Monthly |
endTime | Date (YYYY-MM-DD) after which collection stops |
timeZone | UTC offset (e.g. +08:30) |
jobs | One or more metric keys (ActiveDeviceCount, DataPointCount) |
Each job runs on its repeatPeriod at a system-defined schedule boundary and generates usage
metrics until endTime. The endTime must extend beyond the job's next scheduled execution — for
example, a Monthly job's end date must allow at least one more monthly run.
Response 201 Created
Update Usage Job
PUT /api/v1/reports/usage-jobs/{usageJobId} replaces a usage job's configuration. name,
endTime, timeZone, and jobs are required; repeatPeriod is optional on update.
Download Summary
GET /api/v1/reports/usage-jobs/{usageJobId}/summaries
See Download Summary for full field reference. Downloads usage summary data for the requested date range.
startTimeandendTimeare both required, inyyyy-MM-ddformat (for example2025-07-01)formatcurrently accepts onlyjson- The report covers the specified period only
- On success the response is a downloadable file named
summary-report-{usageJobId}.json - Downloading does not modify or delete the Usage Job
The API does not publish a schema for the downloaded file, so its exact structure is not documented here. Run the request once against your own job to see the shape before you build against it.
Scenario
A tenant admin wants a weekly active-device-count snapshot, then downloads the results as JSON:
Constraints
repeatPeriodmust beDaily,Weekly, orMonthlyname,repeatPeriod,endTime,timeZone, andjobsare all requiredendTimeusesYYYY-MM-DDand must extend beyond the job's next scheduled executionjobsmust include at least one valid metric key- Download requires both
startTimeandendTime; JSON is the only supported format - Deleting a Usage Job permanently removes its schedule and stops future collection; once deleted, its summaries can no longer be downloaded
Related
- Device counts reflect devices registered under: Device Management
DataPointCount is a Tenant usage metric. It does not provide report generation for individual
DataStreams — see DataStreams for querying telemetry values.