> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de résultats Brave Search

> Renvoie, pour une requête, des résultats organiques de l’index propre à Brave, une FAQ, un panneau de connaissance, des actualités, des vidéos, des discussions et des lieux.

`BRAVE_SEARCH` ouvre la page de résultats de Brave pour une requête et renvoie des résultats organiques, des annonces, une FAQ, le panneau de connaissance, des actualités, des vidéos, des discussions, des lieux et des requêtes associées. Brave répond depuis son propre index et rend la page côté serveur : les résultats arrivent avec la page, sans navigateur.

| | |
| - | - |
| `taskType` | `BRAVE_SEARCH` |
| Entrée | `query` ou `prompt` (obligatoire), 600 caractères et 75 mots au plus ; `country`, `lang`, `safesearch`, `freshness`, `page` |
| Crédits | 0.3 par tâche |
| Pays | Valeur par défaut `US`. Les marchés de Brave sont ci-dessous. |
| Localisation | Non pris en charge (`422 LOCATION_UNSUPPORTED`). |

## Requête

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "BRAVE_SEARCH", "payload": { "query": "comment fonctionne une pompe à chaleur par temps froid", "country": "FR" } }'
```

La tâche s’exécute de façon asynchrone. Lisez le résultat comme décrit dans [Tâches asynchrones](https://docs.querying.ai/fr/concepts/async-tasks.md).

## Paramètres

| Champ | Obligatoire | Description |
| - | - | - |
| `query` | Oui, ou `prompt` | La requête, 600 caractères et 75 mots au plus. |
| `prompt` | Oui, ou `query` | Accepté quand `query` manque. Si les deux sont envoyés, `BRAVE_SEARCH` lit `query`. |
| `country` | Non | Le marché à interroger : `AR`, `AU`, `AT`, `BE`, `BR`, `CA`, `CL`, `DK`, `FI`, `FR`, `DE`, `GR`, `HK`, `IN`, `ID`, `IT`, `JP`, `KR`, `MY`, `MX`, `NL`, `NZ`, `NO`, `CN`, `PL`, `PT`, `PH`, `RU`, `SA`, `ZA`, `ES`, `SE`, `CH`, `TW`, `TR`, `GB`, `US` ou `ALL`. Par défaut `US` ; `ALL` interroge tous les marchés. |
| `lang` | Non | La langue des résultats, un code Brave comme `en`, `ko`, `ja`, `de`, `pt-br` ou `zh-hant`. Par défaut, la langue du pays. |
| `safesearch` | Non | `off`, `moderate` (par défaut) ou `strict`. |
| `freshness` | Non | `pd` (dernier jour), `pw` (dernière semaine), `pm` (dernier mois), `py` (dernière année), ou une plage `YYYY-MM-DDtoYYYY-MM-DD`. |
| `page` | Non | Page de résultats, 1 à 10. Chaque page porte jusqu’à 20 résultats et Brave avance par petits pas, donc les pages voisines se chevauchent. |

## Réponse

Chaque bloc porté par la réponse est inclus ; un bloc absent est omis.

```json theme={"theme":"css-variables"}
{
  "organicResults": [
    { "position": 1, "title": "...", "link": "https://...", "snippet": "...", "date": "2026-11-13T04:00:00.000Z", "siteName": "...", "extraSnippets": ["..."] }
  ],
  "ads": [{ "position": 1, "title": "...", "link": "https://...", "description": "...", "displayedLink": "..." }],
  "peopleAlsoAsk": [{ "question": "...", "snippet": "...", "link": "https://..." }],
  "knowledgeGraph": { "title": "...", "type": "...", "description": "...", "attributes": [{ "key": "...", "value": "..." }], "profiles": ["https://..."] },
  "topStories": [{ "title": "...", "link": "https://...", "source": "...", "date": "2 days ago", "snippet": "..." }],
  "videoResults": [{ "title": "...", "link": "https://...", "platform": "...", "duration": "1:02", "views": 1234 }],
  "discussions": [{ "position": 1, "title": "...", "link": "https://...", "source": "...", "question": "...", "topComment": "..." }],
  "locations": [{ "position": 1, "title": "...", "link": "https://...", "address": "...", "coordinates": { "latitude": 37.5, "longitude": 127 } }],
  "alteredQuery": "...",
  "relatedSearches": [{ "query": "...", "link": "https://..." }],
  "moreResultsAvailable": true,
  "page": 1
}
```

| Champ | Description |
| - | - |
| `organicResults` | Toujours présent. `position` compte à partir de 1 sur chaque page. `snippet` est la description de Brave, balisage conservé. `date` reprend la date que la page imprime devant l’extrait. `siteName` est le nom de l’éditeur. |
| `ads` | Annonces, avec le `link` de destination de l’annonceur et le `displayedLink` affiché. Brave les place parmi les résultats organiques, ce qui garde leur `position`. |
| `peopleAlsoAsk` | Le bloc FAQ de Brave : `question`, la réponse en `snippet` et la page d’origine. |
| `knowledgeGraph` | Le panneau de connaissance : titre, catégorie, description, les faits de l’entité dans `attributes` et ses `profiles` (pages officielles). |
| `topStories` | Actualités. `date` reprend les mots de Brave (« 2 days ago »). |
| `videoResults` | Vidéos, avec `platform`, `channel`, `duration` et `views`. |
| `discussions` | Fils de forum, avec la `question` du fil et son `topComment` quand Brave les porte. |
| `locations` | Lieux d’une requête locale : `address`, `coordinates`, `phoneNumber`, `openingHours` et le `link` du fournisseur. |
| `alteredQuery` | Présent quand le correcteur de Brave a changé la requête avant la recherche. |
| `relatedSearches` | Les requêtes associées de Brave, avec le `link` qui lance chacune. |
| `moreResultsAvailable` | `true` quand des résultats existent au-delà de cette page. |
| `page` | La page renvoyée. |

Pas de payload HTML, donc `include` n’ajoute rien.

Les conditions de l’API Brave limitent la conservation des résultats de l’API au-delà de ce qu’exige l’exploitation d’une app. La page est désormais lue, la portée diffère, et la réponse de Brave est nécessaire avant de les conserver.

## Limites et erreurs

* Une requête de plus de 600 caractères ou 75 mots renvoie `422 VALIDATION_ERROR` à l’envoi.
* Un `country` hors liste, un `lang` inconnu, un `safesearch` hors des trois valeurs, un `freshness` mal formé ou une `page` hors de 1 à 10 renvoient `422 VALIDATION_ERROR`.
* Une requête limitée par Brave répond `BRAVE_HTTP_429` après une nouvelle tentative sur une autre adresse. `BRAVE_UNEXPECTED_PAGE` signifie que Brave a répondu par une page que ce moteur ne lit pas, `BRAVE_TIMEOUT` qu’il n’a pas répondu à temps.
* Les autres erreurs de requête sont dans [Erreurs](https://docs.querying.ai/fr/concepts/errors.md).

## Voir aussi

* [Bing Search](https://docs.querying.ai/fr/engines/bing-search.md) pour la page de résultats de Bing et son résumé IA
* [Scrape](https://docs.querying.ai/fr/engines/web-scrape.md) pour lire la page entière d’un résultat


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.