메인 콘텐츠로 건너뛰기
모니터는 한 번만 만들면 됩니다. 실행마다 일반 비동기 태스크 세트가 만들어지고 각 엔진의 가격으로 과금됩니다. 이 페이지는 모니터를 만들고, 실행하고, 관리하는 방법을 다룹니다. 숫자를 읽는 방법은 리포트와 지표, 그 뒤의 답변은 출처와 답변, 웹훅과 이메일 알림은 이벤트와 알림에 있습니다. 같은 데이터를 대시보드로 보려면 제품 페이지를 참고하세요.

브랜드 모니터와 카테고리 모니터

모니터에는 mode가 있습니다. 저장된 모든 답변의 의미를 정하므로 생성할 때 정하고 이후에는 바꿀 수 없습니다. 답변은 도착할 때 한 번 채점합니다.
  • 언급: 내 별칭 중 하나가 답변 텍스트에 나타납니다. position은 처음 일치한 곳의 문자 오프셋이며, 브랜드가 없으면 null입니다.
  • 인용: 답변이 내 domains 중 하나 또는 그 하위 도메인의 페이지를 인용합니다.
  • 경쟁사 히트: 모니터의 경쟁사 중 같은 답변에 나타난 곳입니다.
이 점수에는 감성도, 시장 점유율 추정도 없습니다. 카테고리 모니터의 순위는 답변이 언급한 브랜드 사이의 자리일 뿐입니다. 답변별 감성과 추천을 보려면 analysis를 켜세요.

빠른 시작

1

모니터 만들기

모니터를 만들면 바로 첫 실행이 시작됩니다.
응답은 저장된 모니터와 함께 201입니다. data.monitor.id를 보관하세요.
2

답변 기다리기

태스크는 요금제의 동시 실행 한도가 허용하는 만큼 들어가므로, 실행 결과는 몇 초에서 몇 분에 걸쳐 도착합니다. 리포트의 health.pending이 아직 진행 중인 태스크 수를 셉니다. 0이 되면 리포트를 읽으세요.
3

리포트 읽기

quality를 먼저 읽고, 그다음 stats, brands, opportunities를 보세요. 모든 필드는 리포트와 지표에서 설명합니다.
다음 예약 실행 전에 답변이 필요하면 POST /v1/monitors/{id}/run을 호출하세요.

모니터 만들기

POST /v1/monitors(레퍼런스)는 정의를 검증하고, 계정 한도와 대조하고, 저장한 뒤 첫 실행을 시작합니다. 호출은 그 실행이 끝나기 전에 201을 반환합니다. 첫 실행을 시작할 수 없더라도(예: 잔액 부족) 모니터는 만들어지고, 스케줄러가 매분 실행을 다시 시도합니다. 예를 들어 빠른 시작의 요청은 다음을 반환합니다.

요청 필드

목록 필드는 모두 JSON 배열이나 줄바꿈으로 구분한 문자열 하나를 받습니다. 항목은 앞뒤 공백을 자르고, 빈 항목은 버리고, 중복은 제거합니다.

엔진

