Brave Search API: Search vs Answers, precios, prepago y clave

Brave Search API tiene hoy dos planes que deciden casi todo: Search, que te devuelve resultados web o contexto listo para un modelo y deja que tu aplicación redacte la respuesta, y Answers, que te devuelve la respuesta ya redactada, con citas, a través de una interfaz compatible con el SDK de OpenAI. Search cuesta 5 $ por cada 1.000 peticiones y admite 50 por segundo; Answers cuesta 4 $ por cada 1.000 consultas más 5 $ por millón de tokens de entrada y 5 $ por millón de tokens de salida, con 2 peticiones por segundo.

Cada plan incluye 5 $ de crédito al mes, pero no existe un plan gratuito: necesitas tarjeta para activar cualquiera, y las cuentas nuevas funcionan en prepago. Cuando el saldo llega a 0 $, Brave rechaza las peticiones hasta que recargas. Son las cifras de la página de precios de Brave Search API a 21 de octubre de 2026.

La regla para elegir es una sola pregunta: ¿quién escribe la respuesta final? Si la escribe tu código o tu propio modelo, empieza en Search (/web/search, /llm/context o /local/place_search). Si quieres que la escriba Brave, empieza en Answers (/chat/completions).

Qué se ejecutó y qué no: el 21 de octubre de 2026 se lanzaron con curl peticiones sin clave y con una clave inválida contra los cuatro endpoints, y sus respuestas reales aparecen en la sección de errores 422. No se hizo ninguna petición con una clave válida, de modo que los ejemplos de código siguen la documentación oficial de Brave y no tienen una ejecución con éxito comprobada.

Search vs Answers: qué endpoint llamar primero y cuánto cuesta cada llamada

El plan Search incluye Web Search, LLM Context, noticias, imágenes, vídeo y Place Search; Answers es un plan aparte con su propia clave. La tabla resume cuándo empieza cada uno y qué cuesta una llamada con los precios publicados:

El coste de Search sale de dividir 5 $ entre 1.000 peticiones. Con los 5 $ mensuales cubres unas 1.000 llamadas al mes, la misma equivalencia que da la FAQ del panel de Brave Search API. Según la guía de límites de peticiones, solo se cobran las respuestas sin error.

Answers no tiene un precio fijo por llamada. La documentación de Answers da la fórmula y un ejemplo: búsquedas × 4 $/1.000 + tokens de entrada × 5 $/1.000.000 + tokens de salida × 5 $/1.000.000. Una respuesta con 2 búsquedas, 1.234 tokens de entrada y 300 de salida cuesta 0,008 $ + 0,00617 $ + 0,0015 $ = 0,01567 $. A ese ritmo, los 5 $ del plan Answers dan para unas 319 respuestas al mes, frente a las 1.000 llamadas de Search. Si tu aplicación ya tiene un modelo que redacta, pagar Answers es pagar dos veces por la misma capa.

Tres matices cambian la elección:

• LLM Context frente a Web Search. Los dos cuestan lo mismo, pero LLM Context devuelve fragmentos extraídos y agrupados por URL (grounding.generic con url, title y snippets), pensados para meterlos en un prompt. Web Search devuelve la lista clásica de resultados. Si el siguiente paso es un modelo, LLM Context te ahorra el trabajo de limpiar páginas.
• Place Search cuando el objeto es un lugar. Según la documentación de Place Search, trabaja sobre un índice de más de 200 millones de lugares y se ancla con latitud y longitud o con un texto tipo madrid spain. Forzar «cafeterías cerca de Sol» por Web Search te da páginas, no lugares.
• Summarizer ya no figura en la documentación actual. Si un tutorial antiguo lo usa, la respuesta redactada se pide hoy al plan Answers.

¿Es gratis Brave Search API? 5 $ al mes por plan, con tarjeta y prepago

No es gratis en el sentido de «sin tarjeta y sin límite de gasto», pero puedes usarla sin pagar nada si te quedas dentro del crédito mensual. Estos son los planes de autoservicio a 21 de octubre de 2026:

