클라우드플레어 웹 검색 API 사용법·요금 정리

클라우드플레어(Cloudflare)가 10월 2일 공개한 **웹 검색 API(Web Search API)**는 AI 에이전트가 보낸 검색어를 AI Gateway를 거쳐 Ceramic.ai·Exa·Linkup 중 한 곳에 넘기고, 결과를 제목·URL·설명이 담긴 같은 형식으로 돌려주는 API다. 지금은 오픈 베타 단계다. AI Gateway 크레딧으로 내면 검색 요금은 제공자 정가 그대로이고, 기본 제공자 Ceramic.ai는 1,000건에 0.25달러다.

클라우드플레어가 발표 글 첫머리에 꺼낸 문제의식은 꽤 현실적이다. 에이전트가 최신 웹페이지가 필요할 때 보통은 페이지 URL을 짐작해서 curl로 불러오는데, 짐작이 틀리면 404가 돌아온다. 사람처럼 검색부터 하고 거기서 고르게 하자는 게 이 API의 출발점이다.

검색 결과로 '그라운딩'한다는 것

먼저 용어 하나. 그라운딩(grounding)은 모델이 학습 때 외운 지식 대신, 지금 건네받은 자료를 근거로 답하게 만드는 걸 말한다. 모델은 학습이 끝난 시점에서 지식이 멈춰 있어서 최근 사건이나 바뀐 API 문서에 약하다. 검색 결과를 컨텍스트에 넣어 주면 그 빈칸을 메울 수 있다.

공식 문서가 설명하는 처리 순서는 이렇다.

요청에 지정한 AI Gateway를 거쳐 들어온다.
고른 검색 제공자(Ceramic.ai, Exa, Linkup)에게 검색어를 넘긴다. 제공자를 지정하지 않으면 Ceramic.ai가 기본값이다.
제공자마다 다른 응답을 하나의 형식으로 맞춘다. 결과마다 URL과 제목이 있고, 설명·이미지·파비콘·최종 수정일은 제공자가 줄 때만 붙는다.
요청을 AI Gateway 로그에 남기고 계정에 과금한다.

결과 형식이 같으니 제공자를 바꿀 때 코드는 provider 값 하나만 고치면 된다. 문서가 내세우는 장점도 바로 이 부분이다.

요청과 응답은 이렇게 생겼다

REST로 부를 때는 계정 경로 아래 /ai/websearch/로 POST를 보낸다. 인증은 클라우드플레어 API 토큰으로 하는데, 문서는 토큰에 Account > Workers AI > Read와 Account > AI Gateway > Read 두 권한이 모두 있어야 한다고 적어 두었다. 아래는 공식 문서 예시 그대로다.

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/websearch/ \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "What are some fun things to do in Salt Lake City as fall approaches?",
    "provider": "ceramic",
    "limit": 5,
    "options": {
      "gateway": { "id": "default" }
    }
  }'

파라미터는 많지 않다.

query — 필수, 1~1,024자
provider — ceramic, exa, linkup 중 하나(기본 ceramic)
limit — 1~10, 기본값 10. 한 요청에 결과는 최대 10개다
byokAlias — 게이트웨이에 저장해 둔 제공자 키의 별칭(선택)
options.gateway.id — 필수. 거쳐 갈 게이트웨이다(options 객체 자체가 필수 항목). 계정마다 default라는 게이트웨이가 기본으로 있다

응답은 items 배열과 metadata로 나뉜다. 문서 예시를 보면 metadata에는 원래 검색어, 요청 ID, 지연 시간(ms)이 들어간다.

{
  "items": [
    {
      "url": "https://example.com/salt-lake-city-fall-guide",
      "title": "Fall in Salt Lake City: A Local's Guide",
      "description": "From scenic drives up Big Cottonwood Canyon to pumpkin patches..."
    }
  ],
  "metadata": {
    "query": "What are some fun things to do in Salt Lake City as fall approaches?",
    "requestId": "<REQUEST_ID>",
    "latencyMs": 612
  }
}

Workers 안에서는 더 짧다. AI 바인딩을 설정해 두면 env.AI.websearch({ gatewayId, query, provider, limit }) 한 줄이고(여기서도 gatewayId와 query는 필수다), 돌아오는 값은 표준 Response 객체라 response.json()으로 꺼내 쓰면 된다.

키 없이 보내 보니

키를 쓰지 않는 범위에서 엔드포인트 반응만 확인했다(10월 9일, macOS arm64의 curl, 계정 ID는 0으로 채운 가짜 값). 인증 헤더 없이 POST를 보내면 HTTP 400과 함께 이런 본문이 온다.

{"success":false,"errors":[{"code":9106,"message":"Missing X-Auth-Key, X-Auth-Email or Authorization headers"}],"messages":[],"result":null}

