Reports API

DoiT Cloud Analytics Reports give you instant visibility into your cloud costs, helping you slice and dice your cloud spend and identify opportunities to optimize cost and performance.

Cloud Analytics supports both synchronous and asynchronous report runs.

📘
Required Permissions

Cloud Analytics User

Depending on the features you want to use, you may need extra permissions. See Roles and permissions.

Operations

GET /analytics/v1/reports: Lists all reports.
GET /analytics/v1/reports/{id}/config: Returns the configuration of a report.
POST /analytics/v1/reports: Creates a report.
PATCH /analytics/v1/reports/{id}: Updates a report.
DELETE /analytics/v1/reports/{id}: Deletes a report.

Synchronous report run

GET /analytics/v1/reports/{id}: Runs a saved report.
POST /analytics/v1/reports/query: Runs an inline report configuration.

Asynchronous report run

POST /analytics/v1/reports/{id}/actions/run: Runs a saved report asynchronously.
POST /analytics/v1/reports/actions/run: Runs an inline report configuration asynchronously.
GET /analytics/v1/reports/operations/{operationId}: Returns the status of an async report run operation.
GET /analytics/v1/reports/operations/{operationId}/results: Returns the result of a successful async report run operation.
POST /analytics/v1/reports/operations/{operationId}/actions/cancel: Cancels an async report run operation.

Choose synchronous or asynchronous

Asynchronous runs are available to the same callers as the rest of the Reports API, including service accounts with the Cloud Analytics User permission.

Use asynchronous execution when a report is large or long-running.

Item	Synchronous	Asynchronous
Result	In the HTTP response	Separate results call after the operation succeeds
Maximum rows (entries in `result.rows`)	500,000	5,000,000
Maximum group combinations (distinct combinations of the fields in `config.group` (Group by))	200,000	2,000,000
How long the query can run	2-minute execution limit. If a report run exceeds 120 seconds, the query is aborted.	No 2-minute execution limit.
Cancel a request while it is in progress	❌ (For a single report, you can have up to three concurrent requests using the same API key).	✔️ (Cancel an async report run)
How long the result stays available	Only for that HTTP response	7 days

Run a report asynchronously

To run a report asynchronously, you submit the run, receive an operation ID, poll until it finishes, and then download the result.

Only the user or service account that started the operation can poll it, cancel it, or read its result. Any other caller receives 404.

flowchart TD
    A["POST /analytics/v1/reports/{id}/actions/run"]
    B["GET /analytics/v1/reports/operations/{operationId}"]
    C["GET /analytics/v1/reports/operations/{operationId}/results"]

    A -->|"202 Accepted<br/>Location: /analytics/v1/reports/operations/{operationId}"| B
    B -->|"pending → running → succeeded"| C
    C --> D["200 OK + result"]

Start the run

Saved report: POST /analytics/v1/reports/{id}/actions/run
Inline report configuration: POST /analytics/v1/reports/actions/run

Every start and cancel call requires an Idempotency-Key header. Use a new unique value for each submission, such as a UUID. Use ?dryRun=true to validate without creating an operation.

Keep the key if you need to recover the operation: repeating the same key and the same request within 24 hours returns the original 202 response.

Poll the operation

GET /analytics/v1/reports/operations/{operationId}

This endpoint does not return result data. pending and running responses include Retry-After, a number of seconds to wait before the next poll.

Polling counts toward the account rate limit of 1,000 requests per minute. Follow Retry-After so a long report stays under that limit.

Get the result

GET /analytics/v1/reports/operations/{operationId}/results

A run started from a saved report returns the same report fields as Get report results. reportName, owner, and updateTime are read when you fetch the result, so they reflect the report as it is then.

A run started from an inline configuration returns result only.

cacheHit is true when this result was served from a recent identical run. An identical configuration for the same customer, run again within 6 hours, can come back already succeeded with cacheHit: true. That result is the earlier execution. Its expireBy is the earlier of 7 days from the new operation, and the expiry of the stored result it reuses.

If the result is still larger than the asynchronous limits, the operation finishes as failed with one of these codes:

error.code	Limit exceeded
`result_too_large`	More than 5,000,000 rows
`series_count_too_large`	More than 2,000,000 distinct Group by combinations
`query_timeout`	The query did not finish within 6 hours

Narrow the report before retrying: shorten timeRange, raise timeInterval (for example, from day to month), add filters, or set a top/bottom limit on group.

Optional file download

After a run has succeeded, add fileOutput=pdf or fileOutput=png to the results request.

The JSON result is still returned, and fileOutput is a signed URL for a rendered file.

The URL is valid for 7 days. Request the results endpoint again for a fresh URL. The file is rendered from the stored result, so this does not run the query again.

Cancel a run

POST /analytics/v1/reports/operations/{operationId}/actions/cancel

Cancel returns 200 and status canceled for a pending or running operation. Calling it again on an operation that is already succeeded, failed, or canceled returns that terminal status unchanged.

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	array of objects	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	array of strings	The list of Advanced analysis features enabled on the report: `increasing`: Trending up `decreasing`: Trending down `none`: Not trending `forecast`: Forecast
rows	[array of objects]	An array of report result rows. Each row is an array of values as defined by the `schema` object.
forecastRows	[array of objects]	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	array of objects	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	array of objects	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. `values`(array of strings): Values to filter on.
group	array of objects	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. See Split costs. `id`: Dimension ID. `includeOrigin`(boolean) `mode`: Cost distribution method. Possible values: `even`, `custom`, `proportional`. `origin`(object) `targets` (array of objects)
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 (Synchronous run for a saved report)

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/{CUSTOMER_ID}/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.