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. > [!NOTE] > **Note:** report tasks are available in the [v1alpha](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks) version of the Data API. ## Create a report task > [!TIP] > **Tip:** To try report tasks interactively in Python without setting up a local environment, open the [Async report tasks Colab > notebook](https://developers.google.com/analytics/devguides/reporting/data/v1/notebooks/report-tasks). The Google Analytics Data API v1 uses an asynchronous approach to create report tasks. First, a request to the [`reportTasks.create`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create) method is necessary to create a report task. Then, the [`reportTasks.query`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/query) method is used to retrieve the generated customized report. In addition, you can use [`reportTasks.get`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/get) to retrieve configuration metadata about a specific report task and [`reportTasks.list`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.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](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id) 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](https://developers.google.com/analytics/devguides/reporting/data/v1/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](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart) for examples of using the client libraries. ### Request the report task creation To create a report task, call the [`reportTasks.create`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create) method using the [`ReportTask`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask) object in a request. The following parameters are required: - [`reportDefinition`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#%20ReportDefinition) field which describes the definition of a customized report. This parameter's structure is similar to the report definition used by [Core Reporting methods](https://developers.google.com/analytics/devguides/reporting/data/v1/basics). 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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create) call. You can obtain the readiness state for a report task by calling the [`reportTasks.get`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.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 a report task is returned in the [`state`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask.FIELDS.state) field of a response. Once the report generation is complete, the state of a report task changes from `CREATING` to `ACTIVE`. The [`reportMetadata`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks#ReportTask.FIELDS.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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/list) method. ### Retrieve the generated report When the report task created using the [`reportTasks.create`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks/create) method is generated, call the [`reportTasks.query`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.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" } } ## Next steps - Try the interactive [Async report tasks Colab notebook](https://developers.google.com/analytics/devguides/reporting/data/v1/notebooks/report-tasks) to create, monitor, and query asynchronous report tasks using the Python client library. - Review the [`properties.reportTasks` REST API reference](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.reportTasks). - Learn more about [Data API quotas and limits](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas).