> ## 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.

# Brave 검색 결과 API

> 한 검색어에 대해 Brave 자체 인덱스의 자연 검색 결과, 광고, FAQ, 지식 패널, 뉴스, 동영상, 토론, 장소, 관련 검색어를 받습니다.

`BRAVE_SEARCH`는 Brave의 결과 페이지를 검색어 하나로 열어 자연 검색 결과, 광고, FAQ, 지식 패널, 뉴스, 동영상, 토론, 장소, 관련 검색어를 받습니다. Brave가 자체 인덱스로 답하고 페이지를 서버에서 그리므로 결과가 페이지와 함께 오고 브라우저는 돌지 않습니다.

| | |
| - | - |
| `taskType` | `BRAVE_SEARCH` |
| 입력 | `query` 또는 `prompt`(필수), 600자·75단어 이하; `country`, `lang`, `safesearch`, `freshness`, `page` |
| 크레딧 | 태스크당 0.3 |
| 국가 | 기본값 `US`. 아래 Brave의 시장. |
| 위치 | 지원하지 않습니다(`422 LOCATION_UNSUPPORTED`). |

## 요청

```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": "히트펌프는 추운 날씨에 어떻게 작동하나", "country": "KR" } }'
```

태스크는 비동기로 실행됩니다. 결과는 [비동기 태스크](https://docs.querying.ai/ko/concepts/async-tasks.md)대로 읽습니다.

## 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| `query` | 예, 또는 `prompt` | 검색어, 600자·75단어 이하. |
| `prompt` | 예, 또는 `query` | `query`가 없을 때 받습니다. 둘 다 보내면 `BRAVE_SEARCH`는 `query`를 읽습니다. |
| `country` | 아니요 | 검색할 시장입니다. `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` 중 하나이거나 `ALL`입니다. 기본값은 `US`이고 `ALL`은 모든 시장을 검색합니다. |
| `lang` | 아니요 | 결과 언어입니다. `en`, `ko`, `ja`, `de`, `pt-br`, `zh-hant` 같은 Brave의 코드입니다. 기본값은 국가의 언어입니다. |
| `safesearch` | 아니요 | `off`, `moderate`(기본), `strict`. |
| `freshness` | 아니요 | `pd`(지난 하루), `pw`(지난주), `pm`(지난달), `py`(지난해), 또는 `YYYY-MM-DDtoYYYY-MM-DD` 범위. |
| `page` | 아니요 | 결과 페이지, 1\~10. 페이지마다 결과 20개까지이고 Brave가 조금씩 넘기므로 옆 페이지와 겹칩니다. |

## 응답

페이지에 있는 묶음만 싣고 없는 묶음은 뺍니다.

```json theme={"theme":"css-variables"}
{
  "organicResults": [
    { "position": 1, "title": "...", "link": "https://...", "snippet": "...", "date": "3 days ago", "siteName": "..." }
  ],
  "ads": [{ "position": 1, "title": "...", "link": "https://...", "description": "...", "displayedLink": "..." }],
  "peopleAlsoAsk": [{ "question": "...", "snippet": "...", "link": "https://..." }],
  "knowledgeGraph": { "title": "...", "description": "...", "attributes": [{ "key": "...", "value": "..." }], "profiles": ["https://..."] },
  "topStories": [{ "title": "...", "link": "https://...", "source": "...", "date": "2 days ago", "snippet": "..." }],
  "videoResults": [{ "title": "...", "link": "https://...", "source": "...", "duration": "1:02", "date": "2026년 6월 16일" }],
  "discussions": [{ "position": 1, "title": "...", "link": "https://...", "source": "...", "snippet": "..." }],
  "locations": [{ "position": 1, "title": "...", "link": "https://...", "address": "...", "coordinates": { "latitude": 37.5, "longitude": 127 } }],
  "relatedSearches": [{ "query": "...", "link": "https://..." }],
  "moreResultsAvailable": true,
  "page": 1
}
```

| 필드 | 설명 |
| - | - |
| `organicResults` | 항상 있습니다. `position`은 페이지마다 1부터 셉니다. `snippet`은 Brave의 설명이고 마크업을 그대로 둡니다. `date`는 페이지가 발췌 앞에 날짜를 찍을 때 그 표현 그대로입니다. `siteName`은 발행자 이름입니다. |
| `ads` | 광고입니다. 광고주의 착지 `link`와 표시되는 `displayedLink`. Brave는 자연 결과 사이에 넣으므로 `position`이 그 순서입니다. |
| `peopleAlsoAsk` | Brave의 FAQ 묶음입니다. `question`, 답변을 담은 `snippet`, 답변의 출처 페이지. |
| `knowledgeGraph` | 지식 패널입니다. 제목, 설명, `attributes`의 사실, `profiles`의 공식 페이지. |
| `topStories` | 뉴스 결과. `date`는 Brave의 표현("2 days ago")입니다. |
| `videoResults` | 동영상입니다. `source`, `duration`, `date`. |
| `discussions` | 포럼 글입니다. 글의 `snippet`과 `source`. |
| `locations` | 위치 질의의 장소입니다. `address`, `coordinates`, `phoneNumber`, `openingHours`, 제공처 `link`. |
| `relatedSearches` | Brave의 관련 검색어와 각 검색어를 실행하는 `link`. |
| `moreResultsAvailable` | 다음 페이지가 있으면 `true`. |
| `page` | 반환한 페이지. |

HTML payload는 없어 `include`가 더할 것이 없습니다.

## 한도와 오류

* 600자·75단어를 넘는 검색어는 제출할 때 `422 VALIDATION_ERROR`입니다.
* 위 목록 밖의 `country`, 모르는 `lang`, 세 값 밖의 `safesearch`, 형식이 틀린 `freshness`, 1\~10 밖의 `page`는 `422 VALIDATION_ERROR`입니다.
* Brave가 속도를 제한하면 다른 주소로 재시도한 뒤 `BRAVE_HTTP_429`로 답합니다. `BRAVE_UNEXPECTED_PAGE`는 이 엔진이 읽지 않는 페이지로 답했다는 뜻이고, `BRAVE_TIMEOUT`은 제때 답하지 않았다는 뜻입니다.
* 그 밖의 요청 오류는 [오류](https://docs.querying.ai/ko/concepts/errors.md)에 있습니다.

## 관련

* Bing 결과 페이지와 AI 요약은 [Bing 검색](https://docs.querying.ai/ko/engines/bing-search.md)
* 결과 하나의 페이지 전체를 읽으려면 [Scrape](https://docs.querying.ai/ko/engines/web-scrape.md)


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