Serper API 키와 문서: 로그인부터 첫 결과를 받기까지

“serper api key”, “serper api docs”, “serper api login”을 검색하는 사람 대부분이 같은 벽에 부딪힙니다. Serper에는 별도 문서 사이트가 없습니다. 2026년 11월 5일 기준 serper.dev/docs는 404를 반환했습니다. 실제로 “문서” 역할을 하는 것은 로그인한 뒤에만 쓸 수 있는 플레이그라운드 페이지입니다. 파라미터 규칙, 크레딧 비용, 샘플 코드가 모두 이 페이지의 JavaScript 안에 들어 있습니다.

저희는 공개된 serper.dev 페이지와 프런트엔드 스크립트를 읽었습니다. 이어서 같은 날 00:18부터 00:54(SGT)까지 EveryInfra 검색 API에 실제 요청 34건을 보냈습니다. 21건은 결과를 반환했고 총비용은 $0.015269였습니다. 나머지 13건은 잘못된 키 헤더, 요청 속도 제한 초과 등 의도적으로 잘못 보낸 요청과 빈 결과 1건이었으며, 모두 비용은 $0였습니다.

이 가이드는 가격을 비교하지 않습니다. 첫 호출이 성공하기까지의 과정을 비교합니다. 회원가입부터 첫 결과까지 몇 단계를 거쳐야 할까요? 키는 어디에 있고, 몇 개까지 만들 수 있으며, 유출되면 어떻게 해야 할까요?

q, gl, hl, num, page, type이 저희 API의 어떤 파라미터에 대응하는지 정리합니다. 실제 오류 응답 본문도 보여 드립니다. Python, n8n, MCP 클라이언트에서 키를 어디에 넣는지도 설명합니다. 요금은 첫 번째 섹션에 링크한 이전 Serper 글 세 편을 참고하세요.

이 가이드는 무엇을 다루며, 요금 정보는 어디에 있나

요금을 한 줄로 요약하면 이렇습니다. Serper의 4가지 팩은 크레딧 1,000개당 $0.30~$1.00이며 6개월 후 만료됩니다. EveryInfra 웹 검색은 호출당 $0.000694(1,000건당 $0.694)이며 만료가 없습니다. 쿼리 1,000건당 비용은 Serper API 대안: 요금, 무료 티어, 실제 테스트를 참고하세요. 무료 쿼리 2,500건으로 얼마나 쓸 수 있는지는 Serper API 무료 티어를, 4가지 팩의 월별 비용은 Serper API 요금 총정리를 참고하세요.

이 글은 Serper를 쓰고 있거나 써 볼 계획인 개발자를 위한 글로, 설정과 디버깅만 다룹니다. 키를 어디서 받고 어떻게 보내는지 알려 드립니다. 파라미터 규칙이 어디에 있는지, 호출이 실패하면 무엇을 해야 하는지, 유출된 키는 어떻게 교체하는지도 다룹니다.

Serper에 대해서는 공개 자료만 사용했습니다. 구체적으로 홈페이지, 회원가입 페이지, 로그인 페이지, 이용약관, 개인정보처리방침, 그리고 이 페이지들이 모든 방문자의 브라우저에 불러오는 JavaScript를 확인했습니다. Serper 계정을 만들거나 Serper 키를 쓰거나 Serper 검색 API를 호출하지는 않았습니다. 따라서 “로그인 후 보이는 화면”에 대한 설명은 모두 이 스크립트들의 텍스트나 공개된 제3자 게시물에서 가져왔으며, 매번 출처를 밝힙니다. EveryInfra의 모든 수치는 2026년 11월 5일의 실제 응답에서 나왔습니다.

비교표: 키, 문서, 첫 요청

표에는 직접 확인할 수 있는 사실만 담았습니다. Serper 열은 2026년 11월 5일에 읽은 serper.dev 페이지와 스크립트를 바탕으로 합니다. EveryInfra 열은 문서, 요금 페이지, OpenAPI 파일, 공개 카탈로그, 실제 호출 결과를 바탕으로 합니다. 문서, 요금 페이지, OpenAPI 파일은 2026년 11월 5일 01:25(SGT)에 다시 확인하고 사본을 보관했습니다.

특히 중요한 행은 세 가지입니다. 첫째는 “문서 위치”입니다. Serper는 파라미터, 샘플 코드, 크레딧 비용을 로그인해야 하는 대화형 페이지 안에 두었습니다. 사람에게는 편하지만, AI 코딩 어시스턴트가 읽으려면 한 단계를 더 거쳐야 합니다. 둘째는 “키 관리”입니다.

Serper 키 페이지에는 액션이 4개 있고 삭제는 없습니다. 키 하나가 할 수 있는 일이나 사용할 수 있는 위치를 제한할 수도 없습니다. 셋째는 인증 헤더입니다. 두 API는 서로 다른 헤더를 쓰며, 사람들이 가장 자주 놓치는 변경 사항이 바로 이것입니다. 저희 테스트에서 유효한 키를 X-API-KEY로 보내자 401이 반환되었습니다.

Serper API 로그인: 회원가입과 로그인 절차

Serper 회원가입 페이지에는 “Create an account”와 “Create a free account, no credit-card needed.”라는 문구가 있습니다. 양식의 필수 항목은 성명(이름과 성), 이메일, 비밀번호 세 가지입니다(serper.dev/signup, 2026년 11월 5일 확인). 양식 아래에 사람 확인 절차가 있으며, 이를 통과해야 “Create account” 버튼이 작동합니다. 페이지 스크립트는 요청과 함께 사람 확인 토큰 2개를 보냅니다. 가입 후에는 “Please verify your email account”라는 페이지가 나타나며, 이메일을 다시 보내거나 로그아웃할 수 있습니다. 유효한 링크를 열면 “Your email has been verified.”가, 오래된 링크를 열면 “The verification link is invalid or has expired.”가 표시됩니다.

로그인 페이지에는 “Log in to your account”라는 문구와 함께 이메일, 비밀번호, “Remember me”, “Forgot password?”가 있습니다(serper.dev/login). Settings에서 2단계 로그인을 켜면 인증 앱의 코드도 입력해야 합니다. 설정 화면에는 “Scan the QR code below with your authenticator app”이라는 문구가 있습니다. 회원가입 및 로그인 스크립트에서는 Google이나 GitHub 로그인을 찾지 못했습니다.

따라서 Serper API 로그인은 이메일과 비밀번호를 사용하는 방법만 지원합니다. 사소한 동작 하나가 많은 검색 결과를 설명해 줍니다. 로그아웃 상태에서 serper.dev/api-keys를 열면 로그인 양식이 나타납니다. 그래서 “serper api login”의 첫 번째 검색 결과는 제목이 “Log in to your account”인데 URL은 /api-keys인 경우가 많습니다.

Serper 이용약관에는 “Updated on May 29, 2024”라고 적혀 있습니다. 계정과 관련해 중요한 규칙은 두 가지입니다. 첫 번째 규칙은 “Register more than one account at any point in time”, 즉 어느 시점에든 계정을 2개 이상 등록하는 행위를 금지합니다. 따라서 무료 쿼리를 더 받으려고 계정을 추가로 만들면 약관 위반입니다.

두 번째 규칙은 “Attempt to circumvent any restrictions or limits placed on your Serper API key or account”, 즉 Serper API 키나 계정에 적용된 제한을 우회하려는 모든 시도를 금지합니다. 약관에는 Serper가 B2B 서비스라는 내용도 있습니다. 개인정보 처리방침에는 “Date Last Reviewed: 5 November 2025”라고 표시되어 있으며, Serper가 접근 로그와 활동 로그를 수집한다고 밝히고 있습니다.

EveryInfra 회원가입은 사이트 오른쪽 상단의 “Start free”에서 시작합니다. 페이지에는 이메일 입력란 하나와 선택 입력인 추천 코드가 있고, 그 아래에 “Continue with GitHub”와 “Continue with Google”이 있습니다. EveryInfra에서도 새 계정은 만들지 않았습니다. 따라서 가입 이후 단계는 페이지와 문서를 바탕으로 설명합니다. 빠른 시작에 따르면 가입 후 콘솔에서 API 키를 만들며, 전체 키는 한 번만 표시됩니다.

