> [!NOTE] > **Objective:** Understand how to retrieve objects and performance stats using [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService). For reporting concepts, see the [reporting guides](https://developers.google.com/google-ads/api/docs/reporting/overview). The [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) is the unified object retrieval and reporting service of the Google Ads API. The service has methods that: - Retrieve specific attributes of objects. - Retrieve performance metrics for objects based on a date range. - Order objects based on their attributes. - Use conditions to indicate which objects you want returned in the response. - Limit the number of objects returned. The [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) can return results in two ways: - [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) returns all rows in a single streaming response, which is more efficient for large (greater than 10,000 rows) result sets. This is recommended if your application downloads full result sets or processes rows as a stream. - [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search) breaks up large responses into manageable pages of results. This is useful if your interactive application displays a page of results at a time. Learn more about [paging versus streaming](https://developers.google.com/google-ads/api/docs/reporting/streaming). ## Make a request [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) expects a [`SearchGoogleAdsStreamRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/SearchGoogleAdsStreamRequest), and [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search) expects a [`SearchGoogleAdsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/SearchGoogleAdsRequest). Both request types include: - A `customer_id` - A Google Ads Query Language `query` that indicates which resource to query, the attributes, segments, and metrics to retrieve, and the conditions to use to restrict which objects are returned Depending on the method, the request also supports method-specific fields: - **`SearchGoogleAdsStreamRequest` (`SearchStream` only)** : - An optional [`summary_row_setting`](https://developers.google.com/google-ads/api/reference/rpc/v26/SummaryRowSettingEnum.SummaryRowSetting) to request a summary row containing aggregated metrics - **`SearchGoogleAdsRequest` (`Search` only)** : - An optional `page_token` to retrieve the next batch of results when using [paging](https://developers.google.com/google-ads/api/docs/reporting/paging) (`page_size` is fixed at 10,000 rows; setting `page_size` in the request throws a [`RequestError.PAGE_SIZE_NOT_SUPPORTED`](https://developers.google.com/google-ads/api/reference/rpc/v26/RequestErrorEnum.RequestError#page_size_not_supported) error) - An optional [`search_settings`](https://developers.google.com/google-ads/api/reference/rpc/v26/SearchSettings) message to configure `return_summary_row`, `return_total_results_count`, and `omit_results` - An optional `validate_only` boolean to validate the query without executing it For more information on Google Ads Query Language, check out the [Google Ads Query Language guide](https://developers.google.com/google-ads/api/docs/query/overview). ## Process a response The [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) returns a list of [`GoogleAdsRow`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsRow) objects (either inside streamed [`SearchGoogleAdsStreamResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/SearchGoogleAdsStreamResponse) batches or in a paged [`SearchGoogleAdsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/SearchGoogleAdsResponse)). Each `GoogleAdsRow` represents an object returned by a query, and consists of a set of attributes that are populated based on the fields requested in the `SELECT` clause. Attributes not included in the `SELECT` clause are not populated on the `GoogleAdsRow` objects in the response. For example, although an `ad_group_criterion` has a `status` attribute, the `status` field of the row's `ad_group_criterion` attribute is not populated in a response for a query where the `SELECT` clause does not include `ad_group_criterion.status`. Similarly, the `campaign` attribute of the row is not populated if the `SELECT` clause does not include any fields from the `campaign` resource. Each `GoogleAdsRow` can have different attributes and metrics from another row in the same result set; so the rows should be viewed as objects rather than fixed rows of a table. ## UNKNOWN and UNSPECIFIED enum types Resources that are returned with an enum value of `UNKNOWN` are not fully supported in that API version, whereas `UNSPECIFIED` indicates that an enum field has not been set or was not requested in the `SELECT` clause. Resources with an `UNKNOWN` enum value could have been created through other interfaces such as the Google Ads UI. You can select metrics when a resource has a type of `UNKNOWN`, but you cannot mutate the resource through the API. An example of this would be a campaign or ad type available in the UI that is not supported in the API version you are querying. Here are some considerations to keep in mind: - A resource with an `UNKNOWN` type can be supported in a later API version or stay `UNKNOWN` indefinitely. - New objects with type `UNKNOWN` can appear at any time. These objects are backward-compatible because the `UNKNOWN` enum value is present on every enum in the API. Resources are returned with `UNKNOWN` so that you have an accurate view of your account's overall performance metrics. - `UNKNOWN` resources can have detailed metrics attached to them that are queryable. - `UNKNOWN` resources are typically fully visible in the Google Ads UI. - `UNKNOWN` resources generally cannot be mutated through the API. ## Segmentation The response contains one `GoogleAdsRow` for each combination of the following: - Instance of the main resource specified in the `FROM` clause - Value of each selected `segments` field For example, the response for a query that selects `FROM campaign` and has `segments.ad_network_type` and `segments.date` in the `SELECT` clause contains one row for each combination of the following: - `campaign` - `segments.ad_network_type` - `segments.date` Results are implicitly segmented by each instance of the main resource, not by the values of the individual fields selected. For example, SELECT campaign.status, metrics.impressions FROM campaign WHERE segments.date DURING LAST_14_DAYS results in one row per **campaign** , not one row per distinct value of the `campaign.status` field. > [!NOTE] > **Note:** Segment availability can differ across API versions. For example, `segments.click_type` on `AdGroupAsset`, `CampaignAsset`, and `CustomerAsset` and `segments.ad_sub_network_type` on `campaign_budget` are selectable only in v23 and earlier; `segments.ad_network_type` on `PerformanceMaxPlacementView` is available in v24 and later; `segments.ad_sub_format_type` and `segments.loyalty_membership` are available in v25 and later; and `segments.search_lift_keyword_bundle` and `segments.search_property` are available in v26 and later. Use [`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/docs/concepts/field-service) to verify segment compatibility for the API version you are querying.