BúsquedaGoogle API5 credits

search_web

El índice de Google, en JSON. Cada resultado incluye el título, la URL, el fragmento y las variantes resaltadas del propio Google, junto con un bloque de metadatos con el total de coincidencias y el tiempo que tardó la búsqueda. Los filtros de sitio, tipo de archivo, idioma, actualidad y búsqueda segura se aplican como operadores reales de Google.

Casos de uso

Pipelines de investigación

Encuentre fuentes sobre un tema y pase las URL directamente a batch_scrape o extract_content.

Búsqueda acotada a un sitio

Use site para buscar dentro de un único dominio: un sustituto del buscador interno cuando no existe o funciona mal.

Búsqueda de documentos

Combine file_type con una consulta para encontrar PDF, hojas de cálculo o presentaciones sobre un tema.

Seguimiento de novedades

Limite al último día o a la última semana con time_range para detectar nuevas menciones de un tema o una marca.

Descubrimiento competitivo

Vea qué páginas muestra Google para los términos que le interesan y cuántos resultados hay en total.

Anclaje de agentes

Dé a un modelo resultados de búsqueda actuales con los que trabajar, en lugar de depender de lo que memorizó.

Endpoint

POST/api/v1/tools/search_web

Auth Required

1 req/s en el plan Free

5 credits

Parameters

limit admite hasta 100, pero Google devuelve como máximo 10 resultados por solicitud: un limit mayor no falla, simplemente le da 10. Recorra el resto con offset, una búsqueda (y 5 credits) por página. Envíe exactamente uno de query o queries: un lote queries ejecuta una búsqueda de Google por consulta, y 5 credits × las consultas que envió —50 con el máximo de 10— es la proyección, un techo y no el cargo. Solo se cobran las consultas que devolvieron resultados.

Name	Type	Required	Default	Description
query	string	Optional	-	Los términos de búsqueda. Los operadores de Google que escriba aquí funcionan igual que en el cuadro de búsqueda, y `site` y `file_type` se añaden como operadores adicionales. Envíe exactamente uno de `query` o `queries`. Example: mcp server for web scraping
queries	string[]	Optional	-	Entre 1 y 10 consultas de búsqueda que ejecutar en una sola llamada, en lugar de `query`. Cada una recorre la misma canalización que una búsqueda simple, y las cargas útiles vuelven en `results_by_query`: una lista en el orden en que las envió, con una entrada por consulta que lleva su propio `query` más los campos de esa búsqueda, o `query` y `error` cuando esa búsqueda concreta falló. `queries` devuelve su entrada tal cual y `count` es su longitud. Una llamada a `search_web` cuesta 5 credits por cada consulta que devolvió resultados: una `query` simple cuesta 5, y un lote `queries` se proyecta en 5 × el número de consultas enviadas, que es un techo: cada consulta que falló no se cobra, así que un lote en el que no tuvo éxito ninguna no cuesta nada. Una consulta repetida en la lista se ejecuta dos veces y se cobra dos veces cuando ambas ejecuciones devuelven resultados. Un lote en el que no tuvo éxito ninguna sigue siendo un 200 con el sobre habitual: `count` tal como se envió, una entrada `{ query, error }` por consulta y `credits_used: 0`. Envíe exactamente uno de `query` o `queries`: enviar ambos, o ninguno, es un 400. Example: ["mcp server for web scraping", "model context protocol tools"]
limit	number	Optional	10	Resultados que devolver, de 1 a 100, pero Google limita cada solicitud a 10, así que cualquier valor por encima de 10 se comporta como 10. Example: 10
offset	number	Optional	0	Índice de base cero del primer resultado. Use 10, 20, 30 para paginar. Cada página es una búsqueda aparte y cuesta 5 credits. Example: 10
lang	string	Optional	-	Limita a documentos en un solo idioma, con un código ISO 639-1. Se devuelve en `search_metadata.lang`, que toma `en` por defecto si lo omite. Example: es
site	string	Optional	-	Limita a un dominio. Se añade a su consulta como `site:<dominio>`, así que se comporta igual que si lo escribiera. Example: docs.anthropic.com
safe_search	boolean	Optional	-	Activa el filtrado SafeSearch de Google. Desactivado salvo que lo indique. Example: true
time_range	string	Optional	-	Limita por actualidad: `day`, `week`, `month`, `year` o `all`. `all` no aplica ninguna restricción, y es además el valor por defecto. Example: week
file_type	string	Optional	-	Limita a una única extensión de archivo. Se añade como `filetype:<ext>`, así que `pdf`, `xlsx` y `pptx` funcionan. Example: pdf
redact_pii	boolean \| object	Optional	false	Elimine los datos personales del texto que devuelve esta llamada, antes de que el resultado se almacene o se envíe de vuelta. Se aplica a los títulos, fragmentos y búsquedas relacionadas que devuelve Google; la `query` que envió se devuelve intacta. `true` es la forma abreviada de `{ mode: "fast" }`: las cuatro clases de expresiones regulares, etiquetadas. Siempre que pida redacción, la respuesta lleva `redaction: { entities, count, mode }` dentro de `data`, incluso cuando no hubo coincidencias (`count: 0`), de modo que «no se encontró nada» nunca se confunde con «se ignoró el parámetro»; una clase sin coincidencias se omite en lugar de informarse como `0`. La redacción se ejecuta antes de almacenar el resultado, así que un resultado grande que se lea después con [read_result](/docs/api-reference/tools/read-result) ya viene redactado. Dos límites deliberados: las direcciones (`url`, `link`, `href`, `canonical_url`) nunca se redactan, y los contadores derivados del texto (`content_length`, `word_count`, `character_count`) lo describen tal como se extrajo, antes de la redacción. Example: true
max_inline_chars	number	Optional	40000	Tamaño máximo del resultado que se devuelve en línea, en caracteres de su JSON (de 1.000 a 10.000.000). Por encima, la respuesta incluye `preview` (los primeros `max_inline_chars` caracteres del JSON formateado), `result_handle`, `total_chars`, `truncated: true` y `expires_at`, y [read_result](/docs/api-reference/tools/read-result) lee el resto por 1 credit por llamada. Los resultados almacenados se conservan 1 hora. Example: 40000

