Managing reports

All operations with the reports in the cloud platform are located under the /reports endpoint.

Reports allow you to have detailed statistics of the usage of your services.

The reports use binary gigabytes (GB), which are 1024^3 bytes, or gibibytes (GiB) as measurement units for storage space.

Important

The platform enforces the following rules for the report period:

Report period must not be in future.
If the tenant was renamed, the report will contain the latest name of the tenant within the provided period.

Report object structure

Name	Value type	Description
`recipients`	array of UUID strings	An array of UUIDs of the user accounts which should receive the report by email. Must be used only when `result_action` is set to `send`.
`parameters`	report parameters object	An object of report parameters which allow to configure the report.
`schedule`	report schedule object	An object that allows to configure scheduling of the report.
`generation_date`	string	ISO 8061 date when the report should be generated (only one-time reports).
`result_action`	string	Action to be done with the report. Refer to report result actions for the list of available report result actions.

Report parameters object structure

Name	Value type	Description
`tenant_id`	UUID string	The UUID of the tenant that will be the subject of this report
`level`	string	Level of report detail. Refer to report levels for the list of available report levels.
`kind`	string	Kind of report. Refer to report kinds for the list of available report kinds.
`formats`	array of strings	Report formats. Refer to report formats for the list of available report formats.
`period`	report period parameter object	An object that allows to set desired period of the report.
`hide_zero_usage`	boolean	Hide metrics with zero usage in report.
`show_skus`	boolean	Show SKU-related fields in report.

Report period parameter object structure

Name	Value type	Description
`start`	string	ISO 8061 date when the report starts.
`end`	string	ISO 8061 date when the report ends.

Report schedule object structure

Name	Value type	Description
`enabled`	boolean	Flag indicating whether the report is enabled (scheduled reports only).
`type`	string	Type of report schedule. Refer to report scheduling types for the list of available report types.

Example report

{
    "recipients": [
        "ca451758-b48a-45d9-9ae6-8f1059f67619",
        "ab00e527-219b-481b-b01b-311b5be0ed3c"
    ],
    "parameters": {
        "kind": "usage_summary",
        "tenant_id": "2a91a14d-ffd3-4ac1-9b4d-3990162c5acc",
        "level": "accounts",
        "period": {
            "start": "2017-05-01",
            "end": "2017-05-07"
        },
        "formats": [
            "csv",
            "json_v1",
            "csv_v2_0",
            "json_v2_0"
        ]
    },
    "schedule": {
        "type": "once"
    },
    "generation_date": "2017-05-08",
    "result_action": "send"
}

Stored report object structure

Name	Value type	Description
`id`	UUID string	The UUID of the stored report.
`created_at`	string	ISO 8061 date when the stored report was generated.
`size`	number	Size of the compressed stored report in bytes.
`status`	string	Report generation status.
`report_format`	string	Stored report data format. Refer to report formats for the list of available report formats.

Example stored report

{
    "id": "af5946c3-7e5b-4480-8835-518efe1c3522",
    "created_at": "2019-08-08T07:36:57+00:00",
    "size": 3605,
    "status": "saved",
    "report_format": "csv"
}

Report levels

Value	Description
`direct_partners`	The report will include direct customers and partners.
`all_partners`	The report will include all partners.
`all_customers`	The report will include all customers and partners.
`accounts`	The report will include all customers and partners (including user account details).

Report kinds

Value	Description
`usage_daily`	A kind of report that will contain the service usage metrics for each day of the specified period.
`usage_summary`	A kind of report that will contain the service usage metrics for the end of the specified period, and the difference between the metrics in the beginning and at the end of the specified period.
`usage_current`	A kind of report that will contain the current service usage metrics for the previous day. The usage metrics are calculated within each of the child tenants’ billing periods. If the tenants included in the report have different billing periods, the parent tenant’s usage may differ from the sum of the child tenants’ usages.
`usage_breakdown`	A kind of report that will contain the service usage metrics and their changes for each day of the specified period.

Report formats

Value	Description
`csv`	The report will be generated in table-formatted CSV format.
`html`	The report will be generated in HTML format.
`json_v1`	The report will be generated in API v1 compatible JSON format.
`csv_v2_0`	The report will be generated in CSV format.
`json_v2_0`	The report will be generated in API v2 compatible JSON format.

Report scheduling types

Value	Description
`once`	The report will be generated only once on `generation_date`.
`monthly`	The report will be generated at 23:59:59 by UTC time on the first day of a month and sent on the second day of that month to administrators of your tenant who have the `reports` attribute in notifications.

Report result actions

Value	Description
`save`	The report will be saved on the server when generated and it will be possible to download it.
`send`	The report will be sent by email when generated.

What you can do with usage reports

Operation	Methods and endpoints used
Create a new usage report	`POST /reports`
Fetch a usage report	`GET /reports/{report_id}`
Fetch a usage report from tenant reports	`GET /reports/{report_id}` `GET /tenants/{tenant_id}/reports`
Update a usage report	`PUT /reports/{report_id}`
Disable scheduled usage report	`PUT /reports/{report_id}`
Delete a usage report	`DELETE /reports/{report_id}`
Fetch a stored usage report	`GET /reports/{report_id}/stored` `GET /reports/{report_id}/stored/{stored_report_id}`
Fetch a service usage using a stored report	`GET /reports/{report_id}/stored/{stored_report_id}`
Create a billing report	`POST /reports` `GET /reports/{report_id}/stored` `GET /reports/{report_id}/stored/{stored_report_id}`