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.

Operations

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	DoiT Clo	An array of JSON objects that define the structure of each row in the report results: `name`: the name of a field (column) `type`: the data type of the field
mlFeatures	DoiT Clo	The list of Advanced analysis features enabled on the report: `increasing`: Trending up `decreasing`: Trending down `none`: Not trending `forecast`: Forecast
rows	[iT Cloud Analytics Re]	An array of report result rows. Each row is an array of values as defined by the `schema` object.
forecastRows	[iT Cloud Analytics Repor]	An array of report 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	DoiT Cloud Analyti	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	DoiT Cloud Anal	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`atures y: 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	DoiT Cloud Analyt	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` (oles and permis)
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.

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.