Si activas los cuatro planes, el crédito gratuito suma hasta 20 $ al mes. El crédito mensual no se acumula: cada mes se sustituye por otros 5 $. El plan Enterprise no tiene precio público y es el que ofrece retención de datos cero en toda la cadena.

Cómo usar solo los 5 $ sin que te cobren

1. Al activar el plan, introduce la tarjeta y deja la cantidad de prepago en 0 $. Brave hace una retención de 0 $ o 1 $ para comprobar la tarjeta y la devuelve al momento.
2. En Usage limits, revisa el límite de uso. Según la FAQ, el límite efectivo es la cantidad que introduces más los 5 $ gratuitos; si introduces 0 $, tu techo son esos 5 $.
3. No actives la recarga automática si no quieres gastar. Si la activas, rellena también el límite mensual de recarga: si lo dejas vacío, la recarga no tiene tope.

Si la tarjeta se rechaza, la FAQ apunta a tres causas: la autorización mínima es de 1 $, algunas tarjetas bloquean cargos internacionales o recurrentes, o conviene probar otra Visa o Mastercard. El listado de Brave Search API en AWS Marketplace admite otros medios de pago, pero solo para planes de pago.

Qué pasa cuando el saldo prepago llega a 0 $

Cuando gastas el crédito mensual, el consumo pasa a descontarse de tu saldo prepago. Al llegar a 0 $, el servicio se pausa y las peticiones se rechazan hasta que añades fondos. La FAQ no especifica qué código HTTP ni qué cuerpo devuelve la API en ese caso, así que tu código debe tratar cualquier error de facturación como «servicio parado», no como fallo transitorio que se arregla reintentando.

Otras reglas del prepago que conviene saber antes de recargar:

• Recarga automática. Defines un umbral («When balance drops below») y una cantidad fija («Amount to add»), con un mínimo de 5 $. Por ejemplo: cuando baje de 30 $, añadir 50 $.
• Sin reembolso ni caducidad. Los créditos que compras no caducan, pero tampoco se devuelven si no los usas.
• Hasta dos minutos de espera. El saldo recién comprado puede tardar ese tiempo en aparecer; no lances una prueba de carga justo después de recargar.
• Las cuentas antiguas pueden ir en pospago. Los planes de pospago anteriores al cambio siguen igual y cobran el exceso por uso, por eso hay tutoriales que hablan de «pagar solo lo que usas» sin saldo previo. Si cancelas un plan de pospago, ya no puedes reactivarlo: solo te queda el prepago. Las cuentas creadas antes del cambio que nunca activaron un plan también entran directamente en prepago.

Cómo obtener la clave de Brave Search API

El Quickstart de Brave Search API reduce el alta a tres pasos en el panel api-dashboard.search.brave.com:

1. Crea la cuenta con correo y contraseña y verifica el correo. Crear la cuenta es gratis.
2. Activa un plan en la página de planes e introduce la tarjeta. El plan Search ya incluye Web Search y LLM Context.
3. Crea la clave en API Keys → Add API Key, ponle un nombre y cópiala.

Cada plan necesita su propia clave, y puedes tener hasta 10 claves por plan. Si vas a usar Search y Answers, activa los dos planes y genera una clave en cada uno. Todas las peticiones llevan la clave en la cabecera X-Subscription-Token. Guárdala en una variable de entorno o en un gestor de secretos: nunca en el código del navegador, en una app móvil ni en el repositorio.

Primera petición a Web Search, LLM Context y Place Search

Con la clave en BRAVE_API_KEY, este ejemplo en JavaScript (Node 18 o superior, guardado como .mjs para poder usar await fuera de una función) pide diez resultados web y muestra el código de error si algo falla. Los parámetros son los de la documentación de Web Search: q, count, country, search_lang y extra_snippets.

const params = new URLSearchParams({
  q: "base de datos vectorial open source búsqueda híbrida",
  count: "10",
  country: "ES",
  search_lang: "es",
  extra_snippets: "true",
});

const res = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
  headers: {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": process.env.BRAVE_API_KEY,
  },
});

if (!res.ok) {
  const body = await res.json().catch(() => ({}));
  throw new Error(`${res.status} ${body.error?.code ?? ""}: ${body.error?.detail ?? ""}`);
}