모니터는 프롬프트 기반 답변 엔진을 예약할 수 있습니다: CHATGPT, GEMINI, PERPLEXITY, GOOGLE (Google AI Overviews), AIMODE(Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB, 그리고 기존 모니터를 위해 남겨 둔 지원 중단 이름 NAVER. 별칭 GOOGLE_AIO, GOOGLE_AIMODE, NAVER_AI_MODE는 받아서 각각 GOOGLE, AIMODE, NAVER_AI_TAB으로 저장합니다. 엔진 이름은 대소문자를 구분합니다. GOOGLE_SERP나 CITATION_ANALYSIS 같은 검색, 웹 데이터, 분석 태스크 유형은 예약할 수 없습니다. 가격과 엔진별 상세는 엔진 카탈로그에 있습니다. 일부 엔진으로 제한된 API 키는 그 엔진을 쓰는 모니터만 만들고, 수정하고, 실행할 수 있습니다. 그 밖에는 403 KEY_SCOPE_DENIED를 반환합니다.

경쟁사

경쟁사를 직접 입력하지 않아도 됩니다. 첫 실행이 끝나면 매주 모니터의 최근 답변을 읽어, 내 브랜드와 같은 것을 팔면서 두 개 이상의 답변에 나온 브랜드를 추가합니다. 브랜드 모니터는 최대 15곳, 카테고리 모니터는 25곳입니다.
  • 찾아낸 경쟁사는 source: "auto", 직접 입력한 경쟁사는 source: "user"입니다. 직접 입력한 항목은 분석이 바꾸거나 지우지 않습니다. 찾아낸 브랜드가 다음 두 번의 분석에서 연속으로 보이지 않으면 빠집니다.
  • 찾아낸 목록이 바뀌면 모니터에 저장된 답변을 새 목록으로 다시 채점합니다. 그래서 한 리포트의 모든 브랜드는 같은 답변을 기준으로 측정됩니다. 마지막 분석 시각은 competitorsReadAt에 있습니다.
  • 수정할 때 competitors는 직접 입력한 목록을 바꾸고 찾아낸 목록은 유지합니다. 요청의 source: "auto" 항목은 무시하므로 GET이 반환한 값을 그대로 돌려보내도 됩니다.

이름 일치 방식

  • 대소문자와 문자 폭(NFKC)을 무시하고 비교합니다.
  • 라틴 문자 이름은 단어 단위로만 일치합니다. “replicates”는 브랜드 Replicate의 언급이 아닙니다. 이름에 붙은 한글, 가나, 한자, 태국 문자는 단어 경계로 보므로 “agoda를”과 “ahamoが”는 agoda와 ahamo의 언급입니다. 한국어, 일본어, 중국어, 태국어 이름은 텍스트 어디서든 일치합니다.
  • 한 글자 이름은 일치하지 않습니다. 그런 브랜드에는 더 긴 별칭을 주세요.
  • 두 이름이 겹치면 먼저 시작하는 것, 그다음 더 긴 것을 셉니다. “Acme Pro”라는 경쟁사 안의 “Acme”는 경쟁사로 셉니다.
  • 링크 대상, 그대로 적힌 URL, 인용 칩은 비교 전에 제거하고, 링크의 보이는 텍스트는 남깁니다. 인용은 언급이 아니라 cited에 반영됩니다.

측정이 되는 프롬프트 쓰기

  • 주제와 시장마다 모니터 하나를 두세요. “최고의 CRM”과 “CRM 가격은 어떻게 정하나”는 서로 다른 의도이며, 평균하면 둘 다 가려집니다.
  • 프롬프트는 구매자의 말투로 쓰고 내 브랜드를 절대 넣지 마세요. 브랜드가 든 프롬프트는 항상 언급으로 잡혀 100%를 보고하고 아무것도 측정하지 못합니다. 프롬프트에 경쟁사 이름은 넣어도 됩니다.

샘플과 엔진별 주기

AI 답변은 세션마다 달라지므로 답변 하나보다 여러 답변 중 비율이 더 안정적입니다. engineSettings는 엔진마다 프롬프트당 받을 답변 수와 엔진의 실행 빈도를 정합니다.
  • samples: 실행마다 프롬프트와 지점별로 받는 답변 수, 1–10(기본값 1). 답변마다 별도 세션의 태스크이며 다른 태스크처럼 채점하고 과금합니다.
  • intervalHours: 모니터 intervalHours의 배수, 최대 168. 엔진은 k번째 실행마다 참여하며, 모든 엔진이 참여하는 첫 실행부터 셉니다.
항목은 모니터의 엔진 중 하나만 지정할 수 있고 위 두 키만 받습니다. 수정할 때 engineSettings는 저장된 값을 교체합니다. 엔진을 뺀 수정은 그 엔진의 항목도 지우고, 모니터의 intervalHours를 바꾼 수정은 엔진 간격을 새 값으로 다시 확인합니다.

위치와 그리드

기본적으로 모든 태스크는 국가 전체를 기준으로 질문합니다. 지역 답변을 측정하려면 다음을 쓰세요.
  • location은 모든 프롬프트를 한 지점(십진 도 단위)에서 질문합니다.
  • grid는 모든 프롬프트를 center 주변 정사각형 그리드의 각 지점에서 질문합니다. size는 한 변의 지점 수로 3, 5, 7, 9 중 하나입니다(9–81개 지점). radiusMeters(100–50,000)는 중심에서 변의 가운데까지의 거리입니다.
위치 기준으로 답하는 엔진은 CHATGPT, GEMINI, GOOGLE, AIMODE뿐입니다. 위치나 그리드가 있는 모니터에 다른 엔진이 있으면 400 VALIDATION_ERROR로 거절합니다. 수정할 때 location과 grid 중 하나를 설정하면 다른 하나는 지워지고, null을 보내면 지워집니다. 지점별 답변은 GET /v1/monitors/{id}/grid로 읽으세요.

답변 페이지

태스크가 페이지를 저장한 답변은 그 주소가 display.html에 실리고, 드로어가 폰트를 넣은 파일로 내려줍니다. 페이지는 마크다운을 다시 그린 것이 아니라 엔진의 실제 화면입니다. 모니터 실행은 페이지를 요청하지 않으므로 그 답변에는 페이지가 없습니다. 그래도 어떤 태스크가 페이지를 남겼다면 주소는 그 태스크에서 읽어 오므로 답변에서 계속 열 수 있습니다.

비용과 일정

실행 한 번은 참여하는 엔진마다 프롬프트, 지점, 샘플별로 태스크 하나를 만듭니다.
그리드가 없으면 points는 1입니다. 예를 들어 프롬프트 12개를 CHATGPT(1크레딧)와 GOOGLE(1.25크레딧)에 보내면 실행당 24개 태스크, 27크레딧이고, 매일 실행하면 월 약 810크레딧입니다. "CHATGPT": { "samples": 5 }를 더하면 같은 모니터가 실행당 72개 태스크, 75크레딧입니다. 가격은 하드코딩하지 말고 GET /v1/monitors/capabilities에서 읽으세요. 크레딧을 잡아 두고 청구하는 방식은 크레딧과 한도에 있습니다. 태스크 외에 두 가지 비용이 더 붙습니다.
  • 경쟁사 분석: 모니터당 30일에 80크레딧이며, 실행 주기에 맞춰 각 실행에 나눠 청구합니다(매일 실행하는 모니터는 실행당 약 2.67크레딧, 매주 실행하는 모니터는 18.67크레딧). 실행의 태스크가 모두 제출된 뒤에 청구하므로, 잔액 부족으로 멈춘 실행에는 청구되지 않습니다.
  • 답변 분석: analysis: true이면 태스크당 1크레딧이며, 분석한 답변에만 청구합니다. 점수(mentioned, cited, position)는 그대로이고, 답변별 결과는 GET /v1/monitors/{id}/answers/{taskId}의 answer.analysis에 있습니다.
location이나 grid가 있는 모니터는 태스크마다 1크레딧이 더해집니다. 리포트, 출처, 답변, 결과를 읽는 데는 비용이 들지 않습니다.
일정은 모니터를 일시정지하거나 삭제할 때까지 반복됩니다. 위의 월 비용이 모니터를 만들 때 약속하는 금액입니다.
일정은 다음과 같이 동작합니다.
  • 실행은 한꺼번에 몰리지 않습니다. 태스크는 요금제의 동시 실행 한도와 엔진 큐가 허용하는 만큼 제출됩니다. 스케줄러는 매분 멈춘 곳에서 이어 가며 엔진마다 한 건씩 번갈아 넣고, 여러 계정의 모니터도 차례를 나눕니다. 상위 계정과 하위 계정은 차례 하나를 공유합니다.
  • 실행은 간격 안에 들어가야 합니다. 한 엔진의 태스크를 그 엔진의 다음 실행 전까지 모두 넣을 수 없으면, 생성과 수정이 맞는 가장 짧은 간격을 알려 주며 400 VALIDATION_ERROR를 반환합니다. 한 간격이 지나도록 제출 중인 실행은 종료되고 남은 태스크는 보내지 않습니다.
  • 놓친 실행은 다시 돌리지 않습니다. nextRunAt은 다음 실행이 도래하는 시각입니다. 일시정지한 모니터를 재개하거나 intervalHours를 바꾸면 그 시점부터 한 간격 뒤로 다음 실행을 잡습니다.

기능 조회

GET /v1/monitors/capabilities(레퍼런스)는 내 계정 기준으로 예약 가능한 엔진별 creditsPerTask, analysisCreditsPerTask, placeCreditsPerTask, 내 limits, modes, 지표 정의(metrics), 일정 비용 공식, 변화 이벤트 유형을 반환합니다. 부작용이 없고 비용도 들지 않으므로, 프로그램으로 모니터를 만들기 전에 호출하세요.

프롬프트 고르기

브랜드 정보로 프롬프트 제안받기

POST /v1/monitors/suggest(레퍼런스)는 country의 구매자가 물을 법한 후보 프롬프트를 최대 12개 반환합니다. 아무것도 저장하지 않고 크레딧을 쓰지 않습니다.
예를 들면 다음과 같습니다.
브랜드 이름이나 별칭이 든 제안은 제거합니다. 모니터를 만들기 전에 목록을 검토하세요. 제안은 20초에 한 번, 시간당 30번까지 요청할 수 있고, 넘으면 429 RATE_LIMITED를 반환합니다. 모델이 브랜드를 거절하면 400 SUGGEST_FAILED, 제안 서비스가 실패하면 502 SUGGEST_FAILED, 설정되어 있지 않으면 503 SUGGEST_FAILED를 반환합니다.

검색 수요로 프롬프트 리서치

POST /v1/monitors/research(레퍼런스)는 Prompt Research의 요청 본문을 받고, 같은 14크레딧을 쓰고, 같은 결과를 계정 소유의 태스크로 반환합니다.
응답의 data.task에 큐에 들어간 태스크가 있고, data.credits와 data.replayed가 함께 옵니다. 결과는 data.task.id로 GET /v1/async/task/{id}를 호출해 읽으세요(비동기 태스크 참고). 그런 다음 prompts[].prompt를 순서대로 prompts에 넣어 모니터를 만드세요. 카테고리 모니터라면 리서치에 코어가 둘 이상일 때 각 프롬프트의 core를 promptTopics의 항목으로 쓰고, brands[].brand를 competitors로 씁니다. 모니터를 만들기 전까지는 아무것도 저장되지 않습니다. 한 번 실행은 계정의 tasksPerRun 한도까지만 태스크를 큐에 넣을 수 있고, 엔진마다 프롬프트 × 위치 지점 × samples로 셉니다. 실제로 만들 모니터에 맞춰 limit을 정하세요. 리서치에서 모니터로를 참고하세요.

카테고리 모니터

카테고리 모니터는 한 시장에서 엔진이 언급하는 브랜드의 순위를 냅니다. 프롬프트는 promptTopics로 세부 분야별로 묶습니다.
카테고리 모니터에는 자체 브랜드가 없습니다. aliases, domains, alertBelowPct는 비워야 하며, 값을 보내면 400 VALIDATION_ERROR를 반환합니다. 알림도 없습니다. GET /v1/monitors에서 stats.mentioned와 stats.cited는 항상 0이고, 목록에 최근 30일 동안 가장 많이 언급된 브랜드인 leader가 더해집니다. 리포트는 카테고리 리포트에서 설명합니다. 일정, 비용, 출처, 답변, 결과, 변화 이벤트는 브랜드 모니터와 같게 동작하지만, 카테고리 모니터는 monitor.source.first_cited 이벤트만 보냅니다. 수정할 때 prompts를 바꾸면 제거한 프롬프트의 promptTopics 항목도 지워집니다. 그 프롬프트로 수집한 답변은 순위표에 남습니다.

모니터 관리

GET /v1/monitors/{id}의 예전 기간 요약은 호환성을 위해 남겨 두었습니다. 숫자는 /analytics를 쓰세요. 예전 요약은 프롬프트와 엔진별 최신 답변의 전체 기간 행렬을 기간별 숫자에 섞고, 출처를 도메인 12개와 페이지 20개에서 자르며, shareOfVoice가 각 브랜드를 전체 답변 기준으로 세므로 점유율의 합이 100을 넘을 수 있습니다. 다른 계정의 모니터는 403이 아니라 404 NOT_FOUND를 반환합니다.

모니터 수정

PATCH는 생성 필드의 일부를 받아 결과 전체를 같은 한도로 검증합니다. 생략한 필드는 값을 유지합니다.
  • enabled: false는 모니터를 일시정지하고, enabled: true는 지금부터 한 간격 뒤를 다음 실행으로 잡아 재개합니다. 일시정지는 리포트에 pauses로 나타납니다.
  • alertBelowPct를 바꾸면 알림이 다시 활성화됩니다.
  • 별칭, 도메인, 경쟁사를 바꾸면 그 이후에 채점하는 답변부터 적용됩니다. 저장된 답변은 채점 당시의 정의를 유지하므로, 리포트는 변경 전후 비교를 보류합니다(리포트와 지표 참고).

지금 실행하기

POST /v1/monitors/{id}/run은 다음 실행을 즉시 도래시킵니다. 스케줄러가 약 1분 안에 시작하며 data.queued: true를 반환합니다. 이 실행은 예약 실행처럼 과금됩니다. 그 실행이 아직 도래 상태인 동안 다시 호출해도 두 번째 실행은 만들어지지 않습니다. 큐에 넣기 전에 경쟁사 분석과 답변 분석 크레딧을 포함해 잔액이 실행 비용을 감당하는지 확인합니다. 부족하면 details.needed와 details.available을 담아 402 INSUFFICIENT_CREDITS를 반환합니다. 월 크레딧 한도를 넘은 하위 계정은 429 SUB_ACCOUNT_CREDIT_LIMIT을 받습니다. 일시정지한 모니터는 404 NOT_FOUND를 반환하므로 먼저 재개하세요.

리포트 공유

모니터 하나의 리포트를 https://querying.ai/<slug>에 게시할 수 있습니다. 공유 리포트는 분석, 출처, 인용, 결과, 답변을 보여 주며, 설정, 알림, 실행 제어, 계정의 태스크 상태는 절대 보여 주지 않습니다. GET /v1/monitors/{id}/share(레퍼런스)는 현재 상태인 access, slug, locale, url을 반환하고, slug가 없으면 suggestedSlug를 더합니다. PUT /v1/monitors/{id}/share(레퍼런스)로 변경합니다.
access를 PRIVATE로 바꾸면 리포트가 내려가지만 slug는 유지되므로, 공유를 다시 켜면 같은 주소를 씁니다.

에이전트에서 모니터 쓰기

MCP 서버는 모니터를 도구로 제공합니다: get_monitor_capabilities, list_monitors, get_monitor, create_monitor, update_monitor, delete_monitor, run_monitor, get_monitor_analytics, get_monitor_sources, get_monitor_results, get_monitor_answer, suggest_monitor_prompts, get_monitor_alerts, test_monitor_alert. 각 도구는 내 키로 API를 한 번 호출합니다. 에이전트나 스크립트가 따를 수 있는 실용적인 순서입니다.
  1. GET /v1/monitors/capabilities: 무엇이든 쓰기 전에 엔진, 가격, 한도를 읽습니다.
  2. GET /v1/monitors: 해당 주제와 시장의 모니터를 재사용하거나 새로 만듭니다. POST /v1/monitors/suggest에서 시작해도 됩니다.
  3. POST /v1/monitors/{id}/run: 다음 예약 실행 전에 답변이 필요할 때만 호출합니다.
  4. GET /v1/monitors/{id}/analytics?days=30: 숫자보다 quality를 먼저 읽고, health.pending이 0이 될 때까지 기다립니다.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: nextCursor를 끝까지 따라갑니다.
  6. GET /v1/monitors/{id}/answers/{taskId}: 행동하기 전에 opportunities 최상단 항목 뒤의 답변을 엽니다.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv: 같은 기간을 내보내며 x-next-cursor가 빌 때까지 따라갑니다.

한도

계약 계정은 동시 실행 한도를 별도로 협의한 계정입니다. 다음은 모든 계정에 적용됩니다. 리포트, 페이지 크기, 보관 한도는 해당 페이지에 있습니다: 리포트와 지표, 출처와 답변, 이벤트와 알림.

오류

오류 봉투는 다른 곳과 같습니다(오류 참고). 모니터에만 해당하는 코드는 다음과 같습니다.

다음 단계

리포트와 지표

/analytics 계약과 각 숫자의 의미.

출처와 답변

인용된 페이지, 각 점수 뒤의 답변, 내보내기.

이벤트와 알림

답변이 바뀔 때의 웹훅과 언급률 이메일 알림.

Prompt Research

검색 수요로 추적할 만한 프롬프트를 찾습니다.