You can generate reports with the Cloud Channel API to retrieve billing and licensing data for Google Cloud and Google Maps products, billing data for Google Workspace, and expense data for Google Voice. The available report types provide this data at various levels of aggregation. For more information, see Cloud Channel Report Types.
Running a report has four steps:
- Find and select a report type.
- Start a report job.
- Wait for the job to finish.
- Fetch the results.
Find available report types
To determine the set of available report types, use the
listReports method.
A successful response returns an HTTP 200 status code and a list of report
definitions. The following is an example response.
"reports": [
{
"name": "accounts/C123abcd4/reports/0bvgh484"
"display_name": "Google Cloud Platform Daily Costs"
"columns": [
{
"column_id": "usage_start_date_time"
"display_name": "Usage start date"
"data_type": DATE_TIME
},
{
"column_id": "cost_at_list_price"
"display_name": "Cost at list price"
"data_type": MONEY
},
{
"column_id": "customer_cost"
"display_name": "Customer cost"
"data_type": MONEY
},
{
"column_id": "net_cost"
"display_name": "Net cost"
"data_type": MONEY
}
]
},
...
]
Reports response
A listReports response shows the following information:
name: A unique ID for the report. You must provide this when running a report.display_name: A description of the report.columns: A list of data elements similar to columns in spreadsheets or database tables. Elements include:
Run a report
To start a report job, call
runReportJob.
The name field uses the report name from
listReports.
You must provide the date range of the data.
You can run reports based on usage time or invoices by providing a range of usage dates or invoice dates respectively. You can find more information in the Report request date ranges section of Analyze a report.
When you're ready to run your report, your request should resemble the following
example:
POST https://cloudchannel.googleapis.com/v1/accounts/C123abcd4/reports/x0ol2z5s:run
A successful response returns an HTTP 200 status code and an
Operation.
Track report progress
You can check if your report job is done by calling
getOperation with
operation.name until operation.done returns true.
If operation.result.error is set, check the operation's status for more
information. Otherwise, operation.result.response provides information
about the report job and its data.
Example response:
"report_job":
{
"name": "accounts/C123abcd4/reportJobs/ab12345cd4",
"report_status":
{
"state": AVAILABLE,
"start_time": 1649450584,
"end_time": 1649450620,
}
},
"report_metadata":
{
"report":
{
"name": "accounts/C123abcd4/reports/x0ol2z5s"
"display_name": "Cloud Platform Billing Per Day"
"columns": [
{
"column_id": "usage_start_date_time"
"display_name": "Usage start date"
"data_type": DATE_TIME
},
{
"column_id": "cost_at_list_price"
"display_name": "Cost at list price"
"data_type": MONEY
},
{
"column_id": "customer_cost"
"display_name": "Customer cost"
"data_type": MONEY
},
{
"column_id": "net_cost"
"display_name": "Net cost"
"data_type": MONEY
}
]
},
"row_count": 143,
"date_range":
{
"usage_start_date_time":
{
"year": 2022
"month": 4
"day": 1
"hours": 0
"minutes": 0
"seconds": 0
"time_zone":
{
"id": America/Los_Angeles}
}
}
},
{
"usage_end_date_time":
{
"year": 2022
"month": 4,
"day": 8,
"hours": 11,
"minutes": 6,
"seconds": 16,
"time_zone":
{
"id": "America/Los_Angeles"
}
}
}
}
Fetch report results
After the job finishes, call fetchReportResults with
operation.result.response.report_job.name, page_size to specify the number of
rows to return and page_token to retrieve pages of data.
The response includes the following:
report_metadata: The report name, display name, and list of columns. This metadata matches the metadata from the finished report's operation.rows: A list of records. Each row contains the same number of elements as the list of columns. A row's value matches the column description in the same position.- The maximum number of rows to return is set by
page_size. You might see fewer rows than that number, even if more rows are available.
- The maximum number of rows to return is set by
next_page_token: If set, shows there are more rows to retrieve through additional calls tofetchReportResultswith this token provided in thepage_tokenfield.
A successful response returns an HTTP 200 status code, with the body of the
response containing the report's description (the same data from getOperation)
and data in rows.
Example response:
"report_metadata":
{
"report":
{
"name": "accounts/C123abcd4/reports/x0ol2z5s"
"display_name": "Cloud Platform Billing Per Day"
"columns": [
...
},
"rows": [
{
"values": [
{
"value":
{
"date_time_value":
{
"year": 2022,
"month": 4,
"day": 5,
"hours": 0,
"minutes": 0,
"seconds": 0,
"time_zone":
{
"id": America/Los_Angeles}
}
}
}
},
{
"value":
{
"money_value":
{
"currency_code": "USD",
"units": 120,
"nanos": 100000000,
}
}
},
{
"value":
{
"money_value":
{
"currency_code": "USD",
"units": 115,
"nanos": 430000000,
}
}
},
{
"value":
{
"money_value":
{
"currency_code": "USD",
"units": 105,
"nanos": 270000000,
}
}
}
},
{
"values": [
...
}
],
"next_page_token": "4893je8ek"