const data = await res.json();
console.log(data.web?.results?.[0]);
console.log("¿Hay más páginas?", data.query?.more_results_available);
console.log("Restantes:", res.headers.get("x-ratelimit-remaining"));

Tres detalles de Web Search que ahorran llamadas: extra_snippets=true puede añadir hasta cinco fragmentos más por resultado; los operadores de búsqueda van dentro de q, no en campos aparte; y query.more_results_available te dice si merece la pena pedir la página siguiente, porque la paginación no es infinita.

Para alimentar un modelo, la misma clave sirve en LLM Context. Según la documentación de LLM Context, maximum_number_of_tokens controla cuánto contexto entra en tu prompt (8.192 por defecto, entre 1.024 y 32.768) y count cuántos resultados se consideran (20 por defecto, hasta 50). Para una pregunta factual sencilla, la propia documentación propone 5 resultados y 2.048 tokens:

curl -s --compressed \
  "https://api.search.brave.com/res/v1/llm/context?q=precio+brave+search+api&count=5&maximum_number_of_tokens=2048" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

La respuesta trae grounding.generic (una lista de objetos con url, title y snippets) y sources, con título, dominio y antigüedad de cada URL. Para preguntas de investigación complejas, la guía sube a 50 resultados y 16.384 tokens; ese ajuste multiplica el coste en tokens de tu modelo, no el de Brave, que sigue cobrando una petición.

Place Search acepta un texto de ubicación con el formato «ciudad país» y una consulta opcional:

curl -s --compressed \
  "https://api.search.brave.com/res/v1/local/place_search?q=museos&location=madrid+spain" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

Los detalles de cada lugar se piden después a /res/v1/local/pois y /res/v1/local/descriptions, con hasta 20 identificadores por petición. Esos identificadores caducan a las 8 horas aproximadamente: no los guardes en tu base de datos.

Answers con el SDK de OpenAI: las citas exigen streaming

Answers usa el endpoint https://api.search.brave.com/res/v1/chat/completions con model="brave", así que basta con cambiar base_url y la clave en el cliente de OpenAI. Las peticiones sin streaming funcionan, pero las citas (enable_citations) y el modo research (enable_research) solo funcionan con stream=True:

import asyncio
import os

from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key=os.environ["BRAVE_ANSWERS_API_KEY"],  # clave del plan Answers, no la de Search
    base_url="https://api.search.brave.com/res/v1",
)

async def main():
    stream = await client.chat.completions.create(
        model="brave",
        stream=True,
        messages=[{"role": "user", "content": "¿Qué diferencia hay entre Brave Search API y Answers?"}],
        extra_body={
            "enable_citations": True,
            "enable_research": False,
        },
    )
    async for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)

asyncio.run(main())

country y language también van en extra_body; si no los pasas, valen us y en. En streaming, el texto llega mezclado con etiquetas que tu interfaz tiene que interpretar: <citation>…</citation> con cada fuente y, como último mensaje, <usage>…</usage> con el consumo. En las peticiones sin streaming, ese consumo llega en las cabeceras de la respuesta. Guarda el usage de cada respuesta: es lo único que te permite comprobar la factura con la fórmula de la primera sección.

El modo research no es «el mismo pero mejor». En modo normal, una respuesta suele empezar a llegar en menos de 4,5 segundos; con enable_research: true lanza varias búsquedas y puede tardar minutos (la documentación cita un caso p99 de 53 consultas, 1.000 páginas y unos 300 segundos). Cada búsqueda extra suma 0,004 $ y más tokens. Úsalo para tareas en segundo plano, no detrás de un cuadro de chat. Brave comprueba tus límites antes de responder: una pregunta que ya ha empezado se responde entera y se cobra hasta tu límite.

Error 422 en Brave Search API: VALIDATION y SUBSCRIPTION_TOKEN_INVALID

Cuando falla la autenticación, Brave no devuelve 401, sino 422. Estas son las respuestas obtenidas el 21 de octubre de 2026 con curl en macOS.