Búsqueda por lotes

Envía queries en lugar de query para ejecutar hasta 10 búsquedas en una llamada. Cada consulta es la misma búsqueda de Google que ejecuta una llamada con query —esta API no expande consultas, no usa caché, no deduplica ni reordena resultados— y cada consulta que devolvió resultados se cobra a 5 credits.

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "mcp server for web scraping",
      "model context protocol tools"
    ],
    "limit": 10,
    "redact_pii": true
  }'

Respuesta por lotes

results_by_query es una lista en el orden en que envió las consultas, con una entrada por consulta, así que una consulta repetida aparece dos veces. Una consulta que falló lleva error en lugar de sus resultados y no se cobra; la llamada devuelve 200 en cualquier caso, incluso cuando fallaron todas, así que credits_used es el número de consultas que sí tuvieron éxito por 5. Una llamada con query simple no cambia: en ella no aparece ni queries, ni count, ni results_by_query.

response.jsonJson

{
  "success": true,
  "data": {
    "queries": ["mcp server for web scraping", "model context protocol tools"],
    "count": 2,
    "results_by_query": [
      {
        "query": "mcp server for web scraping",
        "search_metadata": { "total_results": 48200, "results_returned": 10 },
        "results": [
          {
            "title": "CrawlForge MCP Server",
            "url": "https://www.crawlforge.dev/",
            "snippet": "Write to <EMAIL> for access."
          }
        ]
      },
      {
        "query": "model context protocol tools",
        "error": "Search failed: Google API daily quota exceeded"
      }
    ],
    "redaction": { "entities": { "EMAIL": 1 }, "count": 1, "mode": "fast" }
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 720
}

Ejemplos de solicitud

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mcp server for web scraping",
    "limit": 10,
    "time_range": "month",
    "safe_search": true
  }'

Ejemplo de respuesta

200 OK460ms

