Using report tasks, you can start a long-running asynchronous request to create a customized report of your Google Analytics event data.
The Report Task resource generated from this request can be used to access customized reports by all users with read access to your Google Analytics property.
A customized report will be available for 72 hours after it is ready. After this period, the corresponding report task resource and its contents will be automatically deleted.
Create a Report Task
The Google Analytics Data API v1 uses an asynchronous approach to
create Report Tasks. First, a request to the
reportTasks.create
method is necessary to create a Report Task. Then, the
reportTasks.query
method is used to retrieve the generated customized report.
In addition, you can use
reportTasks.get
to retrieve configuration metadata about a specific Report Task and
reportTasks.list
to list all Report Tasks for a property.
Select a reporting entity
All methods of the Data API v1 require the
Google Analytics property identifier
to be specified inside a URL request path in the form of
properties/GA_PROPERTY_ID
, such as:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
The report is generated based on the Google Analytics event data collected in the specified Google Analytics property.
If you are using one of the Data API client libraries,
there is no need to manipulate the request URL path manually.
Most API clients provide a property
parameter that expects a
string in the form of properties/GA_PROPERTY_ID
.
See Quick start guide for examples
of using the client libraries.
Request the Report Task creation
To create a Report Task, call the
reportTasks.create
method using the
ReportTask
object in a request. The following parameters are required:
reportDefinition
field which describes the definition of a customized report. This parameter's structure is similar to the report definition used by Core Reporting methods.
Example Report Task creation request:
HTTP Request
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
A response of the reportTasks.create
method contains the Report
Task name in the name
field (such as
properties/1234567/reportTasks/123
), which can be used in
subsequent queries to obtain the status of a Report Task and retrieve the
resulting report.
HTTP Response
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Get the Report Task readiness state
It may take several minutes to generate a report after the
reportTasks.create
call. You can obtain the readiness state for an Report Task by calling the
reportTasks.get
method.
Use the Report Task name (such as properties/1234567/reportTasks/123
)
you received from a reportTasks.create
response to specify the
Report Task.
Example:
HTTP Request
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
The readiness status for an Report Task is returned in the
state
field of a response. Once the report generation is complete,
the state of a Report Task changes from CREATING
to ACTIVE
.
The reportMetadata
field contains the high level information about the generated report, such as
the rows count and the amount of quota tokens charged.
HTTP Response
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
You can obtain the state of all Report Tasks by calling the
reportTasks.list
method.
Retrieve the generated report
Once the Report Task created using the
reportTasks.create
method is generated, call the
reportTasks.query
method and specify the Report Task name
(such as properties/1234567/reportTasks/123
).
HTTP Request
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
If the Report Task is ready, a response containing generated report is returned:
HTTP Response
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}