설정 과정의 주된 차이는 한 단계입니다. Serper는 가입 후 받은편지함에서 인증 링크를 열고 이메일과 비밀번호로 로그인해야 합니다. EveryInfra에서는 GitHub 또는 Google 계정으로 가입해 받은편지함 단계를 건너뛸 수 있습니다. EveryInfra의 $1 체험용 크레딧을 받으려면 GitHub에서 저장소 2개에 스타를 누르는 단계가 추가되지만, 이 단계는 크레딧을 받기 위한 것이며 키와는 관계가 없습니다. 설정을 AI 어시스턴트가 진행한다면 받은편지함 단계마다 사람이 개입해야 하므로 흐름이 멈춥니다.

Serper API 키는 어디에 있고, 무엇을 할 수 있을까?

Serper 키는 대시보드의 API Keys 페이지에 있습니다. 페이지 제목은 “API Keys”, 부제목은 “Your keys to unlock the power of Serper”입니다. 페이지 스크립트는 키 목록 조회, 키 생성, 키 이름 변경의 세 가지 계정 엔드포인트를 호출합니다. 키에는 반드시 이름이 있어야 하며, 비워 두면 양식에 “Name is required”가 표시됩니다.

각 키에는 “Reset” 액션도 있습니다. 재설정 대화 상자에는 “Are you sure you want to reset this API key? This action cannot be undone and any applications using this key will stop working.”이라고 적혀 있습니다. 재설정 후 페이지에는 “The old API key is not valid anymore. Replace it with the new one.”이 표시됩니다.

페이지에는 “API key copied to clipboard” 메시지가 뜨는 복사 버튼도 있습니다. 따라서 전체 키가 대시보드에 계속 표시되고, 로그인 정보를 가진 사람이라면 누구나 나중에 다시 복사할 수 있습니다. 스크립트에는 키를 삭제하는 엔드포인트가 없습니다. 키 하나를 특정 제품, 지출 한도, 특정 출발지 IP 주소로 제한하는 설정도 없습니다.

Settings 페이지에서는 이름, 비밀번호, 2단계 로그인, 결제 카드를 관리합니다. “Activity logs” 페이지에는 최근 요청이 Time, Query, Type, Page, Num, Credits, Response time (ms) 열로 표시되며, 키별로 필터링할 수 있습니다. “Anonymize queries” 스위치를 켜면 로그에 쿼리 텍스트가 남지 않습니다.

기능이 없다고 해서 Serper를 쓸 수 없는 것은 아닙니다. 스크립트 하나에 키 하나를 쓰는 개발자 한 명이라면 생성과 재설정만으로 충분합니다. 차이는 팀, 여러 환경, AI 에이전트를 다룰 때 드러납니다. 키 하나를 노트북 PC, CI, 그리고 고객과 공유한 데모 노트북에 모두 넣어 두었다고 가정해 봅시다.

데모 노트북이 유출되면 Serper에서는 재설정 한 번으로 세 곳이 동시에 멈춥니다. 환경별로 키를 나눠 두었다면 유출된 키만 비활성화하면 됩니다. EveryInfra 문서는 이를 두꺼비집에 비유합니다. 키 하나가 메인 스위치이고, API Keys → Permission limits에서 개별 회로를 끌 수 있습니다(빠른 시작, 인증 섹션).

스크립트로 키 관리하기: EveryInfra OpenAPI 파일의 키 엔드포인트

키는 콘솔에서만 관리할 수 있는 것이 아닙니다. EveryInfra OpenAPI 파일의 Account 섹션에는 키 관련 엔드포인트가 정리되어 있으며, 2026년 11월 5일 01:25(SGT)에 확인했습니다. 이 엔드포인트는 모두 과금되지 않습니다. 다른 계정 엔드포인트와 계정당 분당 60건의 요청 속도 제한을 공유합니다.

읽기 엔드포인트에는 계정 읽기 스코프가 필요합니다. 모든 제품에 접근할 수 있는 키에는 기본적으로 account:read, requests:read, billing:read가 있습니다. 일부 제품으로 접근이 제한된 키에는 계정 소유자가 콘솔에서 활성화한 후에만 해당 스코프가 부여됩니다. 쓰기 엔드포인트에는 keys:write 스코프가 필요합니다. 이 스코프는 기본적으로 꺼져 있으며, 콘솔에 로그인한 계정 소유자만 부여할 수 있습니다. 키를 사용해 변경한 내용은 모두 콘솔 알림에 표시됩니다.

유출 후에는 이 필드들이 중요합니다. spend_limit_usd는 키 하나에 대한 평생 누적 USD 한도로, 과금액에서 환불액을 뺀 값이며 초기화되지 않습니다. CI 키나 데모 노트북 키에 작은 한도를 걸어 두면 유출되더라도 피해에 상한이 생깁니다. expires_at을 설정하면 임시 키가 정해진 시점에 저절로 중지됩니다. ip_allow를 설정하면 자체 서버의 IP 주소에서만 키가 작동합니다.

Serper API Keys 페이지 스크립트에서는 이에 해당하는 옵션을 찾지 못했습니다. 이 섹션은 OpenAPI 문서의 내용을 따릅니다. 테스트 키를 만들어 각 엔드포인트를 직접 호출하지는 않았습니다.

Serper API 문서: 플레이그라운드가 곧 문서다

먼저 별도 문서 사이트가 있는지 확인했습니다. 2026년 11월 5일 기준 serper.dev/docs, serper.dev/llms.txt, serper.dev/openapi.json, serper.dev/sitemap.xml은 모두 404를 반환했습니다. 홈페이지 푸터의 “Product” 열에는 Playground와 Dashboard, 그리고 Haystack, Jan AI, CrewAI, LangChain 연동 링크가 있습니다. “Docs”나 “API reference” 링크는 없습니다.

Serper의 GitHub 조직 Serper-API에는 저장소가 7개 있습니다. GitHub에서는 모두 Auto-GPT, chat-ui, Perplexica 등 다른 프로젝트의 포크로 표시됩니다. SDK나 API 명세는 하나도 없습니다.

따라서 “serper api documentation”은 사실상 플레이그라운드를 뜻합니다. 플레이그라운드는 폼으로 구성되어 있습니다. 왼쪽에서 결과 유형을 고르고 쿼리를 입력하면 오른쪽에 결과와 코드가 나타납니다. 저희는 이 페이지의 스크립트를 읽고, 이를 기준으로 코드를 작성할 때 중요한 사실 일곱 가지를 정리했습니다.

첫째, 결과 유형은 요청 본문이 아니라 URL의 일부로 지정합니다. 스크립트는 선택한 유형을 https://google.serper.dev/<type>에 붙이고, 요청을 보내기 전에 본문에서 type을 제거합니다. 선택할 수 있는 유형은 search, images, videos, places, news, shopping, scholar, patents, autocomplete, product-reviews, lens, maps, reviews이며, 일부 유형은 계정에 따라 사용 가능 여부가 다릅니다. 웹 페이지 스크래핑은 별도 호스트인 https://scrape.serper.dev를 사용합니다.

“Resolve links” 도구는 0크레딧입니다. 둘째, 파라미터에는 기본값이 있으며, 스크립트는 기본값과 같은 파라미터를 빼고 보냅니다. 기본값은 gl=us, hl=en, page=1, num=10, autocorrect=true입니다.

셋째, 일반 검색의 결과 개수 메뉴에는 이제 10 하나만 있습니다. images는 10 또는 100을 제공하고, shopping은 40을 씁니다. 넷째, “Mini-batch (up to 100 queries)” 스위치를 켜면 쿼리 목록을 요청 하나에 담을 수 있습니다. 다섯째는 크레딧입니다. 실시간 “Credits: N” 위젯이 현재 요청의 비용을 보여 줍니다.

스크립트는 maps와 lens에 3크레딧, shopping과 product-reviews에 2크레딧, 그 밖의 대부분 유형에 1크레딧을 설정합니다. 웹 페이지 스크래핑은 2크레딧이며, 까다로운 페이지는 6 또는 10크레딧입니다. 스크립트 문구로는 “Most webpages typically incur 2 credits, but for harder-to-scrape pages ... the cost can be 6 or 10 credits”입니다. 결과가 10개를 넘는 images 요청은 비용이 2배입니다.

