Search

Returns all rows that match the search query. Uses pagination (nextPageToken) with up to 10,000 rows per page. For result sets larger than 10,000 rows, prefer GoogleAdsService.SearchStream. To build and validate queries, use the Google Ads Query Builder.

List of thrown errors: AuthenticationError AuthorizationError ChangeEventError ChangeStatusError ClickViewError HeaderError InternalError QueryError QuotaError RequestError

Proto definition GitHub

HTTP request

POST https://googleads.googleapis.com/v25/customers/{customerId}/googleAds:search

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer being queried.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "query": string,
  "pageToken": string,
  "pageSize": integer,
  "validateOnly": boolean,
  "searchSettings": {
    object (SearchSettings)
  }
}
Fields
pageSize

integer

This field is deprecated and will be removed in a future version of the API. Google Ads API returns a PAGE_SIZE_NOT_SUPPORTED error if this field is set in the request body.
pageToken

string

Token of the page to retrieve. If not specified, the first page of results will be returned. Use the value obtained from nextPageToken in the previous response in order to request the next page of results.
query

string

Required. The query string.
searchSettings

object (SearchSettings)

Settings that allow users to specify request count, summary row, and results behavior.
validateOnly

boolean

If true, the request is validated but not executed.

Response body

Response message for GoogleAdsService.Search.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "results": [
    {
      object (GoogleAdsRow)
    }
  ],
  "nextPageToken": string,
  "totalResultsCount": string,
  "fieldMask": string,
  "summaryRow": {
    object (GoogleAdsRow)
  },
  "queryResourceConsumption": string,
  "metricAttributes": [
    {
      object (MetricAttributes)
    }
  ]
}
Fields
fieldMask

string (FieldMask format)

FieldMask that represents what fields were requested by the user.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".
metricAttributes[]

object (MetricAttributes)

The metric attributes of the metrics in the results.
nextPageToken

string

Pagination token used to retrieve the next page of results. Pass the content of this string as the pageToken attribute of the next request. nextPageToken is not returned for the last page.
queryResourceConsumption

string (int64 format)

The amount of resources consumed to serve the query.
results[]

object (GoogleAdsRow)

The list of rows that matched the query.
summaryRow

object (GoogleAdsRow)

Summary row that contains summary of metrics in results. Summary of metrics means aggregation of metrics across all results, here aggregation could be sum, average, rate, etc.
totalResultsCount

string (int64 format)

Total number of results that match the query ignoring the LIMIT clause.

SearchSettings

Indicates search settings in request parameter.

JSON representation 
{
  "omitResults": boolean,
  "returnSummaryRow": boolean,
  "returnTotalResultsCount": boolean
}
Fields
omitResults

boolean

If true, results will be excluded from the response. Otherwise, results will be returned. Default is false.
returnSummaryRow

boolean

If true, summary row will be included in the response and sent in a response by itself after all other query results are returned. Default is false.
returnTotalResultsCount

boolean

If true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false.
Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.