{
  "success": true,
  "data": {
    "query": "mcp server for web scraping",
    "search_metadata": {
      "total_results": 48200,
      "results_returned": 1,
      "offset": 0,
      "search_time": 0.312,
      "lang": "en",
      "safe_search": false,
      "time_range": "month",
      "site": null,
      "file_type": null
    },
    "results": [
      {
        "title": "CrawlForge MCP Server — 31 web tools for Claude",
        "url": "https://www.crawlforge.dev/",
        "snippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "displayLink": "www.crawlforge.dev",
        "formattedUrl": "https://www.crawlforge.dev/",
        "htmlSnippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "htmlTitle": "CrawlForge MCP Server — 31 web tools for Claude",
        "cacheId": "x8Kd0PqR2mUJ",
        "pagemap": {
          "metatags": [
            {
              "og:type": "website"
            }
          ]
        }
      }
    ],
    "spelling_correction": "mcp server for web scraping",
    "related_searches": [
      "mcp web scraping tools",
      "model context protocol scraper"
    ]
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 460
}

Field Descriptions

data.queryLos términos que Google buscó realmente, que pueden diferir de los que envió

data.search_metadata.total_resultsLa estimación de Google de documentos coincidentes. Es una estimación, no un recuento que pueda recorrer paginando

data.search_metadata.results_returnedLongitud de `results`: como máximo 10

data.search_metadata.search_timeSegundos que empleó Google, según lo informa el propio Google. No es la latencia de su solicitud

data.results[].urlEl enlace de destino. `formattedUrl` es la versión de visualización que Google hace de la misma dirección

data.results[].htmlSnippetEl fragmento conservando el resaltado `<b>` de los términos que añade Google. Escápelo antes de renderizarlo

data.results[].cacheIdEl identificador de caché de Google, cuando existe. No aparece en resultados que Google no ha cacheado

data.results[].pagemapDatos estructurados que Google extrajo de la página: metaetiquetas, imágenes, tipos de schema.org. Su forma varía en cada resultado y puede no aparecer

data.spelling_correctionLa corrección ortográfica sugerida por Google, o `null` cuando no hay ninguna

data.related_searchesSugerencias de consultas relacionadas. A menudo es un array vacío

credits_used5 credits fijos por búsqueda, sea cual sea el `limit` que haya pedido

Manejo de errores

Consulta no válida (400 Bad Request)

VALIDATION_ERROR. query es obligatorio y no puede estar vacío. El mismo estado cubre un limit fuera de 1-100, un offset negativo o un time_range que no sea uno de los cinco valores aceptados. Enviar a la vez query y queries, o ninguno de los dos, es el mismo 400, igual que un array queries vacío o con más de 10 entradas, un objeto redact_pii que nombre una entidad que esta API no puede redactar, o redact_pii con mode: "model", que necesita un LLM que esta API no ejecuta.

La búsqueda falló (500 Internal Server Error)

TOOL_ERROR. Cubre un error de Google, una cuota diaria agotada y un tiempo de espera de 10 segundos. El mensaje indica la causa. Una búsqueda fallida no se cobra. Esta es la ruta de query simple: una búsqueda que falla da error como siempre. Un lote queries nunca llega aquí: una consulta fallida se informa dentro de su propia entrada de results_by_query y la llamada sigue devolviendo 200, incluso cuando fallaron todas las consultas.

Nota:

Una búsqueda sin coincidencias devuelve 200 con un array results vacío y total_results: 0, no un error. Compruebe results_returned en lugar de fiarse del código de estado.

Costo en credits

5 credits

5 credits por búsqueda

Una búsqueda es un cargo, devuelva 10 resultados o ninguno. Paginar con offset implica otra búsqueda, así que diez páginas cuestan 50 credits. Las búsquedas fallidas no se cobran. Una llamada a search_web cuesta 5 credits por cada consulta que devolvió resultados: una query simple cuesta 5, y un lote queries se proyecta en 5 × el número de consultas enviadas, que es un techo: cada consulta que falló no se cobra, así que un lote en el que no tuvo éxito ninguna no cuesta nada. Diez consultas en una llamada se proyectan en 50 y cuestan 50 solo si las diez devolvieron resultados. redact_pii en su modo fast por defecto no añade nada.

Qué incluye:

El índice en vivo de Google, no una copia cacheada

Título, URL, fragmento y las variantes resaltadas de Google

Estimación del total de coincidencias y tiempo de búsqueda

Filtros site, file_type, lang, time_range y de búsqueda segura

Corrección ortográfica y búsquedas relacionadas cuando Google las proporciona

Recomendaciones por plan:

Plan Free: 1,000 credits de prueba por única vez = 200 búsquedas

Plan Hobby: 5,000 credits = 1,000 búsquedas ($19/mo)

Plan Professional: 100,000 credits = 20,000 búsquedas ($99/mo)