여섯째, 샘플 코드입니다. 코드 패널은 Postman의 오픈소스 라이브러리 postman-code-generators를 씁니다. 언어 메뉴는 이 라이브러리의 getLanguageList() 호출 결과를 그대로 가져오며, 기본값은 Node.js입니다. POST와 GET 중 하나를 고를 수 있습니다.

POST는 키를 X-API-KEY 헤더로 보냅니다. GET은 모든 파라미터와 apiKey를 URL에 넣습니다. URL에 담긴 키는 서버 접근 로그, 브라우저 기록, 프록시 로그에 남습니다. 따라서 사용하는 도구가 GET만 지원하는 경우가 아니라면 POST를 사용하는 것이 좋습니다.

2025년 7월 26일의 n8n 커뮤니티 게시물에 이 함정이 잘 드러납니다. 한 사용자가 헤더를 넣어 GET으로 요청했다가 403을 받았습니다. 답글에서는 GET은 키를 URL에 넣어야 하고, 헤더를 읽는 방식은 POST라고 설명했습니다(n8n 커뮤니티 스레드).

일곱째, 위치입니다. 위치 필드에는 “You can find a list of supported locations here”라는 문구와 함께 api.serper.dev/locations 링크가 있습니다. 이 공개 목록을 내려받았습니다. 목록에는 240개 국가 및 지역의 항목 100,029개가 있으며, 여기에는 우편번호 48,384개, 도시 37,208개, 동네 4,309개가 포함됩니다. EveryInfra의 location 필드보다 훨씬 세밀합니다. 저희 도구 카탈로그는 “국가 이름이나 두 글자 국가 코드를 사용하며, 도시는 해당 국가로 처리된다”고 안내합니다.

대화형 페이지 안에 있는 문서에는 대가가 따르며, 검색 한 번으로 이를 확인할 수 있었습니다. 00:18:40과 00:19:06(SGT)에 EveryInfra 웹 검색에서 location: us를 지정해 “serper api documentation”을 검색하고, 첫 두 페이지의 결과 20개를 수집했습니다. serper.dev URL은 홈페이지, /api-keys(로그아웃 상태에서는 로그인 양식), /signup 3개뿐이었습니다. 문서 페이지는 하나도 없었습니다.

8개는 다른 프로젝트의 문서였습니다. CrewAI, LangChain(3개, 그중 1개는 오래된 미러), Langflow, Haystack, Sim, Aikeedo입니다. 4개는 API 디렉터리였습니다. 나머지 5개는 GitHub 조직, Medium 게시물, YouTube 동영상, MCP 등록 페이지, 다른 검색 API의 홈페이지였습니다.

영국 독자를 위해 SGT 00:45:40에 한 번 더 확인했습니다. location: gb로 “serper api key”를 검색했더니 이번에도 첫 두 결과는 Serper 홈페이지와 /api-keys였습니다. 그다음은 다른 검색 API의 홈페이지, CrewAI 문서, LangChain 문서였습니다. 나머지는 Medium 비교 글, SERP API 모음 글, Aikeedo 문서, h2oGPT GitHub 이슈였습니다.

Serper 문서를 검색한 사람은 대부분 어느 프레임워크의 문서에 도착하며, 프레임워크마다 Serper를 조금씩 다르게 설명합니다.

AI 코딩 어시스턴트에게 클라이언트 코드 작성을 맡기는 개발자에게는 어시스턴트가 로그인 없이 읽을 수 있는 문서가 필요합니다. EveryInfra에서는 공개 파일 세 개가 이 역할을 합니다.

이 파일들이 있으면 어시스턴트가 기억에 의존해 추측하는 대신 코드를 작성하기 전에 파라미터를 확인할 수 있습니다. 아래 테스트에서 보듯 잘못 추측하면 422가 반환됩니다. Serper의 파라미터 규칙은 플레이그라운드 안에 있어서, 어시스턴트는 주로 프레임워크의 2차 문서를 읽게 됩니다. 예를 들어 CrewAI 문서에는 여전히 “n_results”의 기본값이 10이라고 되어 있지만, 플레이그라운드의 일반 검색 메뉴는 이제 10만 제공합니다.

EveryInfra와 비교한 Serper API 문서의 파라미터

결론부터 말하면 두 API 모두 JSON 본문을 받아 JSON을 반환합니다. 하지만 파라미터 이름, 결과 유형을 고르는 방식, 응답 필드가 다릅니다. URL만 바꿔서는 전환할 수 없습니다. 플레이그라운드 스크립트의 일반 검색 파라미터를 EveryInfra web 도구의 파라미터와 비교했습니다. 출처는 무료로 공개된 도구 카탈로그이며, 2026년 11월 5일 SGT 00:16에 확인했습니다.

주의해야 할 행이 두 개 있습니다. 첫째는 location입니다. 이름은 양쪽이 같지만 의미는 다릅니다. Serper에서 location은 구체적인 장소이고, 국가는 gl로 지정합니다. EveryInfra에서 location은 국가이며, 도시를 넣으면 해당 국가로 처리됩니다.

따라서 Serper에서 옮겨 올 때는 gl 값을 location에 복사하고, Serper에서 쓰던 기존 location 값은 버리세요. 둘째는 hl입니다. web 도구에는 언어 파라미터가 없습니다. 언어 설정이 필요하면 데이터 카탈로그의 web/search를 사용하세요. 이 항목은 keyword, country, language를 받으며, 가격은 $0.001389로 web의 두 배입니다.

결과 유형을 지정하는 방식도 바뀝니다. Serper는 유형을 URL에 넣습니다. EveryInfra 검색은 엔드포인트가 POST /api/v1/search 하나뿐이며, 본문의 tool 필드로 도구 17종 중 하나를 고릅니다. 아래 표는 카탈로그 설명을 바탕으로 만들었습니다. 대응 관계는 용도가 비슷하다는 뜻일 뿐, 결과가 같다는 뜻은 아닙니다.

유형마다 크레딧 비용이 다르므로 Serper의 1,000회 호출당 가격도 유형에 따라 다릅니다. Starter 팩에서는 1,000 크레딧이 $1.00입니다. maps와 lens는 호출당 3 크레딧을 쓰므로 1,000회 호출당 $3.00입니다. Ultimate 팩에서는 1,000 크레딧이 $0.30이므로 maps는 1,000회당 $0.90입니다.

crosscheck를 제외한 모든 EveryInfra 검색 도구는 호출당 $0.000694입니다. 아래 차트는 공개된 단가를 유형별로 나란히 보여 줍니다. 팩 크기와 만료 규칙은 Serper API 요금 구조 해설을 참고하세요.

첫 요청 보내기: 양쪽 curl 비교

다음은 플레이그라운드의 POST 형식으로 작성한 Serper 첫 요청입니다. Serper 키가 없어서 실제로 실행하지는 않았습니다. 페이지 스크립트와 CrewAI 소스를 바탕으로 작성했습니다.

# Serper: configuration example (not run for this article)
curl -s https://google.serper.dev/search \
  -H "X-API-KEY: $SERPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"serper api documentation","gl":"us","hl":"en","num":10}'

다음은 같은 검색을 EveryInfra에서 실행한 예입니다. 2026년 11월 5일 00:18:40(SGT)에 실행했습니다. 1.55초 만에 결과 10개가 담긴 HTTP 200 응답을 받았고, billing.charged_usd는 0.000694였습니다.

# EveryInfra: run for this article
curl -s https://api.everyinfra.com/api/v1/search \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"web","q":"serper api documentation","location":"us","num":10}'

바뀌는 부분은 URL, 헤더, gl이 location으로 바뀌는 것, hl이 사라지는 것 네 가지입니다. 놓치기 쉬운 부분이 하나 더 있습니다. 문서에서는 {"tool":"web","q":...}처럼 파라미터를 본문의 최상위에 둡니다. 원격 MCP 도구 everyinfra_search는 {"tool":"web","params":{"q":...}}처럼 params 객체 안에 둡니다. 둘 다 동작하지만 섞어 쓸 수는 없습니다. 섞어 쓰면 어떻게 되는지는 아래 MCP 섹션에서 다룹니다.

