Scheduled Reports

Use the ws/v1/reports/schedules API to schedule recurring reports and have them emailed to recipients as Excel files.

You can schedule reports to run daily, weekly, or monthly. Weekly run at a specific day of the week while monthly reports run on a specific day of the month. The reports run at a time of your choosing.

Use the v1/reports API to get a list of all available reports or a specific status report.

URI

http://<hostname>/ws/v1/reports/schedules

Formats

Method Formats Description Parameters
GET /ws/v1/reports/schedules/inventory Get a list of detailed schedule information for devices. cursor, orderby, query, size
POST /ws/v1/reports/schedules/inventory Create a new scheduled report.
PUT /ws/v1/reports/schedules/inventory/{id} Update the properties of a single scheduled report.
GET /ws/v1/reports/schedules/inventory/{id} Retrieve a single scheduled report.
DELETE /ws/v1/reports/schedules/inventory/{id} Delete a single scheduled report.
POST /ws/v1/reports/schedules/run/{id} Immediately run a single scheduled report. Returns the generated Excel report to the API caller but does not send email for the report. The response type of this API is “application/vnd.openxmlformats-officedocument.spreadsheetml.sheet”

Parameters

Name Type Description
cursor string Specify the cursor (returned in the last page of results) to resume paging through results.
orderby string Specify the field to order by, optionally followed by asc or desc for ascending or descending sort.
query string Specify the device query to summarize. The query language is similar to SQL Query sntax:SQL-like conditions using AND, OR, and parenthesis to group expressionsVarious condition operators on numeric and text valuesSingle quoted text literals: ‘TheText’Text escape for quote character is the quote: ‘isn’’t difficult’Numeric literals support 0x prefix for hexEnumerated values (like connection_status) are treated as textCase insensitive comparisonsTimestamp field conditions are not supported.
size integer Specify the size of the page to return.

Payload fields

The fields that define a scheduled report follow. Fields marked with output only cannot be specified in a create or update operation.

Name Type Description
account_filter string For an account with subaccounts, use account filter to select customer IDs for the target data in the report
at_time localtime Time of day of the form: 14:45[:00]. A 24 hour time of day in the timezone specified. If timezone is not specified, the system selects a timezone.
customer_id integer The account that owns the scheduled report (output only)
description string An optional description for the scheduled report
enabled boolean Is the scheduled report enabled, that is, will it run automatically
end_time timestamp The end time of the data in the report. Specify the end time (exclusive) in ISO 8601 or epoch (long) or relative time (matching the form -N[dhms] where d is days, h is hours, m is minutes, s is seconds, and -1d means one day prior to the report run time).
frequency string One of daily, weekly, monthly, the report runs once per interval
groupby groupby The summarization type used by the report. See the Payload Values section
id integer The identifier of the scheduled report (output only)
last_run timestamp The time (if any) that the scheduled report ran last (output only)
mail_body string The body of the email.
mail_subject string The subject of the email.
mail_to string A comma separated list of valid email addresses to send the report to.
name string A unique name for the scheduled report
on_day integer The day of the interval that the report runs on. See the Payload Values section
query string The API query as supported by the matching report type. For example a cellular_utilization report can only use query fields supported by the /ws/v1/reports/cellular_utilization API
start_time timestamp The start time of the data in the report. Specify the start time (inclusive) in ISO 8601 or epoch (long) or relative time (matching the form -N[dhms] where d is days, h is hours, m is minutes, s is seconds, and -1d means one day prior to the report run time).
timezone string The timezone to be used to calculate the time of day. If the timezone is not specified, the system selects a timezone. See the Payload Values section
type string One of cellular_utilization, device_availability, intelliflow

Payload Values

These fields support unique or special values.

  • account_filter - The account filter describes the list of accounts owning the target data for the report. If left off, only the owning account data is queried. An account filter is a string of the form “all”, customer ID as a string, or a comma separated list of customer IDs that the report owner is authorized to.
  • groupby - Certain report types can further summarize data by grouping it.
    • For any report, you can, leave this field off or specify none and the report selects the default grouping.
    • A device_availability report does not support other grouping values
    • A cellular_utilization report supports carrier, modem, sim, device_type, firmware_version, or group.
    • An intelliflow report supports port, port_name, service_type, server_address, server_domain, or host_address.
  • mail_subject and mail_body - When entering text for the email subject or body, you can use the special values {name} or {description} in the text. These values are replaced with the report name or description fields when the report is emailed.
  • on_day - Use the on_day field to indicate the day of the week or the day of the month that a report runs on.
    • The default value if unspecified is 1
    • Leave this value off or specify 1 for a daily report
    • For a weekly report, specify values 1 to 7, day 1 is Sunday.
    • For a monthly report, specify values 1 to 28 or a value of -1 to indicate the last day of the month.
  • timezone - Specify a timezone using a region based timezone syntax, like America/Chicago or an offset value like +00:00. Some special timezones are supported like UTC or GMT and a value like GMT+05:00 is also supported.

Query fields

See v1 API Query Language for detailed information on building API queries.

All of the fields described in the Payload section are supported by the query language, except for at_time.