Use a synchronous metrics to retrieve campaign delivery and attribution metrics in a single, low-latency HTTP request with no job polling required. Results are returned directly in the response body of your GET Get synchronous metrics call, typically within 3 seconds.

This is designed to be used for short timeframes (up to 7 days) and with a fixed set of dimensions. You should use this when you need fast, lightweight data for dashboards and real-time campaign optimization. For longer lookback windows, or for data that needs segmentation, use asynchronous reports instead.

When to use synchronous metrics vs. asynchronous reports

Key characteristics at a glance

Get synchronous metrics

To create a synchronous metrics make a GET Get synchronous metrics call and include the following in your request body parameters:

• account_uid - The unique identifier of the account to scope the metrics by.
• entity - The type of entity to collect metrics on: account, campaign, ad_group, ad, creative. If account, then account_uid value must be a single UID.
• entity_uids - A comma-separated list of entity unique identifiers to filter by. When entity is account, entity_uids must be a single uid equal to the value of the account_uid.
• event_group_uids - A comma-separated list of event group UIDs to filter by.
• start_date - The start date of the metrics (YYYY-MM-DD). Earliest allowed date is 37 months before today; must not be after today. Inclusive.
• end_date - The end date of the metrics (YYYY-MM-DD). Must be on or after start_date. Data from your end date is included in the results. Inclusive. end_date can be no more than 6 days after start_date, the maximum date range is 7 days.
• granularity - Time granularity for the metrics data. Accepted values are day (per-day breakdown) or total (aggregate for the provided date range). Required on the first page request; ignored when paginating with cursor. Maximum date range is 7 days.
• attributed_events_by - Attribution method required for action and cpa fields. Determines whether attributed events are measured by when the ad was seen (time_of_impression) or when the user converted (time_of_conversion). Ignored when paginating with cursor. Defaults to time_of_impression if not specified.
  

  📘

  Note: The asynchronous reports endpoint and the Ads Manager UI currently only provide time_of_conversion reporting.

• fields - A comma-separated list of field names to include in the metrics. At least one metric is required; dimensions alone are not valid. action and cpa fields follow the action_{name} and cpa_{name} naming pattern. The clicks field is not supported on this endpoint. Ignored when paginating with cursor. To see all available fields, call GET synchronous metrics fields parameters first.
• cursor - Pagination token for retrieving the next page of results. To paginate your metrics, pass the meta.pagination.next_cursor value from the response of the previous GET get synchronous metrics call into this parameter. Valid for 60 minutes after the first-page response. Use cursor together with limit on follow-up page requests only.
• limit - Number of results to return per page. Accepted range is 1-10,000. Limits the number of entities per page, not individual time-series rows within an entity. Default is 100.

A successful call returns your metrics data in the response body.

Dimensions

The synchronous endpoint supports limited dimensions to guarantee low latency.

Fields

Core metrics

Action fields

Order value fields

Cost Per Action (CPA) fields

Paginate metrics with cursor

How to paginate metrics using the cursor parameter in your request.

When you make a GET get synchronous metrics call, if a successful response includes a meta.pagination.next_cursor value and a "has_more":true then your metrics have at least one more page you can get.

To get the next page, make another GET get synchronous metrics call and include the meta.pagination.next_cursor value from your previous call in the cursor parameter of your new call.

The included object in your response

Every response includes an included object alongside data and meta. It surfaces the optimization settings (event group and attribution windows) configured for each ad group active within your requested scope and date range, regardless of what entity level you queried.

included.default_optimizations

included.default_optimizations is an array where each entry describes the default optimization settings for one ad group:

Example included block:

"included": {
  "default_optimizations": [
    {
      "ad_group_uid": "PadGrpL1rio1HP",
      "event_group_uid": "PaccO8EtiUHh",
      "attribution_window": ["click_14d", "view_14d"]
    },
    {
      "ad_group_uid": "PadGrp5o7dgU8h",
      "event_group_uid": "PaccO8EtiUHh",
      "attribution_window": ["click_14d", "view_14d"]
    }
  ]
}

Why this matters: mixed optimization settings

Ad groups within the same campaign or account can be configured to optimize toward different event groups. When you query at the account or campaign level, or when you query multiple ad groups without filtering to a specific event group, the conversion metrics you receive are a sum across all of those ad groups, potentially mixing data from different event groups in a single number. included.default_optimizations makes this transparent.

There are two scenarios to keep in mind:

Scenario 1 - Higher-level query with no event_group_uid filter

Ad Group 1 optimizes toward Event Group A; Ad Group 2 optimizes toward Event Group B. You request entity=account, fields=action_page_view, and don't pass event_group_uids.

The action_page_view count in your response is a sum of page views attributed through Event Group A (via Ad Group 1) and Event Group B (via Ad Group 2). included.default_optimizations shows you which event group each contributing ad group belongs to.

Scenario 2 - Ad group-level query with an explicit events_group_uid filter

You request entity=ad_group, include both Ad Group 1 and Ad Group 2 in entity_uids, set fields=action_page_view, and explicitly filter to Event Group A via event_group_uids.

The returned action_page_view counts for both ad groups will reflect Event Group A only, even for Ad Group 2, which natively optimizes toward Event Group B. included.default_optimizations still shows Ad Group 2's actual default event group, making it visible that its native optimization setting differs from the filter you applied.

Use included.default_optimizations any time you're working with conversion metrics to understand what's behind the numbers you receive and whether mixed event group settings could affect your interpretation.