Monitor offline data diagnostics

AI-generated Key Takeaways

outlined_flag

• The Google Ads API can be used to retrieve offline data diagnostics for monitoring the health of conversion import and adjustment processes.

• Diagnostics can be aggregated at the account level using offline_conversion_upload_client_summary or at the conversion action level using offline_conversion_upload_conversion_action_summary.

• Summary reports provide information on the overall status, event counts (total, successful, pending), and alerts for recent imports.

• Detailed daily and job summaries are available to analyze import performance over the last 7 days or for the 7 most recent import requests.

• Periodically reviewing these summaries and addressing alerts can help ensure the successful recording of conversions and enhancements.

Use the Google Ads API to retrieve offline data diagnostics, which contain information about the overall health of your conversion import and adjustment processes.

To retrieve the latest offline data diagnostics for your account, use one of the following resources:

• offline_conversion_upload_client_summary aggregates import diagnostics at the account level.
• offline_conversion_upload_conversion_action_summary aggregates import diagnostics at the conversion action level.

Account level diagnostics

To retrieve account level conversion upload diagnostics, use the following GAQL query:

SELECT
  customer.id,
  offline_conversion_upload_client_summary.alerts,
  offline_conversion_upload_client_summary.client,
  offline_conversion_upload_client_summary.daily_summaries,
  offline_conversion_upload_client_summary.job_summaries,
  offline_conversion_upload_client_summary.last_upload_date_time,
  offline_conversion_upload_client_summary.pending_event_count,
  offline_conversion_upload_client_summary.pending_rate,
  offline_conversion_upload_client_summary.status,
  offline_conversion_upload_client_summary.success_rate,
  offline_conversion_upload_client_summary.successful_event_count,
  offline_conversion_upload_client_summary.total_event_count
FROM offline_conversion_upload_client_summary

This query returns separate OfflineConversionUploadClientSummary rows for each type of client used in recent imports. For example, if you recently imported using both the Google Ads API and the Google Ads UI, the results contain separate entries for the client values of GOOGLE_ADS_API and GOOGLE_ADS_WEB_CLIENT.

Conversion action level diagnostics

To retrieve conversion upload diagnostics at the conversion action level, use the following GAQL query:

SELECT
  offline_conversion_upload_conversion_action_summary.conversion_action_name,
  offline_conversion_upload_conversion_action_summary.alerts,
  offline_conversion_upload_conversion_action_summary.client,
  offline_conversion_upload_conversion_action_summary.daily_summaries,
  offline_conversion_upload_conversion_action_summary.job_summaries,
  offline_conversion_upload_conversion_action_summary.last_upload_date_time,
  offline_conversion_upload_conversion_action_summary.pending_event_count,
  offline_conversion_upload_conversion_action_summary.status,
  offline_conversion_upload_conversion_action_summary.successful_event_count,
  offline_conversion_upload_conversion_action_summary.total_event_count
FROM offline_conversion_upload_conversion_action_summary
WHERE offline_conversion_upload_conversion_action_summary.conversion_action_id = < INSERT CONVERSION ACTION ID >

Similar to account level diagnostics, this query returns separate OfflineConversionUploadConversionActionSummary rows for each type of client used in recent imports. For example, if you recently imported using both the Google Ads API and the Google Ads UI, the results contain separate entries for the client values of GOOGLE_ADS_API and GOOGLE_ADS_WEB_CLIENT.

How to interpret these summaries

Each OfflineConversionUploadClientSummary or OfflineConversionUploadConversionActionSummary has a status field, that reflects the overall health of imports for the client. It also contains the following information:

• The count of total events received.
• The count of successfully processed events.
• The count of pending events (events that are still being processed).
• An alerts field, that provides a summary of errors, grouped by OfflineConversionError.

All of these fields contain information from the most recent full calendar day of imports. Use this information to assess the current health of your imports.

In addition, each OfflineConversionUploadClientSummary or OfflineConversionUploadConversionActionSummary contains two different types of reports:

daily_summaries

A successful_count, failed_count, and pending_count of import requests from the last 7 days, grouped by import date.

job_summaries

The successful_count, failed_count, and pending_count of the 7 most recent import requests, grouped by job_id. The job_id is an optional field of UploadClickConversionsRequest and UploadConversionAdjustmentsRequest. You can either set the job_id to a non-negative number less than 2^31 or let the Google Ads API assign a system-generated job ID to your request. Regardless of which option you choose, the UploadClickConversionsResponse or UploadConversionAdjustmentsResponse returns the job_id.

One scenario where assigning your own job_id is useful is when you have a single job or process that imports a large number of conversions using multiple requests. If you set the job_id on each of those requests to the same value, then you can retrieve a single entry for the job from job_summaries. If instead you let the Google Ads API assign a system-generated value to the job_id of each request, the job_summaries contains a separate entry for each request, which could make analyzing the overall health of your job more challenging.

How to use summaries

To ensure your import processes are recording conversions and enhancements as expected, periodically retrieve the summaries for each of your accounts. If the status of any summary is not EXCELLENT, use the list of errors under alerts to guide you through modifying your import process to reduce or eliminate those errors.

For example:

• If the status is NEEDS_ATTENTION, then a significant portion of your import operations failed. Review the errors under alerts and modify your import process to reduce or eliminate those errors.

• If the status is NO_RECENT_UPLOADS, then Google Ads has not received any recent imports for the client. If this is unexpected, then review the processes that perform imnports using that client.

  For example, if the status for GOOGLE_ADS_API is NO_RECENT_UPLOADS, that could indicate that your import process that uses the Google Ads API stopped running recently.

• To determine if there was a specific import date or job that sent a large number of events that failed to process, check the successful_count, failed_count, and pending_count of daily_summaries and job_summaries. Any events in a pending state may take up to 24 hours to complete.

More information on how to improve offline data diagnostics can be found in the Help center.

Restrictions

Keep the following in mind when retrieving import summaries:

• The Google Ads API only returns offline data diagnostics if the customer_id of the searchStream or search request is the same customer you used recently to import conversions.

  For example, a client account that uses cross-account conversion tracking may not contain any diagnostics. However, you can retrieve diagnostics by sending a request where the customer_id matches the customer_id of the manager account you use in imports.

• Google Ads treats CLICK_NOT_FOUND errors from enhanced conversions for leads imports as warnings. As a result, if alerts contains an entry for this error, the corresponding operations are still considered successful and are included in the successful_event_count.