Report Tasks Fundamentals

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 4 property identifier to be specified inside a URL request path in the form of properties/GA4_PROPERTY_ID, such as:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks

The report is generated based on the Google Analytics event data collected in the specified Google Analytics 4 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/GA4_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:

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.

{
  "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:

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.

{
  "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).

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

If the Report Task is ready, a response containing generated report is returned:

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}