Sin cabecera X-Subscription-Token, la API responde HTTP/2 422 con código VALIDATION:

{"error":{"code":"VALIDATION","detail":"Unable to validate request parameter(s)","meta":{"errors":[{"input":null,"loc":["header","x-subscription-token"],"msg":"Field required","type":"missing"}]},"status":422},"type":"ErrorResponse"}

Con una clave inventada (X-Subscription-Token: invalid-key-test), la respuesta es otro 422, ahora con SUBSCRIPTION_TOKEN_INVALID:

{"error":{"code":"SUBSCRIPTION_TOKEN_INVALID","detail":"The provided subscription token is invalid.","meta":{"component":"authentication"},"status":422},"type":"ErrorResponse"}

El mismo SUBSCRIPTION_TOKEN_INVALID apareció en /web/search, /llm/context, /chat/completions (con POST) y /local/place_search, e incluso en una ruta inexistente. Eso tiene una consecuencia práctica: la clave se comprueba antes de mirar la ruta, así que un 422 de autenticación no te dice nada sobre si la URL está bien escrita. Arregla primero la clave y después revisa la ruta.

Cómo leer cada caso:

• VALIDATION con loc: ["header","x-subscription-token"]. La cabecera no llega. Suele ser una variable de entorno vacía o un proxy que elimina cabeceras personalizadas.
• SUBSCRIPTION_TOKEN_INVALID. La cabecera llega, pero la clave no vale: está mal copiada, se revocó o es de otro plan. Una clave del plan Search no sirve para Answers.
• Si tu código solo comprueba status === 401, nunca detectará estos fallos. Comprueba res.ok y registra error.code, como en el ejemplo de JavaScript.

Qué rompe la primera semana: 429, saldo a 0 $, datos guardados y esperas

Ninguno de estos fallos se observó en las pruebas anteriores (sin clave válida no se puede llegar a ellos); todos salen de la documentación de Brave. Repásalos antes de poner la integración en producción:

• 429 por exceso de velocidad. El límite se mide en una ventana deslizante de 1 segundo: 50 peticiones por segundo en Search y 2 en Answers. Lee las cabeceras X-RateLimit-Limit, X-RateLimit-Policy, X-RateLimit-Remaining y X-RateLimit-Reset. En el ejemplo de la documentación, X-RateLimit-Policy: 1;w=1, 15000;w=2592000 describe dos ventanas: 1 petición por segundo y 15.000 por mes (2.592.000 segundos). La petición cuenta en cuanto llega, así que reintentar en bucle empeora el 429. Aplica espera exponencial y respeta X-RateLimit-Reset.
• Saldo prepago a 0 $. El servicio se pausa, y la documentación no dice con qué código responde la API en ese caso. Fija un límite de uso en el panel y vigila el consumo con las cabeceras y el usage de Answers.
• Guardar resultados está prohibido. La FAQ dice que está prohibido retener cualquier dato recibido a través de la API. Para almacenar resultados o entrenar un modelo hay que escribir a searchapi-support@brave.com y llegar a un acuerdo. Una caché persistente de resultados en tu base de datos entra en esa prohibición.
• LLM Context lento o vacío. La documentación recomienda un timeout de 30 segundos y tratar el caso de grounding.generic vacío. Si una consulta pasa de 600 caracteres o 75 palabras, recórtala.
• Cambio de extracción en LLM Context. Desde el 31 de julio de 2026, LLM Context usa por defecto un nuevo sistema de extracción de contenido. Si tus prompts dependían del formato anterior, fija la cabecera Api-Version: 2026-02-06.
• Modo research por defecto. Respuestas de minutos y varias búsquedas cobradas por pregunta. Actívalo solo donde el usuario no esté esperando delante de la pantalla.

Migrar desde la API JSON de Google Custom Search antes del 1 de enero de 2027

Según la página de Custom Search JSON API de Google, la API ya no admite clientes nuevos y los actuales deben migrar antes del 1 de enero de 2027, fecha en que deja de funcionar. Hasta entonces ofrece 100 consultas gratis al día y cobra 5 $ por cada 1.000 adicionales, con un máximo de 10.000 al día.

