Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.
You can create queries using either of the Search or SearchStream methods.
Both methods support the same queries and return equivalent results. The
Search method returns data in fixed size pages of 10,000 rows, enabling you
to iterate over a result set using pagination. This could be advantageous in low
bandwidth or unreliable network conditions, for example, to segment a large
result set into smaller responses that can be re-fetched if a connection is
lost. The SearchStream method, on the other hand, streams the entire result
set back in a single response, which can be more efficient for bulk data
retrieval.
Both Search and SearchStream use the same base URL:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"}
If there are more than 10,000 rows in the results a nextPageToken is
returned in the response:
Repeating the same query with a pageToken added with the values from the
previous request fetches the next page of results:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'","pageToken":"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"}
To use the SearchStream method, which returns all results in a single streamed
response, change the service method in the URL to searchStream
(pageToken is not required by SearchStream):
POST/v21/customers/CUSTOMER_ID/googleAds:searchStreamHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"}
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eThe Google Ads API offers a unified mechanism for retrieving attributes and reporting metrics, allowing you to create complex queries using the Google Ads Query Language.\u003c/p\u003e\n"],["\u003cp\u003eYou can retrieve data using either the \u003ccode\u003eSearch\u003c/code\u003e or \u003ccode\u003eSearchStream\u003c/code\u003e methods, with \u003ccode\u003eSearch\u003c/code\u003e returning paginated results and \u003ccode\u003eSearchStream\u003c/code\u003e providing a single streamed response.\u003c/p\u003e\n"],["\u003cp\u003eFor large result sets exceeding 10,000 rows, use the \u003ccode\u003enextPageToken\u003c/code\u003e to retrieve subsequent pages of data when using the \u003ccode\u003eSearch\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eBoth \u003ccode\u003eSearch\u003c/code\u003e and \u003ccode\u003eSearchStream\u003c/code\u003e utilize the same base URL and query structure, differing only in how the results are delivered.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eSearchStream\u003c/code\u003e method wraps results in a JSON array, unlike most other API calls which return a single JSON object.\u003c/p\u003e\n"]]],[],null,["# Search & SearchStream\n\nondemand_video\n[Video: Reporting](/google-ads/api/videos/catalog/working-with-rest-3)\n| **Note:** Refer to the [reporting guide](/google-ads/api/docs/reporting/overview) to learn about various reporting concepts.\n| **Note:** See the [Search](/google-ads/api/rest/examples#search) section of the accompanying examples for more complete examples.\n\nThe Google Ads API has a unified [attribute retrieval and metrics reporting\nmechanism](/google-ads/api/docs/reporting/overview)\nthat lets you create queries using the [Google Ads Query\nLanguage](/google-ads/api/docs/query/overview).\nThis enables complex queries that can return large quantities of data about\nindividual Google Ads accounts.\n\nYou can create queries using either of the `Search` or `SearchStream` methods.\nBoth methods support the same queries and return equivalent results. The\n`Search` method returns data in fixed size pages of 10,000 rows, enabling you\nto iterate over a result set using pagination. This could be advantageous in low\nbandwidth or unreliable network conditions, for example, to segment a large\nresult set into smaller responses that can be re-fetched if a connection is\nlost. The `SearchStream` method, on the other hand, streams the entire result\nset back in a single response, which can be more efficient for bulk data\nretrieval.\n\nBoth `Search` and `SearchStream` use the same base URL: \n\n```html\n https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds\n``` \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n\"query\": \"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\"\n}\n```\n\nIf there are more than 10,000 rows in the results a `nextPageToken` is\nreturned in the response: \n\n```javascript\n{\n \"results\": [\n // ...\n // ...\n // ...\n ],\n \"nextPageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\",\n \"fieldMask\": \"adGroupCriterion.keyword.text,adGroupCriterion.status\"\n}\n```\n\nRepeating the same query with a `pageToken` added with the values from the\nprevious request fetches the next page of results: \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n\"query\": \"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\",\n\"pageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\"\n}\n```\n\nTo use the `SearchStream` method, which returns all results in a single streamed\nresponse, change the service method in the URL to `searchStream`\n(`pageToken` is not required by `SearchStream`): \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:searchStream HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"query\": \"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\"\n}\n```\n| **Note:** The results of a `SearchStream` API call are wrapped in a JSON array, whereas most other API calls return a single JSON object as the response message. See the [JSON mappings](/google-ads/api/rest/design/json-mappings) section for more info."]]
