GEO 모니터링 API: 브랜드 언급과 인용

​

모니터란

• 답변 텍스트에 브랜드 별칭이 나타나는지와 그 문자 오프셋, 답변이 등록된 내 도메인 중 하나를 인용했는지, 설정한 경쟁사 중 어느 곳이 같은 답변에 나타났는지를 기록합니다.
• 감성 점수와 시장 점유율 추정치는 만들지 않습니다. 순위는 답변이 언급한 브랜드 사이의 자리이며, 아래 카테고리 모니터의 브랜드 순위가 그 예입니다.

​

경쟁사는 자동으로 찾습니다

• 찾아낸 경쟁사는 source: "auto", 직접 추가한 경쟁사는 source: "user"입니다. 직접 추가한 항목은 분석이 바꾸거나 지우지 않습니다.
• 찾아낸 목록이 바뀌면 모니터에 저장된 답변을 새 목록으로 다시 셉니다. 그래서 한 리포트의 모든 브랜드는 같은 답변을 기준으로 측정됩니다. 마지막 분석 시각은 모니터의 competitorsReadAt에 있습니다.
• 라틴 문자 이름은 단어 단위로 일치시킵니다. 예를 들어 “replicates”는 브랜드 Replicate의 언급으로 세지 않습니다.

​

모니터 세트는 의도를 갖고 나누세요

• 주제와 시장마다 모니터 하나를 두어 리포트의 코호트를 비교 가능하게 유지하세요. “최고의 CRM”과 “CRM 가격은 어떻게 정하나”를 한 세트에 섞으면 서로 다른 두 의도가 한 숫자로 평균됩니다.
• 프롬프트는 구매자의 말투로 쓰고 내 브랜드를 절대 넣지 마세요. 브랜드가 든 프롬프트는 항상 언급으로 잡혀 영원히 100%를 보고하고 아무것도 측정하지 못합니다. 경쟁사 이름은 괜찮으며, 쓸 수 있는 가장 유용한 프롬프트인 경우가 많습니다.

​

카테고리 모니터: 시장 속 브랜드의 순위

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

리포트가 순위를 매기는 방식

• **rank**는 브랜드를 언급한 답변 수로 순서를 매깁니다. 이 답변들이 언급한 브랜드 사이의 자리입니다. 어느 답변도 언급하지 않은 브랜드의 rank는 null입니다.
• **브랜드의 mentionRate**는 그 브랜드 자체의 sampleSize(브랜드가 목록에 있는 동안 채점된 답변)로 나눕니다. 오늘 추가한 브랜드는 오늘부터 측정됩니다.
• **shareOfVoice**는 기간 안에서 100 × 그 브랜드의 언급 수 / 추적 브랜드 언급 총합이라, 한 기간의 점유율을 더하면 100이 됩니다.
• GET /v1/monitors는 카테고리 모니터마다 leader(가장 많이 언급된 브랜드와 그 비율)를 더합니다. mentioned와 cited는 항상 0입니다.
• GET /v1/monitors/{id}/answers/{taskId}는 mode, 빈 aliases, 추적 브랜드 목록인 competitors를 반환합니다.

​

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

curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'

​

비용과 일정

credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours

• 실행은 한꺼번에 몰리지 않습니다. 태스크는 요금제 동시 실행 한도와 큐가 허용하는 만큼 들어가므로, 무료 요금제 한도를 넘는 실행은 버려지지 않고 몇 분에 걸쳐 도착합니다. 진행 중인 실행은 리포트의 health.pending으로 확인하세요.
• 다음 기간은 보장이 아니라 시각입니다. nextRunAt은 실행이 도래하는 시각이며, 일주일 동안 일시정지한 모니터는 놓친 실행을 몰아서 돌리지 않고 다시 켠 시점부터 한 간격 뒤에 재개합니다.

​

엔드포인트

​

모니터 만들기

curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'

​

실행한 뒤 리포트 읽기

​

숫자의 의미

• 기간, 엔진별 그룹, 셀별 그룹의 **mentionRate**는 100 × 언급된 답변 / 채점된 답변입니다. 엔진별 비율의 평균이 아니라 답변 수로 가중하므로, 바쁜 엔진이 한가한 엔진에 묻히지 않습니다. (브랜드 자체의 비율은 별도 분모를 쓰며, 바로 아래에서 설명합니다.)
• **citationRate**는 등록한 내 도메인 중 하나를 인용한 답변에 대해 같은 방식으로 셉니다. 등록한 도메인이 없으면 인용 추적이 꺼져 있으므로 항상 0입니다.
• 브랜드 비율은 기간 전체가 아니라 자기 sampleSize로 나눕니다. 내 브랜드는 채점된 모든 답변이고, 경쟁사는 모니터에 등록되어 있던 동안 채점된 답변뿐입니다. 오늘 경쟁사를 추가하면 첫 리포트는 그 경쟁사를 측정한 답변만 다루며, 존재하기 전의 이력은 불리하게 세지 않습니다. 해당 답변이 없는 브랜드는 0%가 아니라 mentionRate: null을 보고합니다. 0%는 실제로 사라진 것처럼 읽히기 때문입니다.
• brands의 **shareOfVoice**는 기간 안에서 100 × 그 브랜드의 언급 / 추적 중인 모든 브랜드 언급이므로 한 기간의 점유율을 더하면 100입니다. 이 프롬프트로 수집한 답변 안에서 브랜드를 비교하는 값이며, 시장 점유율도 가시성 순위도 아닙니다. 레거시 상세 엔드포인트의 shareOfVoice는 예전의 답변 침투율 관점으로, 각 브랜드를 수집한 답변 수에 대해 세므로 합이 100을 넘을 수 있습니다. 둘을 한 차트에 섞지 마세요.
• competitorOnly(와 opportunities 목록)는 내 브랜드 없이 설정한 경쟁사를 언급한 답변을 셉니다. 실제로 대응할 수 있는 격차입니다.
• 비율은 0이 아니라 null이 될 수 있습니다. 기간에 답변이 없으면 null이고, 비율 0은 답변이 있었지만 하나도 맞지 않았다는 뜻입니다.
• 답변 없이 완료된 관측은 언급 없음으로 셉니다. 분모에 남고, quality.noAnswerObservations가 그 수를 알려줍니다. 실패한 태스크는 모든 비율에서 빠지고 health에만 나타납니다. 고장 난 엔진은 조용히 부재로 바뀌지 않고 표본을 줄이며, quality는 이를 부재로 재구성하지 않습니다(historicalFailures는 항상 null).
• 오해를 부를 변화량은 보류합니다. 한 기간에 답변이 없거나(insufficient_periods), 채점 맥락이 생기기 전에 채점된 행이거나(legacy_scoring_unknown), 두 기간 사이에 채점 정의가 바뀌었으면 (scoring_definitions_changed) changes와 셀별 mentionRateChangePp는 null이고 quality.comparable은 false입니다. 과거 행은 채점 당시 정의를 유지하므로(quality.scoring) 별칭이나 경쟁사를 바꿔도 과거가 다시 쓰이지 않습니다. 위에서 설명한 월간 경쟁사 분석만 예외입니다.
• 표본 크기를 공개합니다. 채점된 답변이 30개 미만이면 quality.lowSample이 true이고, quality.missingCells는 아직 답변이 없는 설정된 프롬프트 × 엔진 셀 수를 세며, quality.partialDays는 기간이 반으로 자른 UTC 날짜를 알려줍니다. 부분 일자의 낮은 건수는 산술 결과이지 하락이 아닙니다.

​

답변의 출처

​

인용 추이

curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

​

채점된 행 내보내기

​

숫자 뒤의 답변 읽기

• answerText: 엔진이 준 그대로의 답변. 가능하면 markdown이며, 최대 8,000자이고 더 길면 말줄임표를 붙여 자릅니다.
• sources: 엔진 순서대로의 인용. 각각 레이블과 인용 목록 안의 1부터 시작하는 위치를 가집니다.
• aliases와 competitors: 이 행이 비교된 대상. 언급을 믿지 않고 확인할 수 있게 해 줍니다.
• scoringContext: 사용한 정확한 정의. version 해시, 채점 시각, answerPresent, 위 텍스트가 잘렸을 때의 evidenceTruncated를 담습니다.

​

이 영역의 오류

​

에이전트와 함께 쓰기

1. GET /v1/monitors/capabilities: 무엇이든 쓰기 전에 엔진, 가격, 한도를 읽습니다.
2. GET /v1/monitors: 해당 주제와 시장의 기존 모니터를 재사용하거나, POST /v1/monitors로 새로 만듭니다(먼저 POST /v1/monitors/suggest를 호출해 후보를 다듬어도 됩니다).
3. POST /v1/monitors/{id}/run: 다음 예약 기간 전에 답변이 필요하면 실행합니다.
4. GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT: quality(comparable, lowSample, missingCells, partialDays)를 먼저 읽고 숫자를 봅니다. health.pending이 가라앉고 quality.sampleSize가 더 늘지 않을 때까지 폴링합니다.
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=...&includeEvidence=true&format=csv: 같은 기간을 내보내며 x-next-cursor가 빌 때까지 따라갑니다.

​

한도