Reports 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 User

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
Replace "YOUR_API_KEY" with your actual API key as explained at Get 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.

📘
API concurrency
For a single report, you can have up to three concurrent requests using the same API key. You cannot cancel a request while it is in progress.

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 timeRange query 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.

Reports API

📘
Required Permissions

Endpoints

Schema

Common properties

Result object

Config object

Examples

📘
YOUR_API_KEY

List all reports

Get report results

📘
API concurrency

🚧
Experimental feature

📘Required Permissions

Endpoints

Schema

Common properties

Result object

Config object

Examples

📘YOUR_API_KEY

List all reports

Get report results

📘API concurrency

🚧Experimental feature

📘
Required Permissions

📘
YOUR_API_KEY

📘
API concurrency

🚧
Experimental feature