배치 처리도 달라집니다. Serper의 Mini-batch는 요청 하나에 쿼리를 최대 100개까지 받습니다. EveryInfra 검색 API는 요청당 쿼리 하나를 받습니다. 따라서 키워드 100개짜리 배치는 분당 한도 안에서 보내는 요청 100건이 됩니다. 계정 기본 한도는 분당 60건이므로 키워드 100개를 처리하는 데 약 2분이 걸립니다.

스피드 팩을 사용하면 한도가 분당 1,800건으로 올라갑니다(요금). 비용은 그대로 쿼리당 $0.000694, 100개에 $0.0694입니다. 요청을 하나씩 보내면 실패도 하나씩 일어납니다. 한 쿼리의 파라미터가 잘못되면 422가 하나 반환될 뿐, 나머지 99개는 그대로 실행됩니다.

응답 필드: organic과 results 비교

Serper 홈페이지의 샘플 응답은 하나의 큰 객체입니다. 최상위에 knowledgeGraph, organic, peopleAlsoAsk, relatedSearches가 있습니다. 각 organic 결과에는 title, link, snippet, position이 있고, 일부에는 sitelinks, date, attributes도 있습니다(serper.dev 홈페이지 샘플). 플레이그라운드는 결과를 표시하기 전에 응답에서 searchParameters를 제거하므로, 실제 응답에는 요청 내용도 함께 담겨 있습니다. LangChain은 유형마다 다른 키를 읽습니다. 검색은 organic, 뉴스는 news, 장소는 places, 이미지는 images입니다(LangChain 소스).

EveryInfra web 응답은 {"id","tool","location","results","billing","quota"}입니다. 각 결과에는 title, url, snippet이 있고, 날짜를 알 수 있으면 published도 포함됩니다. SGT 00:19:06에 실행한 2페이지 호출에서는 결과 10개 중 3개에 published가 있었습니다. 데이터 카탈로그의 web/search 항목은 더 많은 필드를 반환합니다. 반환되는 필드는 title, url, text, rank, published_at, image_url, sub_links입니다(데이터 카탈로그). SGT 00:20:09에 실행한 호출에서는 결과 10개 중 3개에 published_at이 있었습니다.

마지막 행은 과금 기록에 관한 것입니다. Serper FAQ에는 "쿼리에 대해 성공한 응답을 받을 때마다 계정 잔액에서 크레딧을 차감합니다"라고 되어 있습니다. 잔액이 0이 되면 새 쿼리는 처리되지 않습니다. 사용 내역을 보려면 Dashboard와 Activity 로그를 열어야 합니다. EveryInfra의 모든 응답에는 charged, charged_usd, balance_after_usd가 담긴 billing 객체가 포함됩니다.

배치 작업은 응답만으로 지출을 대조할 수 있습니다. 실패한 호출과 빈 결과 호출에는 charged: false가 표시됩니다. web 도구는 지식 패널이나 관련 질문을 반환하지 않습니다. 이 필드에 의존하는 코드에는 새 로직이 필요하며, 자세한 내용은 "Serper가 더 나은 경우" 섹션에서 설명합니다.

테스트 1: Serper 형식 요청을 그대로 보내면

전환 후 가장 저지르기 쉬운 실수는 URL과 헤더만 바꾸고 기존 파라미터를 그대로 두는 것입니다. API가 어떻게 반응하는지 보려고 일부러 이 실수를 해 봤습니다.

SGT 00:18:28에 {"tool":"web","q":"serper api documentation","gl":"us","hl":"en","num":10}를 보냈습니다. API는 0.20초 만에 HTTP 422를 반환했습니다. error.code는 unknown_param이었고, message는 "gl is not a parameter of tool web Supported: after, before, location, num, page, q, site"였습니다.

allowed 목록에는 유효한 파라미터 7개가 들어 있었습니다. next_steps 필드에는 "Remove gl; the parameters are listed at catalog_url. Nothing was charged."라고 적혀 있었습니다. API는 호출당 알 수 없는 파라미터를 하나씩 알려 줍니다. gl을 지우고 hl은 그대로 둔 채 SGT 00:18:47에 다시 보냈더니 param: hl과 함께 같은 422가 반환되었습니다.

SGT 00:19:00에는 location을 locaton으로 잘못 적었습니다. 0.11초 만에 did_you_mean: ["location"]이 포함된 422가 반환되었습니다. 첫 번째 다음 단계 안내는 "Rename locaton to location (did_you_mean), then resend. Nothing was charged."였습니다. 두 번째 안내는 보낸 파라미터가 카탈로그에 실제로 있다면 티켓을 열라는 내용이었습니다.

SGT 00:19:14에는 본문에 "type":"news"를 넣었고, type은 web의 파라미터가 아니므로 422가 반환되었습니다. SGT 00:19:20에는 media 도구에 kind: "videos"를 보냈습니다. 오류는 invalid_value였고, allowed는 image와 video, did_you_mean은 video였습니다.

이런 오류는 AI 어시스턴트가 스스로 호출을 고칠 수 있도록 마련한 것입니다. 422는 재시도해도 소용없다는 것을 프로그램에 알려 주고, allowed와 did_you_mean은 무엇을 바꿔야 하는지 어시스턴트에 알려 줍니다. HTTP는 서버가 요청을 이해했지만 처리할 수 없는 경우의 상태 코드로 422를 정의합니다(MDN: 422). 이 정의는 RFC 9110 15.5.21절에 명시되어 있습니다. 이는 잘못된 이름이나 잘못된 값에 맞는 코드입니다. EveryInfra의 오류 본문은 RFC 9457의 problem+json 형식이 아닙니다. 자체 error 객체이며, 각 필드는 자가 복구형 API 오류 가이드에서 설명합니다.

테스트 2: 키 누락, 잘못된 헤더, 요청 속도 제한

SGT 00:18:21에 인증 헤더 없이 web을 호출했습니다. API는 0.12초 만에 code: unauthorized, message: Missing API key와 함께 HTTP 401을 반환했습니다. fault는 account, retryable은 false였고, next_steps에는 "This API key is not accepted; ask the user for a working key (console: API keys). Nothing was charged."라고 적혀 있었습니다. SGT 00:18:34에는 Serper 방식대로 유효한 키를 X-API-KEY 헤더에 넣었습니다. 결과는 같은 메시지의 같은 401이었습니다.

두 번째 결과는 분명히 밝혀 둡니다. 오류 메시지는 "대신 Authorization: Bearer를 사용하라"고 알려 주지 않습니다. Serper에서 넘어왔다면 위 표처럼 헤더 줄을 직접 바꾸십시오.

Serper용 키가 없으므로 공개 게시물을 인용합니다. 위의 n8n 스레드에는 본문 {"message":"Unauthorized. Sign up for a free account.","statusCode":403}과 함께 HTTP 403이 나옵니다. 2024년 CrewAI 이슈 #633의 제목은 "Unauthorized Error (403) when Using SERPER_API_KEY"입니다.

원인은 다른 서비스의 키였습니다. 잔액이 없는 경우는 2026년 10월 23일 커밋 메모에 400 {"message":"Not enough credits"}로 기록되어 있습니다(neo1415/q #339). 2026년 10월 22일 작업 목록에는 "400 또는 403"이라고 적혀 있고 미확인으로 표시되어 있습니다(dbhq-uk/gannet #12). serper.dev에서는 오류 코드 표를 찾지 못했습니다.

요청 속도 제한은 테스트 도중 저절로 걸렸습니다. 테스트 키에는 분당 10회라는 별도 상한이 있고, 여러 작성 작업이 이 키를 함께 씁니다. SGT 00:19:55, 00:20:56, 00:22:38, 00:24:51에 HTTP 429를 네 번 받았습니다. 각 응답에는 code: rate_limited, 차례로 5초, 4초, 22초, 9초인 retry_after, max_retries: 3, 그리고 "Nothing was charged.

Retry after retry_after seconds"라는 안내가 있었습니다. 스크립트는 429를 받으면 60초를 기다렸고, 다음 시도는 매번 성공했습니다. 헤더는 Retry-After에 관한 MDN 문서를, 429 코드는 RFC 6585를 참고하십시오.

빈 결과 행은 SGT 00:20:17에 존재하지 않는 문자열을 따옴표로 묶어 검색한 결과입니다. API는 빈 results 배열, billing.charged: false, reason: empty_result_refunded, refund.status: succeeded와 함께 HTTP 200을 반환했습니다. 실패한 호출과 빈 결과 호출을 자체 기록과 대조하려면 실패 환불 대조 가이드를 참고하십시오.

테스트 3: 같은 쿼리를 10개국에서 보내면

gl 값을 location으로 옮기면 location이 제대로 동작할까요? SGT 기준 00:22부터 00:26까지 동일한 쿼리 "google search api"를 num을 10으로 설정해 web에 보냈습니다. location 값은 us, gb, de, fr, es, mx, br, jp, sg, in이었습니다. 10건의 호출 모두 HTTP 200을 반환했으며 비용은 건당 $0.000694, 총 $0.00694였습니다. US 호출은 결과 9개를 반환했고, 나머지 호출은 각각 10개를 반환했습니다.

미국 URL 9개를 기준으로 다른 국가 결과에 몇 개가 나타나는지 셌습니다. 싱가포르와 영국은 9개 모두 유지했습니다. 인도, 일본, 프랑스는 7개였습니다. 브라질과 스페인은 6개였습니다. 멕시코와 독일은 5개에 그쳤습니다.

독일에서는 .de 도메인의 개인 사이트와 YouTube 동영상이 추가되었습니다. 일본에서는 qiita.com이, 멕시코에서는 rapidapi.com이 추가되었습니다. 즉 국가 파라미터는 결과를 바꿉니다. 영어권 시장은 미국 목록과 가깝고 다른 시장은 더 멀어지는데, 지역별 순위를 생각하면 예상할 수 있는 결과입니다.

이 테스트는 한계도 보여 줍니다. EveryInfra location은 국가 단위까지만 지원하므로 국가 단위로만 테스트했습니다. Serper는 도시와 우편번호까지 지정할 수 있습니다. "뉴욕의 특정 ZIP 코드 지역 결과"가 필요하다면 EveryInfra web 도구로는 할 수 없습니다.

표본도 작습니다. 쿼리 하나에 국가당 호출 한 번입니다. 순위는 시간이 지나면서 바뀝니다. 겹침 수치는 파라미터가 동작한다는 것을 보여 줄 뿐, 국가 간의 장기적인 차이를 측정한 것은 아닙니다.

테스트 4: 지연 시간과 오류 응답 속도

요청 34건 전체를 결과별로 나누고, 싱가포르에서 네트워크 시간을 포함한 curl 총 소요 시간을 측정했습니다. 과금된 요청 21건은 0.98~3.48초가 걸렸고 중앙값은 1.81초였습니다. 가장 빠른 요청은 0.98초가 걸린 suggest였습니다. 가장 느린 요청은 SGT 00:45:40의 영국 web 호출로 3.48초였습니다. 빈 결과는 실제로 검색이 실행되었기 때문에 2.12초가 걸렸습니다.

거부된 요청 11건(401, 422, 429)은 0.09~0.20초 만에 반환되었습니다. 인증이나 파라미터 검사 단계에서 멈췄고 검색은 실행되지 않았습니다. Serper 홈페이지에는 "일반적으로 모든 쿼리는 1~2초 안에 반환됩니다"라고 되어 있습니다. Serper는 테스트하지 않았으므로 속도에 관해서는 아무 주장도 하지 않습니다.

차트는 처음 29건 요청을 다룹니다. 이 영어판을 위해 호출을 5건 더 했습니다. 이를 포함하면 과금된 호출 21건 전체의 중앙값은 1.81초입니다.

오류가 빨리 돌아오면 코드를 작성하는 사람에게 도움이 됩니다. 파라미터가 틀려도 2초씩 기다릴 필요가 없습니다. 수정 방법이 담긴 422가 0.1초 만에 도착하므로 어시스턴트는 한 턴 안에 고쳐서 다시 보낼 수 있습니다. 반대 경우도 마찬가지입니다. 200이 아닌 응답을 모두 "서비스 혼잡"으로 보고 재시도하는 프로그램은 422에 재시도를 낭비합니다. 429, 503처럼 retryable: true인 오류만 재시도하십시오.

테스트 5: 검색어 제안, 뉴스, 데이터 카탈로그 항목

Serper의 autocomplete와 news 유형은 EveryInfra의 suggest와 news 도구에 대응합니다. SGT 00:20:01에 "serper api key"로 suggest를 호출하자 10개 행이 반환되었습니다. 각 행에는 "serper api key free", "serper api key pricing", "serper api key crewai", "get serper api key"처럼 title만 있습니다. 비용은 $0.000694였습니다.

SGT 00:21:28에 "Model Context Protocol"로 news를 호출하자 결과 10개가 반환되었고, 모든 결과에 published가 있었습니다. 값은 "17 hours ago", "2 days ago" 같은 상대 시간이었습니다. 데이터베이스에서 날짜순으로 정렬하려면 요청 시각을 기준으로 변환해야 합니다. 또는 데이터 카탈로그의 google_news/search를 사용하면 $0.000792에 UTC ISO 8601 형식의 published_at을 받을 수 있습니다.

SGT 00:20:09에는 데이터 카탈로그 항목 web/search로 keyword, country: us, language: en을 지정해 "serper api key"를 검색했습니다. $0.001389에 결과 10개가 반환되었습니다. 이 항목에서는 결과 언어를 지정할 수 있습니다. 필드는 text와 rank이며, 카탈로그에 있는 다른 플랫폼의 검색 결과와 같은 구조입니다. 웹 결과를 다른 플랫폼 데이터와 함께 저장한다면 유용합니다. 웹 결과만 필요하고 언어 설정이 필요 없다면 web 도구가 절반 가격입니다.

web/search의 상위 세 결과는 Serper 홈페이지, 다른 검색 API의 홈페이지, serper.dev/api-keys였습니다. 일곱 번째는 Serper 대시보드에서 키를 찾는 방법을 다룬 Clay 커뮤니티 게시물이었습니다. 같은 쿼리를 web으로는 실행하지 않았으므로 결과 순서는 비교하지 않습니다. 두 항목이 같은 목록을 반환할 것이라고 기대하지 마십시오.

Python에서 키 설정하기: 프레임워크마다 다른 변수 이름

키는 코드가 아니라 환경 변수에 보관하십시오. The Twelve-Factor App과 OWASP Secrets Management Cheat Sheet 모두 이렇게 권합니다. 로컬 작업에서는 python-dotenv로 .env 파일을 읽고, 이 파일을 .gitignore에 추가해야 합니다. 문제는 Serper에 자체 SDK가 없어서 프레임워크마다 변수 이름을 따로 정한다는 점입니다. 프레임워크 네 개의 현재 소스와 문서를 확인했습니다.

Haystack은 이름에 "DEV"를 붙입니다. 한 머신에서 LangChain과 Haystack을 함께 쓴다면 변수를 두 개 설정하거나, Haystack에서 Secret.from_env_var("SERPER_API_KEY")로 지정하십시오. 파라미터 이름도 다릅니다. CrewAI의 SerperDevTool은 country, locale, n_results를 쓰고, 소스에서 이를 gl, hl, num으로 매핑합니다. 지원하는 유형은 search와 news뿐입니다.

2026년 11월 3일 1.15.35 릴리스 다음 날의 main 브랜치를 확인했습니다. LangChain은 k, gl, hl, type을 씁니다. Haystack은 top_k와 search_params를 씁니다. 결국 프레임워크를 연결할 때마다 변수 이름과 파라미터 이름을 새로 익혀야 합니다.

EveryInfra는 Python에서 별도 패키지가 필요 없습니다. Requests면 충분합니다. 코드에 이미 Serper 형식의 요청 본문이 있다면 작은 함수 하나로 EveryInfra 본문으로 바꿀 수 있습니다. 아래 함수는 2026년 11월 5일 SGT 00:47에 실행했습니다.

입력은 {"q": "serper api key rotate", "gl": "gb", "hl": "en", "num": 10, "tbs": "qdr:y", "autocorrect": true}였습니다. 출력은 {"tool": "web", "q": "serper api key rotate", "location": "gb", "num": 10, "page": 1, "after": "2025-11-04"}였습니다. 이 호출은 2.24초 만에 HTTP 200과 결과 10개를 반환했고 비용은 $0.000694였습니다. 결과 10개 모두 published 날짜가 2025년 11월 4일 이후였으므로 after 필터가 동작했습니다.

import datetime as dt, os, requests

URL = "https://api.everyinfra.com/api/v1/search"
TYPE_TO_TOOL = {"search": "web", "news": "news", "images": "media", "videos": "media",
                "places": "places", "maps": "places", "shopping": "shopping",
                "scholar": "scholar", "patents": "scholar", "autocomplete": "suggest",
                "lens": "lens", "webpage": "read"}
TBS_DAYS = {"qdr:h": 1, "qdr:d": 1, "qdr:w": 7, "qdr:m": 31, "qdr:y": 366}

def from_serper(serper_type, body, today=None):
    """Turn a Serper-style request into an EveryInfra search body."""
    tool = TYPE_TO_TOOL[serper_type]
    out = {"tool": tool, "q": body["q"]}
    if tool == "web":
        if "gl" in body:
            out["location"] = body["gl"]          # country code moves to location
        out["num"] = min(int(body.get("num", 10)), 10)
        out["page"] = int(body.get("page", 1))
        if body.get("tbs") in TBS_DAYS:
            today = today or dt.date.today()
            out["after"] = (today - dt.timedelta(days=TBS_DAYS[body["tbs"]])).isoformat()
    # hl, autocorrect and Serper's city-level location have no web-tool match: dropped
    return out

body = from_serper("search", {"q": "serper api key rotate", "gl": "gb", "hl": "en",
                              "num": 10, "tbs": "qdr:y", "autocorrect": True})
r = requests.post(URL, json=body, timeout=90,
                  headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"})
data = r.json()
if r.status_code != 200 and not data["error"].get("retryable"):
    raise ValueError(data["error"]["next_steps"])   # 401 and 422: fix, do not retry
print(len(data.get("results", [])), data.get("billing", {}).get("charged_usd"))

이 함수는 web 경로만 자세히 매핑합니다. media와 scholar는 먼저 카탈로그를 확인한 뒤 kind를 직접 추가하십시오. after는 날짜를 받으므로 qdr:h 행은 하루로 올림 처리됩니다.

n8n에서 키 설정하기: HTTP Request와 MCP Client Tool

n8n에는 Serper 전용 노드가 없습니다. 2026년 11월 5일 기준 n8n.io의 Serper 통합 페이지는 404를 반환했습니다. 사용자들은 범용 HTTP Request 노드를 사용합니다. 키는 이름이 X-API-KEY인 Header Auth 자격 증명에 넣습니다(n8n HTTP Request 자격 증명).

메서드는 POST로 설정하십시오. 위의 403 스레드는 GET 요청에서 나온 것입니다. 아래 설정은 2026년 11월 5일에 확인한 n8n 문서를 따릅니다.

EveryInfra는 두 가지 방법으로 연결할 수 있습니다. 첫 번째는 같은 HTTP Request 노드를 쓰는 방법입니다. Header Auth 이름은 Authorization으로, 값은 Bearer 와 공백 하나, 그리고 키로 설정합니다. URL은 https://api.everyinfra.com/api/v1/search로 설정하고, 본문은 curl 예제에서 복사합니다.

두 번째는 AI Agent 워크플로에서 MCP Client Tool 노드를 쓰는 방법입니다. 엔드포인트를 https://api.everyinfra.com/mcp로 설정하고, Bearer 인증을 선택한 뒤 키를 자격 증명에 저장합니다. 그러면 에이전트가 everyinfra_search 같은 도구 목록을 불러오고 언제 호출할지 스스로 판단합니다.

이 글을 위해 n8n을 직접 실행하지는 않았으므로, 두 설정 모두 n8n 문서를 바탕으로 한 구성 예시입니다. 매일 아침 실행되는 전체 워크플로는 n8n 일일 리포트 가이드를 참고하십시오.

MCP 클라이언트에서 키 설정하기: 원격과 로컬 비교

Serper는 MCP 서버를 운영하지 않습니다. GitHub에는 marcopesani/mcp-server-serper(MIT 라이선스, 스타 171개, 마지막 푸시 2025년 3월 13일), garylab/serper-mcp-server(스타 39개, 마지막 푸시 2025년 11월 10일) 같은 커뮤니티 서버가 있습니다. 둘 다 npx나 uvx로 사용자 컴퓨터에서 로컬 프로세스를 실행합니다. 키는 클라이언트 설정 파일의 env 블록에 SERPER_API_KEY로 들어갑니다. 따라서 클라이언트를 실행하는 모든 머신의 설정 파일에 키가 평문으로 저장됩니다.

EveryInfra는 https://api.everyinfra.com/mcp에서 원격 MCP 서버를 운영합니다. MCP 사양 2026-07-28 버전의 HTTP 전송 방식을 사용하며, 키는 Authorization 헤더에 넣습니다. Claude Code에서는 명령어 하나로 추가할 수 있습니다(Claude Code MCP 문서). 다른 클라이언트는 MCP 설정 페이지와 원격 MCP 설정 가이드를 참고하십시오.

claude mcp add --transport http everyinfra https://api.everyinfra.com/mcp \
  --header "Authorization: Bearer $EVERYINFRA_API_KEY"

도구 목록은 키 없이도 조회할 수 있습니다. SGT 00:21경 키 없이 tools/list를 호출해 도구 12개를 받았습니다. everyinfra_search의 입력은 17종 중 하나를 지정하는 tool과 params 객체입니다. SGT 00:21:40에는 일부러 q를 params 밖에 넣었습니다.

응답은 isError: true와 "missing_param: q is required", "Next steps: Add the required q. Nothing was charged."라는 텍스트가 담긴 HTTP 200이었습니다. SGT 00:21:58에는 {"tool":"web","params":{"q":"serper api login","location":"us","num":5}}를 보냈습니다. 결과 5개가 반환되었고, 첫 번째는 제목이 "Log in to your account"인 serper.dev/api-keys였으며, charged_usd는 API를 직접 호출할 때와 같은 0.000694였습니다.

MCP 사양에는 원격 서버의 인가(authorization)를 다루는 섹션이 있으며, OAuth를 권장합니다. EveryInfra는 현재 정적 Bearer 키를 사용합니다. 모든 클라이언트가 보낼 수 있는 방식이지만 키는 직접 지켜야 하며, 이것이 다음 섹션의 주제입니다. AI 에이전트용 검색 도구 유형을 고르려면 에이전트 검색 도구 선택 방법을 참고하십시오.

키가 유출되었다면: 양쪽에서 키를 교체하는 방법

최근 실제 사례부터 살펴보겠습니다. LiteLLM이 2026년 10월 23일 발표한 사고 보고서에 경위가 나와 있습니다. 2026년 5월 27일, 누군가 내부 관리자 키가 담긴 설정 파일을 공개 저장소에 커밋했습니다. 이 파일은 약 3시간 뒤 삭제되었고, 키는 "폐기 예정" 목록에 올랐습니다.

해당 커밋은 10월 22일까지 공개 이력에 남아 있었고, 사람의 실수로 폐기 작업은 끝내 이뤄지지 않았습니다. 2026년 10월 10일, 공격자는 4개월이 지났지만 여전히 유효한 이 키를 사용했습니다. 공격자는 이를 발판으로 GitHub 조직 소유자 토큰까지 손에 넣었습니다. 10월 21일, LiteLLM의 릴리스 파이프라인은 변조된 1.107.0을 배포했습니다(LiteLLM 사고 보고서).

보고서는 교훈으로 "노출되었을 가능성이 있는 키를 교체하지 않은 것"을 꼽습니다. 같은 날 Railway는 고객 환경 변수를 저장하는 시스템에 제3자가 접근했을 수 있다고 밝혔습니다. Railway는 모든 사용자에게 API 키를 포함해 Railway에 저장된 모든 환경 변수를 교체하라고 안내했습니다(Railway 공지, 2026년 10월 21일). 원칙은 간단합니다.

코드에서 키를 지워도 키는 무효화되지 않습니다. 서비스 측에서 기존 키를 무효화해야 합니다. 서비스별 방법은 다음과 같습니다.

Serper에서는 로그인한 뒤 API Keys를 엽니다. 유출된 키를 찾아 "Reset"을 클릭합니다. 확인하면 기존 키는 즉시 작동을 멈추고 페이지에 새 키가 표시됩니다. 기존 키를 쓰던 모든 곳에서 키를 교체합니다.

키 하나를 여러 곳에서 썼다면 한 곳만 따로 멈출 수 없으므로 모든 곳이 한꺼번에 중단됩니다. 그다음 Activity logs를 열고 해당 키로 필터링해 모르는 쿼리가 있는지 확인합니다. "Anonymize queries"를 켜 두었다면 로그에는 쿼리 수와 크레딧만 표시되고 쿼리 텍스트는 표시되지 않습니다.

EveryInfra에서는 콘솔에서 유출된 키를 비활성화합니다. 이후 해당 키로 보낸 호출은 401을 반환합니다. 스크립트로도 처리할 수 있습니다. keys:write 스코프가 있는 키로 POST /portal/api/keys/{key_id}/disable을 호출하면 됩니다. 비활성화된 키는 계정 소유자만 콘솔에서 다시 활성화할 수 있습니다. 대체할 새 키를 생성합니다. 환경마다 키를 하나씩 만들었다면 다른 환경은 계속 작동합니다.

키 교체, 스코프, IP 허용 목록은 콘솔에서만 변경할 수 있으므로 키가 자신의 설정을 바꿀 수 없습니다(빠른 시작, 인증 섹션). 그다음 호출 내역에서 유출 기간 중의 요청과 지출을 확인합니다. GET /api/v1/account로도 최근 24시간 사용량을 확인할 수 있으며, 비용은 들지 않습니다.

유출에 미리 대비할 수도 있습니다. 다음과 같이 키를 분리합니다:

이렇게 하면 어떤 키가 유출되더라도 그 키만 비활성화하면 됩니다. 다른 키는 계속 작동하고, 피해는 해당 키의 한도 안으로 제한됩니다.

유출을 대신 잡아 주는 곳은 없습니다. GitHub 시크릿 스캐닝은 저장소에서 알려진 형식의 키를 찾아 파트너 서비스에 알리고, 파트너 서비스가 키를 폐기할 수 있게 합니다. 2026년 11월 5일 지원 패턴 목록을 세어 보니 제공업체는 207곳이었고, Serper와 EveryInfra는 모두 목록에 없었습니다. TruffleHog 2026년 11월 2일 v3.99.8 릴리스에는 다른 SERP 서비스 3곳의 탐지기는 있지만 Serper용 탐지기는 없습니다. Gitleaks의 기본 규칙에도 없습니다.

GitHub는 2026년 10월 13일 Anthropic 키 유형 2가지를 기본 푸시 보호에 추가했습니다(GitHub 변경 내역). 2026년 10월 28일에는 고정된 형식 대신 문맥으로 판단하는 AI 기반 푸시 보호를 추가했습니다. 이 기능은 기본적으로 꺼져 있습니다(GitHub 변경 내역). 스캐너가 키 형식을 인식하기 전까지는 GitHub Advanced Security 사용자가 직접 사용자 지정 패턴을 작성할 수 있습니다.

변수 이름이 공개 코드에 얼마나 자주 등장하는지 확인해 보았습니다. SGT 00:45:51에 site: github.com 조건으로 "SERPER_API_KEY"를 검색했습니다. 결과 10개는 모두 공개 GitHub 페이지였습니다. 여기에는 CrewAI 403 이슈, 제목이 "configure the serper api key?"인 h2oGPT 이슈, 커뮤니티 MCP 서버 2개가 포함되어 있었습니다.

NVIDIA 블루프린트 README와 2026년 7월 21일 Hermes Agent 기능 요청도 있었습니다. 공개 코드에 변수 이름이 있는 것은 흔하며 안전합니다. 위험은 커밋된 .env 파일에 이름과 값이 나란히 있을 때 시작되며, 기본 스캐너는 이 값을 잡아내지 못합니다.

Serper가 더 나은 선택인 경우

EveryInfra보다 Serper가 더 적합한 경우는 다음과 같습니다.

첫째, 도시, 동네, 우편번호 단위의 지역 검색 결과입니다. Serper의 위치 목록은 우편번호 단위까지 100,029개 항목을 제공하지만, EveryInfra location은 국가 단위까지만 지원합니다. 지역 SEO 순위 추적이나 도시별 결과 확인에는 Serper가 맞습니다. 둘째, 지식 패널, "People also ask", 관련 검색 같은 결과 페이지 모듈입니다. Serper는 knowledgeGraph, peopleAlsoAsk, relatedSearches를 필드로 반환합니다.

EveryInfra web 도구는 제목, 링크, 스니펫, 날짜만 반환합니다. 셋째, 높은 처리량입니다. Serper의 팩은 초당 50~300개 쿼리를 허용합니다. EveryInfra 계정은 기본적으로 분당 60건, 속도 팩을 추가하면 분당 최대 1,800건까지 허용합니다(요금). 1초에 수백 건을 보내야 한다면 Serper가 훨씬 유리합니다.

넷째, 지도 리뷰와 상품 리뷰입니다. Serper는 reviews, product-reviews, maps를 검색 유형으로 제공합니다. EveryInfra 검색에는 이런 도구가 없으므로 플랫폼마다 데이터 카탈로그에서 맞는 기능을 찾아야 하고, 그만큼 설정 작업이 늘어납니다. 다섯째, 요청 하나에 최대 100개 쿼리를 담는 배치 요청입니다.

Serper의 Mini-batch는 이를 지원하지만, EveryInfra 검색은 호출 한 번에 쿼리 하나를 받습니다. 여섯째, 이미 Serper의 필드를 기반으로 구축했고 미국 영어 결과만 필요한 대규모 코드베이스입니다. 이 경우 코드 변경 비용이 절감액보다 클 수 있으므로 기다리는 편이 낫습니다. AI 에이전트에 검색을 추가할 때나, 데이터, 검색 등 여러 기능을 키 하나로 쓰고 싶을 때 전환을 고려해 보십시오.

한계: 이 결과가 성립하지 않는 경우

첫째, 로그인 후 대시보드에 관한 Serper 내용은 직접 본 화면이 아니라 페이지 스크립트의 텍스트를 근거로 합니다. 스태프 계정만 쓸 수 있는 유형처럼 스크립트에는 있지만 화면에 표시되지 않는 기능은 제외했습니다. 스크립트에 언급되지 않은 서버 기능도 확인할 수 없습니다. 둘째, Serper 오류 본문은 2025년 7월~2026년 10월에 작성된 제3자 게시물에서 가져왔으므로 바뀌었을 수 있습니다. 셋째, EveryInfra 회원가입 이후 절차와 키 기능은 웹페이지, 문서, 요금 페이지, OpenAPI 파일을 바탕으로 작성했습니다. 새 계정을 만들지 않았고, 스코프가 제한된 키로 호출해 403을 직접 확인하지도 않았습니다.

넷째, 34회 호출에는 일반 계정과 달리 분당 10회로 제한된 테스트 키를 사용했습니다. 다섯째, 위치 및 지연 시간 테스트는 싱가포르에서 측정한 단일 샘플입니다. 여섯째, 결과 품질이나 커버리지는 비교하지 않았습니다.

FAQ

앱에서 Serper API 키는 어떻게 설정하나요?

환경 변수로 설정한 뒤, 사용 중인 프레임워크가 어떤 이름을 읽는지 확인합니다. LangChain, CrewAI, LiteLLM은 SERPER_API_KEY를 읽습니다. Haystack은 SERPERDEV_API_KEY를 읽습니다. 제목이 "configure the serper api key?"인 h2oGPT 이슈(h2oai/h2ogpt #914)에서 흔한 실수를 볼 수 있습니다.

사용자가 코드에서 변수 이름을 넣어야 할 자리에 키를 붙여 넣었습니다. 앱은 여전히 실패했고, 다른 키를 요구하는 유효성 검사 오류가 발생했습니다.

Serper 무료 티어는 월 2,500건인가요?

Serper 홈페이지에는 "Get 2,500 free queries"라고만 적혀 있고 "매월"이라는 표현은 없습니다. 2026년 7월 21일 Hermes Agent 기능 요청에서는 이를 "2,500 free queries/month"라고 표현합니다(NousResearch/hermes-agent #68615). 회원가입 후 대시보드를 확인하고, 매월 초기화된다고 가정해 계획하지 마십시오. 약관은 동시에 2개 이상의 계정을 보유하는 것도 금지합니다. 2,500건으로 얼마나 쓸 수 있는지는 Serper API 무료 티어를 참고하십시오.

CrewAI에서 Serper 키를 쓰면 왜 403 Unauthorized가 반환되나요?

먼저 키가 serper.dev에서 발급된 것인지 확인합니다. CrewAI 이슈 #633의 사용자는 다른 서비스의 키를 쓰고 있었습니다. 다음으로 변수 이름이 CrewAI 소스 코드가 직접 읽는 SERPER_API_KEY인지, 요청이 POST를 사용하는지 확인합니다. 본문에 "Unauthorized. Sign up for a free account."가 표시되면 키가 잘못되었거나 누락된 것입니다. CrewAI 이슈 #633을 참고하십시오.

Serper API 전체 레퍼런스가 있나요?

2026년 11월 5일 기준으로 찾지 못했습니다. serper.dev/docs, /llms.txt, /openapi.json은 404를 반환했고, GitHub 조직에도 SDK가 없습니다. 파라미터, 유형, 크레딧 비용은 플레이그라운드에서 확인할 수 있으며, 플레이그라운드는 샘플 코드도 생성합니다. CrewAI, LangChain, Haystack, LiteLLM, Langflow의 프레임워크 문서가 각각 일부를 다룹니다.

Serper API 로그인에 Google이나 GitHub 계정을 쓸 수 있나요?

회원가입 및 로그인 스크립트에서 서드파티 로그인은 찾지 못했습니다. Serper 로그인은 이메일과 비밀번호 방식이며, 2단계 인증은 선택 사항입니다. EveryInfra는 이메일, GitHub, Google 로그인을 지원합니다.

시작하기: 키 발급부터 첫 결과까지

사용해 보려면 everyinfra.com에서 회원가입합니다. GitHub 저장소 2곳에 스타를 누르고 콘솔에서 $1 체험용 크레딧을 받습니다. 크레딧은 24시간 동안 유효합니다. API Keys에서 키를 생성하고, 위의 curl 요청을 보낸 뒤 응답의 billing.charged_usd를 확인합니다. 파라미터를 무료로 확인하려면 검색 도구 카탈로그를 엽니다. 데이터 카탈로그의 검색 기능은 웹 데이터 플랫폼 페이지, Bing, DuckDuckGo, Google News, Google Shopping을 참고하십시오. 콘솔에서 클릭 한 번으로 호출을 시험하려면 인프라 마켓플레이스를 이용하십시오.

Serper에서 옮겨 오는 경우 다음 항목을 이 순서대로 변경합니다. 마지막 행은 변경 사항이 아니라 오류 처리 테스트입니다.

더 넓게 비교하려면 대안과 EveryInfra를 선택하는 이유를 참고하십시오.

참고 자료

1. Serper 홈페이지(요금, FAQ, 샘플 응답), Serper, 2026-11-05 확인
2. Create an account, Serper, 2026-11-05 확인
3. “Log in to your account”, Serper, 2026-11-05 열람
4. API Keys, Serper, 2026-11-05 확인(로그아웃 상태에서는 로그인 양식)
5. 플레이그라운드, Serper, 페이지 스크립트 2026-11-05 확인
6. Terms of Service, Serper, 2024-05-29 업데이트, 2026-11-05 확인
7. Privacy Policy, Serper, 2025-11-05 검토, 2026-11-05 확인
8. Supported locations, Serper, 2026-11-05 확인
9. Serper-API GitHub 조직, GitHub, 2026-11-05 확인
10. serper.dev 웹 아카이브 인덱스, Internet Archive, 2026-11-05 확인
11. postman-code-generators, Postman, 2026-11-05 확인
12. Serper.dev authentication issues, n8n 커뮤니티, 2025-07-26
13. Unauthorized Error (403) when Using SERPER_API_KEY #633, CrewAI, 2024-05-17
14. configure the serper api key? #914, h2oGPT, 2023-10-01
15. Add Serper.dev web search provider plugin #68615, Hermes Agent, 2026-07-21
16. Research: read a spent plan or refused key as what it is #339, GitHub, 2026-10-23
17. Live checks with real keys before release #12, GitHub, 2026-10-22
18. Google Serper Search (SerperDevTool), CrewAI, 2026-11-05 확인
19. serper_dev_tool.py, CrewAI, 2026-11-05 확인
20. CrewAI 1.15.35, CrewAI, 2026-11-03
21. GoogleSerperAPIWrapper, LangChain, 2026-11-05 확인
22. google_serper.py, LangChain, 2026-11-05 확인
23. SerperDevWebSearch, deepset, 2026-11-05 확인
24. Haystack serperdev websearch.py, deepset, 2026-11-05 확인
25. Serper Search, LiteLLM, 2026-11-05 확인
26. Serper bundle, Langflow, 2026-11-05 확인
27. HTTP Request node, n8n, 2026-11-05 확인
28. HTTP Request credentials, n8n, 2026-11-05 확인
29. MCP Client Tool node, n8n, 2026-11-05 확인
30. n8n 2.46.6, n8n, 2026-11-04
31. mcp-server-serper, GitHub, 2026-11-05 확인
32. serper-mcp-server, GitHub, 2026-11-05 확인
33. Model Context Protocol Specification 2026-07-28, MCP, 2026-11-05 확인
34. MCP Authorization, MCP, 2026-11-05 확인
35. Connect Claude Code to tools via MCP, Anthropic, 2026-11-05 확인
36. RFC 9110: HTTP Semantics, IETF, 2022-06
37. RFC 6585: Additional HTTP Status Codes, IETF, 2012-04
38. RFC 9457: Problem Details for HTTP APIs, IETF, 2023-07
39. 422 Unprocessable Content, MDN, 2026-11-05 확인
40. Retry-After, MDN, 2026-11-05 확인
41. Supported secret scanning patterns, GitHub, 2026-11-05 확인
42. Secret scanning blocks Anthropic keys by default, adds Salesforce, GitHub, 2026-10-13
43. Push protection beyond predefined secret patterns, GitHub, 2026-10-28
44. “Defining custom patterns for secret scanning”, GitHub, 2026-11-05 열람
45. TruffleHog v3.99.8, Truffle Security, 2026-11-02
46. Gitleaks, Gitleaks, 2026-11-05 확인
47. The attack chain behind the v1.107.0 LiteLLM release, LiteLLM, 2026-10-23
48. Security Disclosure: Wednesday October 21st, Railway, 2026-10-21
49. How to Retrieve Your API Key from Serper.dev Dashboard, Clay 커뮤니티, 2025-05-10
50. Secrets Management Cheat Sheet, OWASP, 2026-11-05 확인
51. The Twelve-Factor App: Config, 12factor.net, 2026-11-05 확인
52. python-dotenv, PyPI, 2026-11-05 확인
53. Requests Quickstart, Requests, 2026-11-05 확인
54. EveryInfra 검색 도구 카탈로그, EveryInfra, 2026-11-05 00:16 SGT 확인
55. EveryInfra 데이터 기능 카탈로그, EveryInfra, 2026-11-05 00:16 SGT 확인
56. EveryInfra OpenAPI, EveryInfra, 2026-11-05 확인