Reports API
Programmatically obtain cost, usage and savings information for your cloud infrastructure with easy-to-use RESTful API.
DoiT Cloud Analytics Reports give you instant visibility into your cloud cost. With Cloud Analytics Reports, you can slice and dice your cloud spend and identify cost & performance optimization opportunities for your organization.
Required Permissions
- Cloud Analytics (part of Standard User built-in role)
- Depending on the features you want to use, you may need extra permissions, for example, Attributions Manager. See Roles and permissions.
Endpoints
- GET /analytics/v1/reports: Lists all reports.
- GET /analytics/v1/reports/{id}: Returns the results of a report.
- GET /analytics/v1/reports/{id}/config: Returns the configuration of a report.
- POST /analytics/v1/reports: Creates a report.
- POST /analytics/v1/reports/query: Runs a query on the fly.
- PATCH /analytics/v1/reports/{id}: Updates a report.
- DELETE /analytics/v1/reports/{id}: Deletes a report.
Schema
Common properties
Below are the common properties you'll find in response bodies of GET /analytics/v1/reports and GET /analytics/v1/reports/{id}.
| Property | Type | Description |
|---|---|---|
| id | string | Report ID. See Resource IDs. |
| reportName | string | Report name. |
| owner | string | The owner of the report. |
| type | string | Report type. Possible values: preset, custom, managed |
| createTime | int64 | The time when the report was created, epoch time in milliseconds. |
| updateTime | int64 | The time when the report was last modified, epoch time in milliseconds. |
| urlUI | string | The URL of the report in the DoiT console. |
Result object
The result object contains the results of a report run. It's returned in the response bodies of GET /analytics/v1/reports/{id} and POST /analytics/v1/reports/query.
| Property | Type | Description |
|---|---|---|
| schema | [object] | JSON object representing the rows values: - name- type |
| mlFeatures | [string] | The list of Advanced analysis features enabled on the report: - increasing: Trending up- decreasing: Trending down- none: Not trending- forecast: Forecast |
| rows | [[query_result_object]] | Rows of report results. |
| forecastRows | [[forecast_result_object]] | Rows of forecast results. |
Config object
The config object contains a report's configuration. Its attributes correspond to the Report settings in the DoiT console.
| Property | Type | Description |
|---|---|---|
| metric | object | The metric to apply to the report. See Report settings: Metric. Attributes: - type: metric type. Possible values: basic, custom, extended- value: metric name. For example, basic metrics are cost, usage, and savings. |
| metricFilter | object | To limit the report results by metric values. See Limit by value. Attributes: - metric- operator- values |
| aggregation | string | The aggregation option of the data. See Aggregation. |
| advancedAnalysis | object | The Advanced analysis features and whether they are enabled: forecast, notTrending, trendingUp, trendingDown |
| timeInterval | string | See Time interval. For example, hour, day, week, month, quarter, year. |
| dimensions | [dimension_object] | To define the columns that appear in the tabular formats. See Dimensions. Dimension object attributes: - id: Dimension ID.- type: Dimension type.You can use the Dimensions API to check dimension IDs and types. |
| timeRange | object | Specify a predefined or custom time range for the report. See Time range. |
| includePromotionalCredits | boolean | See Promotional credits. |
| includeSubtotals | boolean | See Include subtotals. |
| filters | [filter_object] | To filter the results of a report. See Filter results. Filter object attributes: - id: Dimension ID.- type: Dimension type.- inverse(boolean): Set to true to exclude the specified values.- value[string]: Values to filter on.Note: To use an attribution as a filter, both the type and the ID must be attribution, and the value array must contain the attribution IDs. |
| group | [group_by_object] | To define the rows that appear in the tabular formats. See Group by. Group-by object attributes: - id: Dimension ID.- type: Dimension type.- limit(object): To limit the number of results based on ranking. See Limit by top/bottom.- metric(object): Metric type and name.- sort: Sort option. Possible values: asc, desc, a_to_z.- value: The number of items to show. |
| layout | string | The visualization option of the report. See View as. |
| displayValues | string | See View data as (Comparative report). |
| currency | string | The currency in which the billing data is reported. See Currency. |
| sortGroups | string | The sort option for groups. See Sort groups. Possible values: - asc: Row total ascending.- desc: Row total descending.- a_to_z: Alphabetical sort by group name. |
| sortDimensions | string | The sort option for dimensions. See Sort dimensions. Possible values: - asc: Column total ascending.- desc: Column total descending.- a_to_z: Alphabetical sort by column title. |
| dataSource | string | Data source of the report. See Data source. Possible values: - billing: Use cloud billing data as the data source.- billing_datahub: Use the combined dataset of cloud billing data and data imported via DoiT DataHub.- bqlens: Use the BigQuery Lens audit log sink as the data source. See BigQuery Lens as data source. |
| splits | object | To split costs using attribution groups. See Split costs. Attributes: - id: Dimension ID.- type: Dimension type. Must be attribution_group.- includeOrigin(boolean)- mode: Cost distribution method. Possible values: even, custom, proportional.- origin(object)- targets ([target_object]) |
| customTimeRange | object | Attributes: - from: The start timestamp of the time range in RFC3339 format.- to: The end timestamp of the time range in RFC3339 format. |
Examples
your-api-key
Always replace "your-api-key" with your actual API key as explained at Getting Started.
List all reports
The List reports method lists all reports accessible by your user account according to the report's access control list (ACL) as described at Share Cloud Analytics Reports.
You can filter the results using the following query parameters.
| Parameter | Type | Description |
|---|---|---|
minCreationTime | string | Min value for a report's creation time, in milliseconds since the POSIX epoch. If set, only reports created after or at this timestamp are returned. |
maxCreationTime | string | Max value for a report's creation time, in milliseconds since the POSIX epoch. If set, only reports created before or at this timestamp are returned. |
filter | string | An expression to filter the results of the request. The syntax is key:[<value>]. For example, using type:custom will return only custom reports. Learn more about filters.Supported filter keys: - type: Report type. Possible values: custom, preset- owner: Owner of the report. Example: [email protected]- reportName: Report name.- updateTime: The time when the report was last modified, epoch time in milliseconds. |
Sample request:
curl --location \
--request GET 'https://api.doit.com/analytics/v1/reports?maxResults=5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-api-key' \
--data-raw ''
Sample response body:
{
"pageToken": "djVmZnFPZDc0czkxNVBySzI4OVc",
"rowCount": 5,
"reports": [
{
"id": "rrVOklaQxh74xh2gPEzQ",
"reportName": "EC2 Instance Amortised Cost by Coverage Type",
"owner": "doit.com",
"type": "preset",
"createTime": 1712326184470,
"updateTime": 1712327214694,
"urlUI": "https://console.doit.com/customers/{CUSTOMER_ID}/analytics/reports/rrVOklaQxh74xh2gPEzQ"
},
{
"id": "mTJwWWgI6PMC13pP0p3t",
"reportName": "GCS Uploads by Bucket",
"owner": "doit.com",
"type": "preset",
"createTime": 1709553127060,
"updateTime": 1709553145612,
"urlUI": "https://console.doit.com/customers/{CUSTOMER_ID}/analytics/reports/mTJwWWgI6PMC13pP0p3t"
},
{
"id": "m0QjqmjOC9f6f0LPX4GA",
"reportName": "GCS by Cost Type",
"owner": "doit.com",
"type": "preset",
"createTime": 1709504558240,
"updateTime": 1709504919076,
"urlUI": "https://console.doit.com/customers/{CUSTOMER_ID}/analytics/reports/m0QjqmjOC9f6f0LPX4GA"
},
{
"id": "KyPf3v17CueP6xlZ2vJK",
"reportName": "GCS Cost by Bucket",
"owner": "doit.com",
"type": "preset",
"createTime": 1709503968466,
"updateTime": 1709504904672,
"urlUI": "https://console.doit.com/customers/{CUSTOMER_ID}/analytics/reports/KyPf3v17CueP6xlZ2vJK"
},
{
"id": "XjK5I6Eql5dNFgPw4Qh3",
"reportName": "EKS Interactive Cost Explorer by Clusters and Pod owner",
"owner": "doit.com",
"type": "preset",
"createTime": 1707210125547,
"updateTime": 1708617155142,
"urlUI": "https://console.doit.com/customers/{CUSTOMER_ID}/analytics/reports/XjK5I6Eql5dNFgPw4Qh3"
}
]
}
Get report results
The Get report results method returns the results of a Cloud Analytics Report.
Sample request:
curl --request GET \
--url 'https://api.doit.com/analytics/v1/reports/ViSpueEq1iXNMcL1n6Un' \
--header 'Authorization: Bearer your-api-key' \
--header 'accept: application/json'
Sample response body:
{
"id": "ViSpueEq1iXNMcL1n6Un",
"reportName": "Historical Cloud Native Costs by Platform",
"owner": "doit.com",
"type": "preset",
"createTime": 1609229892750,
"updateTime": 1712448000355,
"urlUI": "https://console.doit.com/customers/EE8CtpzYiKp0dVAESVrB/analytics/reports/ViSpueEq1iXNMcL1n6Un",
"result": {
"schema": [
{
"name": "cloud_provider",
"type": "string"
},
{
"name": "year",
"type": "string"
},
{
"name": "month",
"type": "string"
},
{
"name": "cost",
"type": "float"
},
{
"name": "timestamp",
"type": "timestamp"
}
],
"mlFeatures": [
"forecast"
],
"rows": [
[
"amazon-web-services",
"2023",
"10",
330941.7693793848,
1696118400
],
[
"amazon-web-services",
"2023",
"11",
305171.4947461792,
1698796800
],
[
"amazon-web-services",
"2023",
"12",
312004.42597404466,
1701388800
],
[
"amazon-web-services",
"2024",
"01",
313523.0173567938,
1704067200
],
[
"amazon-web-services",
"2024",
"02",
299471.6298391634,
1706745600
],
[
"amazon-web-services",
"2024",
"03",
104042.84870879125,
1709251200
],
[
"amazon-web-services",
"2024",
"04",
91039.54142940845,
1711929600
],
[
"amazon-web-services",
"2024",
"05",
72912.15826542026,
1714521600
],
[
"amazon-web-services",
"2024",
"06",
44885.68562664757,
1717200000
],
[
"amazon-web-services",
"2024",
"07",
331956.2241485975,
1719792000
],
[
"amazon-web-services",
"2024",
"08",
268081.4014359781,
1722470400
],
[
"amazon-web-services",
"2024",
"09",
9430.640448551749,
1725148800
],
[
"google-cloud",
"2023",
"10",
156741.32602723103,
1696118400
],
(omitted...)
[
"google-cloud",
"2024",
"09",
22354.92029756825,
1725148800
]
],
"forecastRows": [
[
"Forecast",
"2023",
"10",
null,
1696118400
],
[
"Forecast",
"2023",
"11",
null,
1698796800
],
(omitted...)
[
"Forecast",
"2025",
"07",
296300.8125,
1751328000
]
]
}
}
Experimental feature
You can pass an optional
timeRangequery parameter to override the time range of the report. You can either specify a period or startDate/endDate pair.Examples:
- https://api.doit.com/analytics/v1/reports/{id}?timeRange=P20D
- https://api.doit.com/analytics/v1/reports/{id}?startDate=2022-08-15&endDate=2022-09-03
To specify a period, use P[n]Y[n]M[n]D notation, where Y is the year(s), M is the month(s), and D is the day(s). For example, P28D means the last 28 days, and P1Y means the last year.
Updated about 1 month ago