BúsquedaBrave Search API5 credits

search_web

Un índice web en vivo, en JSON. Los resultados proceden del índice web independiente de la Brave Search API. Cada resultado incluye el título, la URL, el fragmento y una copia resaltada del fragmento, junto con un bloque de metadatos que indica cuánto tardó la búsqueda. Los filtros de sitio y tipo de archivo se aplican como operadores de búsqueda; el idioma, la actualidad y la búsqueda segura se envían como filtros de búsqueda.

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 una búsqueda web en vivo para los términos que le interesan. Para su posición exacta en Google, use serp_rank.

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 una solicitud devuelve como máximo 10 resultados: 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 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 como `site:`, `filetype:` y las frases entre comillas funcionan igual que en un 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 cada solicitud está limitada 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, hasta 90: los resultados posteriores al número 100 no están disponibles, y una página más allá de ellos vuelve con un array `results` vacío. Cada página es una búsqueda aparte y cuesta 5 credits. Example: 10
lang	string	Optional	-	Da preferencia a documentos en un solo idioma, con un código ISO 639-1; también se aceptan formas regionales como `zh-TW` y `pt-BR`. Es una preferencia, no un filtro estricto, así que pueden aparecer páginas en otros idiomas, y un código que el backend de búsqueda no admite se descarta en lugar de hacer fallar la búsqueda. 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 estricto de búsqueda segura. 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 y fragmentos que devuelve la búsqueda; 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 individual 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": null, "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 request timeout"
      }
    ],
    "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": null,
      "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",
        "pagemap": {
          "cse_thumbnail": [
            {
              "src": "https://imgs.search.brave.com/example-thumbnail"
            }
          ],
          "metatags": [
            {
              "article:published_time": "2026-10-01T00:00:00"
            }
          ]
        }
      }
    ],
    "spelling_correction": null,
    "related_searches": []
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 460
}

Field Descriptions

data.queryLa consulta que se buscó, tal como la envió, sin los operadores `site` y `file_type`

data.search_metadata.total_results`null`: el backend de búsqueda no informa de un recuento total de coincidencias. Pagine con `offset` hasta que `results_returned` sea 0

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

data.search_metadata.search_timeSegundos que tardó la búsqueda de origen, medidos por CrawlForge. No es la latencia total de su solicitud

data.results[].urlEl enlace de destino. `formattedUrl` lleva la misma dirección

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

data.results[].pagemapDetalles de la página cuando el buscador los tiene: `cse_thumbnail[0].src` (la URL de una miniatura) y `metatags[0]['article:published_time']` (la antigüedad de la página). No aparece cuando no hay ninguno de los dos

data.spelling_correctionLa consulta corregida cuando el buscador buscó con una ortografía corregida, o `null`

data.related_searchesSiempre un array vacío: el backend de búsqueda actual no devuelve búsquedas relacionadas. Se mantiene para que el código existente no deje de funcionar

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 la búsqueda de origen, un límite de frecuencia en el proveedor de búsqueda 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, 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:

Un índice web en vivo (Brave Search API), no una copia cacheada

Título, URL, fragmento y una copia resaltada del fragmento

Tiempo de búsqueda, más miniatura y antigüedad de la página cuando están disponibles

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

Corrección ortográfica cuando el buscador aplicó una

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)