La cuota gratuita cambia de escala: 100 consultas diarias son unas 3.000 en un mes de 30 días, frente a unas 1.000 con el crédito de Brave. Si tu proyecto vivía de la cuota gratuita de Google, calcula el consumo real antes de migrar. Por encima de la cuota gratuita, los dos cobran lo mismo: 5 $ por cada 1.000 peticiones.

Brave explica su propuesta de migración en el artículo «Alternativas al API de Google Search: tus opciones antes del cierre de 2027», del 14 de agosto de 2026. Ten en cuenta que ese texto lo publica un proveedor que compite por esos mismos clientes.

En qué se diferencia Brave Search API de un buscador genérico

Brave Search API funciona sobre un índice propio, no sobre resultados de Google o Bing. Sobre su tamaño, Brave da dos cifras: la web en español de la API del Buscador de Brave habla de más de 30.000 millones de páginas y más de 100 millones de actualizaciones diarias, y su artículo de agosto de 2026 sobre el cierre de Google eleva el índice a más de 40.000 millones de páginas. Ninguna de las dos cifras se puede comprobar desde fuera.

Lo que sí se nota al integrar son los controles: Goggles para reordenar y filtrar dominios, hasta cinco fragmentos adicionales por resultado, resultados enriquecidos y la opción de pedir resultados, contexto para un modelo o una respuesta terminada con la misma cuenta. Para compras con requisitos de cumplimiento, Brave anuncia certificación SOC 2 Tipo II, y el plan Enterprise ofrece retención de datos cero.

También es una pieza habitual en agentes. OpenClaw, por ejemplo, la usa como herramienta de búsqueda web: eliges el plan Search, generas la clave y la guardas en su configuración o como BRAVE_API_KEY en el entorno del gateway; la guía completa de OpenClaw cubre la configuración de modelos y costes. Para Claude Code y otros clientes MCP existe un servidor MCP de Brave Search. Si es tu primer servidor MCP, los mejores MCP para Claude Code explican cuál instalar primero y cómo comprobar que funciona. En los dos casos, cada búsqueda que lanza el agente consume peticiones de tu plan Search como cualquier otra llamada.

Preguntas frecuentes sobre Brave Search API

¿Se puede usar Brave Search API sin tarjeta de crédito?

No. Brave pide tarjeta para activar cualquier plan, incluido el uso que se queda dentro de los 5 $ mensuales; la presenta como medida contra el fraude. Si dejas el prepago en 0 $, solo hace una retención de 0 $ o 1 $ que devuelve al momento.

¿Brave Search API ya no es gratuita?

Ya no hay un plan gratuito independiente. Lo que queda son 5 $ de crédito al mes en cada plan (unas 1.000 peticiones de Search) y hasta 20 $ si activas los cuatro planes. Más allá de ese crédito, pagas con saldo prepago.

¿Por qué mi Brave Search API dejó de responder de repente?

Lo más probable es que hayas agotado el crédito mensual y tengas el saldo prepago a 0 $: en ese caso el servicio se pausa hasta que recargas. Si recibes 429, el problema es la velocidad (más de 50 peticiones por segundo en Search o 2 en Answers). Si recibes 422 con SUBSCRIPTION_TOKEN_INVALID, o con VALIDATION sobre la cabecera x-subscription-token, el problema es la clave.

¿Puedo guardar los resultados de Brave Search API en mi base de datos?

No con un plan de autoservicio. La FAQ prohíbe retener cualquier dato recibido a través de la API; para almacenar resultados o entrenar un modelo necesitas un acuerdo con Brave a través de searchapi-support@brave.com. Los identificadores de Place Search, además, caducan a las 8 horas aproximadamente.

¿Cuánto cuesta una respuesta de Brave Answers?

Depende de las búsquedas y los tokens: 4 $ por cada 1.000 búsquedas más 5 $ por millón de tokens de entrada y 5 $ por millón de salida. El ejemplo oficial, con 2 búsquedas, 1.234 tokens de entrada y 300 de salida, cuesta 0,01567 $. El modo research multiplica las búsquedas, así que el coste por respuesta sube.