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

POST /reports
GET /reports/{report_id}
GET /reports/{report_id}
GET /tenants/{tenant_id}/reports
PUT /reports/{report_id}
PUT /reports/{report_id}
DELETE /reports/{report_id}
GET /reports/{report_id}/stored
GET /reports/{report_id}/stored/{stored_report_id}
GET /reports/{report_id}/stored/{stored_report_id}
POST /reports
GET /reports/{report_id}/stored
GET /reports/{report_id}/stored/{stored_report_id}