Grok Search API 사용법: 웹 검색·출처 인용·비용 확인

Grok API에 웹 검색을 붙이려면 xAI Responses API 요청의 tools에 web_search를 넣는다. 모델이 실시간으로 웹을 검색하고 페이지를 읽어 답한다. 응답에서는 검색 호출 상태와 인용 링크를 함께 확인한다. 비용은 성공한 검색 1,000회당 5달러이고, 모델 토큰 비용은 따로 든다.

언제 검색을 붙이나

모든 요청에 붙이지 말고 최신 정보가 필요한 질문에만 쓴다. 검색은 도구 호출과 네트워크 시간이 더 들어 느리고 비싸다.

질문 종류	검색
번역, 문장 다듬기, 주어진 문서 요약	필요 없음
오늘 가격, 최신 버전, 새 보안 공지, 현재 담당자	필요
회사 내부 문서 질문	웹 검색보다 승인된 내부 검색 도구

기본 요청

python -m pip install openai로 SDK를 설치하고, API 키는 환경 변수 XAI_API_KEY에 넣는다. 키 만들기와 첫 호출은 Grok API 시작 가이드에 있다. (Web Search 문서)

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")

response = client.responses.create(
    model="grok-4.7",
    input="Python 공식 문서에서 현재 안정 버전과 릴리스 날짜를 찾아 출처를 붙여줘. 못 찾으면 확인 불가로 적어줘.",
    tools=[{"type": "web_search"}],
)

print(response.status, response.output_text)
for item in response.output:
    if item.type == "web_search_call":
        print("search status:", item.status)
    if item.type == "message":
        for content in item.content:
            for a in getattr(content, "annotations", []):
                if a.type == "url_citation":
                    print(a.title, a.url, a.start_index, a.end_index)

tools에 넣으면 모델이 검색을 쓸 수 있게 될 뿐이다. 실제로 검색했는지는 output에 web_search_call이 있는지와 그 status로 본다. 최신 정보가 꼭 필요한 질문인데 성공한 검색이 없으면, 모델이 기억으로 답한 것일 수 있으니 그대로 쓰지 않는다.

기존 Chat Completions 예제와 Responses API 예제는 응답 구조가 다르다. 둘을 섞어 쓰면 필드를 찾지 못해 오류가 난다.

인용 확인

• 인라인 인용(url_citation): 답의 특정 문장에 연결된 출처다. 위치(start_index, end_index)가 함께 온다. 문장별 근거는 이것으로 본다.
• 전체 출처 목록(xAI SDK의 response.citations): 검색 과정에서 만난 출처 URL 목록이다. 답에 쓰지 않은 주소도 들어 있어, 목록에 있다고 특정 문장의 근거로 연결하면 안 된다.

인라인 인용 기본값은 SDK마다 다르다. (인용 문서)

	Responses API(OpenAI SDK·cURL)	xAI Python SDK
기본값	켜짐	꺼짐
바꾸는 법	끄려면 include=["no_inline_citations"]	켜려면 include=["inline_citations"]
출처 확인	메시지의 annotations에서 인라인 인용 확인	response.citations에서 전체 URL 확인

인용이 붙어 있어도 내용은 직접 대조한다. 예를 들어 “최신 버전에서 지원한다”는 답이면 릴리스 노트의 기능명과 버전을, “무료로 쓸 수 있다”면 요금제와 사용량 조건을, “오늘부터 모두에게 열린다”면 배포 일정과 지역을 본다. 같은 발표를 옮긴 사이트 두 곳은 독립된 근거 두 개가 아니다.

비용

9월 29일 xAI 가격표 기준이다.

도구	가격
Web Search	성공한 호출 1,000회당 $5
X 게시물 검색	1,000건당 $5
X 프로필 검색	1,000건당 $10

