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. Provide the full
set of fields when updating, the same as when creating the job.
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. Both startTime and endTime are
required (YYYY-MM-DD), and JSON is currently the only supported format.
The response groups collected values by metric, keyed by timestamp:
{
"usageJobId": "...",
"name": "...",
"startTime": "20250701",
"endTime": "20250731",
"reports": {
"ActiveDeviceCount": { "<timestamp>": 10 },
"DataPointCount": { "<timestamp>": 1200 }
}
}
- Both
startTimeandendTimeare inclusive. - Dates with no collected data are omitted from the result rather than returned as
0. - If the job has no data at all for the requested range,
reportsis an empty object ({}) — the call still returns200 OKand produces the summary file.
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
- In the current release, a Usage Job is visible only to the user who created it — list, get, update, delete, and download all require the original creator's session
Related
- Device counts reflect devices registered under: Device Management
DataPointCount is a Tenant usage metric. It does not provide report generation for individual
Data Objects — see Data Objects for querying telemetry values.