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 startTime and endTime are 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, reports is an empty object ({}) — the call still returns 200 OK and produces the summary file.

---

Scenario

A tenant admin wants a weekly active-device-count snapshot, then downloads the results as JSON:

---

Constraints

• repeatPeriod must be Daily, Weekly, or Monthly
• name, repeatPeriod, endTime, timeZone, and jobs are all required
• endTime uses YYYY-MM-DD and must extend beyond the job's next scheduled execution
• jobs must include at least one valid metric key
• Download requires both startTime and endTime; 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.

---

Last updated on Jul-17, 2026 | Version 1.1.0