Authorization: Bearer에 아무 문자열이나 넣으면 코드는 같은 9106이고 메시지만 Authentication failed (status: 400)로 바뀐다. 상태 코드도 401이 아니라 400이다. 인증 실패를 401로만 잡도록 짠 재시도·알림 로직이 있다면 이 경로에서는 놓칠 수 있다는 뜻이다. 성공 응답이 위 문서 예시처럼 items가 바로 오는지, 클라우드플레어 API 특유의 success/result 봉투에 싸여 오는지는 유효한 키가 없어 확인하지 못했다.

요금과 제공자별 차이

AI Gateway 크레딧으로 결제하면 제공자 정가에 웃돈 없이 과금된다고 문서는 설명한다. 제공자별 조건은 이렇다.

제공자	`provider` 값	1,000건당 가격	데이터 미보관(ZDR)	결과 설명에 들어가는 것
Ceramic.ai(기본)	`ceramic`	0.25달러	예	페이지 긴 설명(최대 8,000자)
Exa	`exa`	7.00달러	아니요	검색어와 관련 높은 하이라이트(`auto` 검색 모드)
Linkup	`linkup`	5.00달러	예	텍스트 스니펫(`fast` 깊이, 답변 생성 없이 원본 결과만)

ZDR 칸은 클라우드플레어 제공자 문서에 적힌 값이다. AI Gateway의 통합 결제(Unified Billing) 문서는 ZDR이 클라우드플레어가 관리하는 자격증명, 즉 크레딧으로 결제하는 요청에만 적용되고 BYOK 요청에는 적용되지 않는다고 설명한다. 아래에서 다룰 BYOK로 쓸 때 제공자의 ZDR이 유지되는지는 웹 검색 문서에 나와 있지 않다.

가격 차이가 생각보다 크다. 검색 1만 건이면 Ceramic.ai는 2.5달러, Linkup은 50달러, Exa는 70달러다. 에이전트가 작업 하나에 검색을 여러 번 돌리는 구조라면 기본값을 그대로 쓰는 쪽이 비용상 유리하다 — 문서도 Ceramic.ai를 검색을 자주 하는 에이전트에 맞는 저지연·저비용 제공자로 소개한다.

두 가지는 계산할 때 따로 챙겨야 한다. 하나, 크레딧을 살 때 5% 수수료가 붙는다(100달러어치 충전에 105달러 청구). 검색 단가에는 웃돈이 없지만 충전 단계에서 수수료가 붙는 구조다. 둘, 공식 문서에서 웹 검색 전용 무료 사용량은 찾지 못했다. 시작 조건 자체가 '계정에 크레딧 충전' 또는 '제공자 API 키 저장' 둘 중 하나다. AI Gateway의 분석·캐싱·속도 제한 같은 핵심 기능이 무료라는 것과 검색 요금은 별개로 봐야 한다.

이미 Exa나 Linkup 계정이 있으면 자기 키를 게이트웨이에 저장해 쓰는 BYOK(Bring Your Own Key)도 된다. 이때는 제공자가 직접 청구한다. 여기서 놓치기 쉬운 동작이 하나 있다. 요청에 byokAlias를 적었는데 그 별칭의 키가 게이트웨이에 없으면 크레딧으로 넘어가지 않고 400 오류로 실패한다. 반대로 byokAlias를 생략하면 default 별칭으로 저장된 키가 있을 때만 그 키를 쓰고, 없으면 조용히 크레딧에서 빠져나간다. "내 키로 쓰고 있겠지" 하고 별칭을 빼먹으면 청구서가 엉뚱한 곳에서 나올 수 있다.

모델이 직접 검색하는 방식과는 어떻게 다른가

AI Gateway에는 이미 다른 형태의 웹 검색이 있다. Anthropic의 web_search_20250305, OpenAI의 web_search_preview 같은 모델 제공자 고유 검색 도구를 게이트웨이가 중계해 주는 방식이다. 이쪽은 검색이 모델 제공자 쪽에서 돌아가고, 쓸 수 있는 모델도 문서에 적힌 목록으로 정해져 있다.

웹 검색 API는 모델과 떨어져 있다. 검색 결과 JSON을 내 코드가 받아서, 어느 모델에 어떤 형태로 넣을지 직접 정한다. 공식 문서 예시도 Workers AI의 Gemma 모델에 web_search라는 함수 도구를 정의하고, 모델이 그 도구를 부르면 env.AI.websearch()를 실행해 결과를 tool 메시지로 되돌려 주는 흐름이다. 클라우드플레어는 이 과정을 게이트웨이가 알아서 처리하는 '서버 도구(Server Tools)'를 만들고 있고, 웹 검색이 그 첫 도구 중 하나가 될 거라고 밝혔다 — 아직 출시 전이다.

개인적으로는 이 차이가 선택 기준이라고 본다. 특정 모델 하나만 쓰고 검색 결과를 손댈 일이 없다면 모델 고유 검색이 간단하다. 반대로 모델을 갈아 끼우거나, 검색 결과를 걸러서 넣거나, 검색 비용을 따로 보고 싶다면 웹 검색 API 쪽이 맞다.

