Precaución: Estás viendo la documentación de la interfaz REST de la API. La mayoría de nuestras bibliotecas cliente oficiales usan gRPC. Consulta la Introducción a REST para obtener más detalles.
Puedes crear consultas con los métodos Search o SearchStream.
Ambos métodos admiten las mismas consultas y devuelven resultados equivalentes. El método Search devuelve datos en páginas de tamaño fijo de 10,000 filas, lo que te permite iterar un conjunto de resultados con paginación. Esto podría ser ventajoso en condiciones de red poco confiables o de bajo ancho de banda, por ejemplo, para segmentar un conjunto de resultados grande en respuestas más pequeñas que se pueden volver a recuperar si se pierde la conexión. Por otro lado, el método SearchStream transmite todo el conjunto de resultados en una sola respuesta, lo que puede ser más eficiente para la recuperación de datos masivos.
Tanto Search como SearchStream usan la misma URL base:
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'"}
Si hay más de 10,000 filas en los resultados, se devuelve un nextPageToken en la respuesta:
Si repites la misma búsqueda con un pageToken agregado con los valores de la solicitud anterior, se recuperará la siguiente página de resultados:
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"}
Para usar el método SearchStream, que devuelve todos los resultados en una sola respuesta transmitida, cambia el método de servicio en la URL a searchStream (pageToken no es obligatorio para 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'"}
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Falta la información que necesito","missingTheInformationINeed","thumb-down"],["Muy complicado o demasiados pasos","tooComplicatedTooManySteps","thumb-down"],["Desactualizado","outOfDate","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Problema con las muestras o los códigos","samplesCodeIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-05 (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."]]