삭제된 페이지나 접근 제한처럼 실패한 호출에는 도구 요금이 붙지 않는다. xAI SDK의 server_side_tool_usage에는 성공한 호출만 집계되고, 이 숫자가 호출별 과금 도구의 청구 기준이다. X 검색은 호출 수 대신 가져온 게시물·프로필 수로 과금한다. 모델 토큰 비용은 별도다. (도구 사용량)

에이전트가 검색을 여러 번 반복하는 구성이면 xAI SDK의 max_turns로 턴 수를 제한한다. 한 턴에 도구가 여러 번 불릴 수 있으니 호출 수 자체를 막는 설정은 아니다. 빠른 조회는 적은 턴, 깊은 조사는 많은 턴으로 둔다.

검색 범위 지정

옵션	하는 일	제한
allowed_domains	지정한 도메인 안에서만 검색	최대 5개
excluded_domains	지정한 도메인 제외	최대 5개
enable_image_understanding	검색 중 만난 이미지 분석	view_image 호출이 따로 집계된다
enable_image_search	이미지 검색 결과 허용	-

허용과 제외 목록은 한 요청에 같이 쓸 수 없다. 특정 회사 문서만 봐야 하는 질문은 허용 도메인을 좁히면 엉뚱한 페이지가 근거로 들어오는 일이 준다. 넣는 위치는 SDK마다 다르다.

# xAI SDK
tools=[web_search(allowed_domains=["example.com"])]

# OpenAI 호환 Responses API: 도메인 옵션은 filters 안에
tools=[{"type": "web_search", "filters": {"allowed_domains": ["example.com"]}}]

enable_image_understanding은 OpenAI 호환 방식에서도 filters 밖에 둔다. 도메인 두 옵션만 filters 안에 들어간다.

검색 결과를 믿을 만하게 받는 요청

요청문에 출처의 종류, 확인할 날짜, 못 찾았을 때의 처리를 적으면 엉뚱한 페이지를 근거로 삼는 일이 준다.

제조사 공식 문서와 릴리스 노트만 근거로 삼아 줘. 각 사실 옆에 출처 URL과 그 페이지의 날짜를 적고, 공식 출처에서 찾지 못한 항목은 추측하지 말고 확인 불가로 표시해 줘.

검색 엔진이 지금 찾은 페이지라도 내용은 오래됐을 수 있다. 답을 저장할 때 인용 URL, 확인한 시각, 주장이 나온 위치를 함께 남기면 나중에 페이지가 바뀌어도 당시 판단을 되짚을 수 있다.

자주 묻는 질문

X 검색과 웹 검색은 무엇이 다른가? 웹 검색(web_search)은 일반 웹페이지를 찾고, X 검색(x_search)은 X의 게시물·사용자·스레드를 찾는다. 공식 발표나 가격 확인에는 웹 검색이 맞고, 출시 직후 반응처럼 X 게시물 자체가 필요할 때만 X 검색을 쓴다. 둘은 요금도 따로 계산된다.

검색을 켜니 응답이 느리다면? 검색이 필요 없는 요청에서는 도구를 뺀다. 허용 도메인은 출처를 한정하는 옵션이며 속도 개선을 보장하지는 않는다. 에이전트 구성이라면 조사 범위를 고려해 max_turns를 줄인다.

같은 질문의 답을 저장해 두고 써도 되나? 된다. 다만 가격처럼 자주 바뀌는 답과 개념 설명을 같은 기간 동안 저장하지 않는다. 저장한 답에는 확인한 날짜와 출처를 함께 남긴다.

검색한 페이지에 이상한 지시문이 있으면? “이전 지시를 무시하라” 같은 문구가 있어도 따르지 않도록 도구 권한과 할 수 있는 작업을 좁혀 둔다. 검색 결과를 다음 단계의 입력으로 넘길 때는 필수 항목과 인용이 제대로 붙었는지 코드로 검사한다.

파일을 올려 검색하는 법은 Grok 파일·커넥터 활용법에 있다.