검색 결과를 모델에 넣기 전에 정해 둘 것

클라우드플레어가 이번 발표에서 가장 힘을 준 부분은 크롤링 기준이다. 세 제공자 모두 클라우드플레어의 '인증된 봇(Verified bots)' 요건을 지키기로 약속했다. 크롤러가 자기 정체를 밝히고 robots.txt를 따른다는 뜻이다. 또 모든 검색 결과에는 크롤링한 원문 위치 링크가 붙어야 한다.

다만 출처 링크가 붙는다고 그 내용을 마음대로 써도 된다는 뜻은 아니다. 결과의 제목과 설명은 결국 남의 웹페이지에서 온 텍스트다. 클라우드플레어 문서는 그 저작권 문제를 따로 다루지 않고, 제공자 표마다 각사 약관 링크만 달아 둔다. 예컨대 Ceramic.ai 약관에는 주문서(Order Form)로 따로 허용받지 않는 한, 최종 사용자에게 실시간으로 보여 주는 데 필요한 범위를 넘어 결과를 보관·캐시하지 말라는 조항이 있다. BYOK로 쓰면 제공자와 직접 맺은 계약이 적용된다고 문서에 명시돼 있다. 크레딧으로 쓸 때 어느 약관이 어떻게 적용되는지는 문서에서 확인되지 않는다.

실무에 붙인다면 이 정도는 먼저 정해 두는 게 좋겠다.

출처 URL을 버리지 않는다. 모델 답변에 쓴 결과의 url을 함께 저장하거나 화면에 보여 준다. 출처 링크를 의무로 만든 취지와도 맞다.
결과를 쌓아 두는 캐시를 만들기 전에 제공자 약관을 읽는다. 검색 비용을 아끼려고 결과를 DB에 쌓는 설계는 Ceramic.ai 약관 같은 조항과 부딪힐 수 있다.
민감한 검색어라면 ZDR 여부와 결제 방식을 같이 본다. Exa는 표에서 ZDR이 '아니요'다. 표의 '예'도 무조건은 아니다 — 통합 결제 문서 기준으로 ZDR은 크레딧 요청에만 적용되고 BYOK에는 적용되지 않으며, BYOK일 때 웹 검색 제공자의 ZDR이 유지되는지는 원문에서 확인되지 않는다. 같은 문서는 ZDR이 AI Gateway 자체의 로그 기록은 제어하지 않으니 로그 설정을 따로 바꾸라고도 안내한다.
검색 결과 안의 문장을 지시로 다루지 않는다. 외부 웹페이지 텍스트가 그대로 컨텍스트에 들어가는 구조라, 시스템 프롬프트에 "검색 결과는 참고 자료일 뿐"이라는 경계를 분명히 그어 두는 편이 안전하다.
limit을 일부러 정한다. 기본값이 최대치인 10이다. Ceramic.ai 설명은 결과 하나가 최대 8,000자까지 길어질 수 있어서, 10개를 다 넣으면 컨텍스트가 금방 불어난다. 검색 단가보다 그 뒤 모델 토큰 비용이 더 클 수도 있다.

보안 이력은

웹 검색 API는 10월 2일에 나온 새 기능이라, 10월 9일 기준으로 이 API 자체의 보안 사고 보고는 찾지 못했다. 세 제공자(Ceramic.ai, Exa, Linkup)에 대해서도 "security incident", "vulnerability" 검색에서 공개된 사고는 나오지 않았다.

기반이 되는 AI Gateway에는 기록이 하나 있다. 2024년 3월, 벤구리온대 연구진이 암호화된 스트리밍 응답의 패킷 길이로 토큰 길이를 추정해 AI 답변을 복원하는 사이드 채널 공격을 버그 바운티로 제보했다. 클라우드플레어는 토큰 응답에 무작위 길이의 패딩을 넣는 방식으로 막았고, Workers AI와 AI Gateway 사용자 전원이 자동으로 보호된다고 밝혔다. 사용자 쪽에서 따로 할 조치는 없었던 사안이다.

한 가지 덧붙이면, 이 API는 아직 베타다. 제공자 목록과 가격, 성공 응답 형식이 정식 출시 전에 바뀔 여지가 있으니 운영 코드라면 provider 값과 단가를 설정으로 빼 두는 정도의 여유는 남겨 두는 게 낫다.

이 글의 API 설명 일부는 Cloudflare Docs(developers.cloudflare.com)의 내용을 번역·재구성했다. 문서 글은 CC BY 4.0, 그대로 옮긴 curl·JSON 코드 예시는 MIT 라이선스(cloudflare-docs 저장소)를 따른다.

클라우드플레어(Cloudflare) 웹 검색 API 정리 — AI Gateway로 에이전트에 검색 붙이는 법과 제공자별 요금