> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 프롬프트 세트를 예약 실행하고, 분모가 명시된 하나의 리포트 계약을 읽고, 모든 숫자 뒤의 답변을 내보냅니다.

모니터는 저장된 프롬프트 세트를 일정에 따라 반복 실행하고, 그 결과 AI 답변을 내 브랜드와 경쟁사 기준으로
채점합니다. 이 페이지는 API 계약입니다. 모니터 설정 방법, 각 숫자의 의미, 숫자 뒤의 출처를 읽는 방법,
그 아래 답변을 내보내는 방법을 다룹니다. 같은 데이터를 대시보드로 보려면
[제품 가이드](https://querying.ai/ko/monitors)부터 보세요.

이 페이지의 모든 키, id, 브랜드, 프롬프트는 예시입니다. 실제 인증 정보나 실제 모니터는 없습니다.

## 모니터란

모니터는 **한 시장을 대상으로 한 이름 붙은 프롬프트 세트**입니다. 프롬프트 목록, 보낼 엔진, "내 브랜드"를
뜻하는 별칭, 선택적으로 내 도메인과 경쟁사 몇 곳, 국가, 실행 간격으로 이루어집니다. 예약 실행마다
프롬프트 × 엔진 수만큼 일반 비동기 태스크를 제출하고, 완료된 답변은 한 번 채점해 보관합니다.

채점 범위는 의도적으로 좁고, 데이터는 저장한 것 이상을 답할 수 없습니다.

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

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

경쟁사를 직접 입력하지 않아도 됩니다. 모니터의 첫 실행이 끝나면 최근 답변을 언어 모델로 읽어, 내 브랜드와 같은 것을
팔면서 두 개 이상의 답변에 나온 브랜드를 최대 15곳까지 남깁니다. 이 분석은 30일마다 다시 돌기 때문에 새 경쟁사는
추가되고 더 이상 언급되지 않는 곳은 빠집니다.

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

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

모니터가 다르면 주제나 시장이 다르고 리포트도 따로입니다. 각각 자체 기간, 채점 정의, 일정을 가집니다.
두 가지 습관이 도움이 됩니다.

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

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

브랜드 모니터는 브랜드 하나를 추적합니다. **카테고리 모니터**는 시장을 추적합니다. 카테고리 이름을 정하고 질문을
세부 분야별로 묶으면, 리포트가 엔진이 답변하며 언급한 브랜드의 순위를 냅니다. 모니터를 만들 때
`"mode": "CATEGORY"`를 지정하세요. `mode`의 기본값은 `BRAND`이고, 저장된 모든 행의 뜻을 정하므로 모니터를 만든
뒤에는 바뀌지 않습니다.

```bash theme={null}
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
  }'
```

| 필드 | 카테고리 모니터에서 |
| - | - |
| `category` | 필수, 1–80자. 구매자가 부르는 시장 이름. |
| `promptTopics` | 프롬프트(정확한 텍스트)를 세부 분야에 연결합니다. 세부 분야는 최대 30개, 이름은 각 60자 이하. 항목이 없는 프롬프트는 카테고리 전체를 다룹니다. |
| `competitors` | 순위를 낼 브랜드: 직접 입력한 최대 25곳. 첫 실행이 끝나면 월간 분석이 답변에서 언급된 브랜드를 최대 25곳 더 붙입니다. |
| `aliases` · `domains` · `alertBelowPct` | 비워 두세요. 카테고리 모니터에는 자체 브랜드, 소유 도메인, 알림이 없어서 값을 보내면 `400 VALIDATION_ERROR`가 반환됩니다. |

일정, 비용, 기간, 필터, `quality`, 출처, 인용, 결과, 답변은 브랜드 모니터와 같게 동작합니다. 카테고리 모니터에는 알림이
없으므로 `POST /v1/monitors/{id}/alerts/test`는 `400`을 반환합니다.

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

`GET /v1/monitors/{id}/analytics`는 카테고리 형태로 응답합니다. `stats`와 `previous`는 `runs`, `named`(추적 브랜드를
하나 이상 언급한 답변 수), `namedRate`를 담고, `changes.namedRatePp`는 포인트 변화이며, `category` 객체가 순위를 담습니다.

| 필드 | 담고 있는 것 |
| - | - |
| `category.brands` | 답변이 언급한 모든 추적 브랜드, 언급한 답변이 많은 순: `rank`, `mentions`, `sampleSize`, `mentionRate`, `shareOfVoice`, 직전 구간 대비 변화. |
| `category.topics` | 세부 분야별 한 행(`topic: null`은 카테고리 전체). `runs`, `namedRate`, 가장 많이 언급된 브랜드 3곳. |
| `category.engines` | 엔진별 한 행과 그 엔진이 가장 많이 언급한 브랜드 3곳. |
| `category.series` | UTC 일별, 상위 5개 브랜드의 비율. |
| `category.prompts` | 프롬프트별 한 행: 선두 브랜드와 엔진별 셀. 각 셀에는 그 뒤의 답변을 여는 `evidenceTaskId`가 있습니다. |

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

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

`POST /v1/monitors/research`는 [Prompt Research](/ko/research/prompt-research)의 요청 본문을 받고, 같은 12크레딧을 쓰고,
같은 결과를 반환합니다. 다만 태스크는 계정 명의로 제출됩니다. 큐에 들어간 태스크는 `GET /v1/async/task/{id}`로 읽으세요. 태스크 id는 응답의 `data.task.id`입니다.

```bash theme={null}
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"] }'
```

`monitorSet.prompts`를 `prompts`로, 각 프롬프트의 `topic`을 `promptTopics`의 세부 분야로, `brands[].brand`를
`competitors`로 쓰세요. 대시보드의 **리서치 실행** 버튼이 같은 일을 하며 폼을 채웁니다. 모니터를 만들기 전까지는
아무것도 저장되지 않습니다.

## 비용과 일정

실행 한 번은 프롬프트마다, 엔진마다 태스크 하나를 각 엔진의 공개 크레딧 가격으로 큐에 넣습니다. 일정은
모니터를 일시정지하거나 삭제할 때까지 반복되므로, 생성할 때 고르는 것은 반복 비용입니다.

```text theme={null}
credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours
```

예를 들어 프롬프트 12개를 ChatGPT(2 크레딧)와 Gemini(1 크레딧)에 보내면 실행당 24개 태스크, 36
크레딧이고, 매일 실행하면 월 약 1,080 크레딧입니다. 가격은 하드코딩하지 말고 capabilities 엔드포인트에서
실시간으로 읽으세요.

일정에 의존하기 전에 알아둘 두 가지 성질이 있습니다.

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

경쟁사 자동 분석에는 모니터당 한 달 100크레딧이 더 들고, 실행 주기에 맞춰 각 실행에 나눠 청구됩니다. 매일 실행하는
모니터는 실행마다 약 3크레딧, 매주 실행하는 모니터는 약 23크레딧입니다. 실행의 태스크가 모두 들어간 뒤에 청구되므로,
잔액 부족으로 멈춘 실행에는 청구되지 않습니다.

## 엔드포인트

| 메서드와 경로 | 제공하는 것 |
| - | - |
| `GET /v1/monitors/capabilities` | 엔진별 크레딧 가격, 한도, 지표 정의, 일정 비용 계산. 부작용 없는 가벼운 조회입니다. |
| `GET /v1/monitors` | 내 모니터 목록과 각각의 30일 집계. |
| `POST /v1/monitors` | 모니터를 만들고 시작합니다. |
| `GET /v1/monitors/{id}` | 레거시 기간 상세. 대신 `/analytics`를 쓰세요. 이 엔드포인트는 필터 없는 전체 기간 셀 행렬을 기간별 숫자에 섞고, 인용을 도메인 12개와 페이지 20개에서 자릅니다. |
| `PATCH /v1/monitors/{id}` | 필드를 수정하거나, `enabled`로 일시정지와 재개를 합니다. |
| `DELETE /v1/monitors/{id}` | 모니터와 채점 이력을 삭제합니다. |
| `POST /v1/monitors/{id}/run` | 다음 실행을 지금으로 당깁니다. 여느 실행처럼 크레딧을 씁니다. |
| `GET /v1/monitors/{id}/analytics` | **리포트 계약.** 하나의 코호트, 하나의 필터 세트, 모든 섹션. |
| `GET /v1/monitors/{id}/sources` | 같은 기간의 인용 도메인 또는 페이지, 페이지네이션 지원. |
| `GET /v1/monitors/{id}/citations` | 상위 도메인과 페이지의 일별 인용 수. 대시보드 인용 차트가 쓰는 데이터입니다. |
| `GET /v1/monitors/{id}/results` | 채점된 행 자체를 JSON 또는 CSV로, 필터와 커서 지원. |
| `GET /v1/monitors/{id}/answers/{taskId}` | 행 하나 뒤에 보관된 답변. |
| `GET /v1/monitors/{id}/prompt` | 프롬프트 하나의 상세: 시계열, 출처, 최근 행. |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | 알림 임계값, 래치 상태, 전달 이력. 테스트 이메일을 큐에 넣습니다. |
| `POST /v1/monitors/suggest` | 브랜드 정보로 만든 후보 프롬프트. 아무것도 저장하지 않고 태스크 크레딧을 쓰지 않습니다. |
| `POST /v1/monitors/research` | 모니터용 프롬프트 리서치: [Prompt Research](/ko/research/prompt-research)와 같은 요청, 가격, 결과를 계정 명의로 제출합니다. |

모두 API의 나머지와 같은 Bearer 키를 받습니다([인증](/ko/authentication) 참고). 다른 계정 소유 모니터는
`403`이 아니라 `404`로 응답합니다.

## 모니터 만들기

```bash theme={null}
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
  }'
```

`name`, `engines`, `prompts`, `aliases`, `intervalHours`는 브랜드 모니터에서 필수이고, 카테고리 모니터는 `aliases` 대신 `category`를 받습니다. 각 목록은 배열이나 줄바꿈으로 구분한
문자열 하나를 받으며, 항목은 앞뒤 공백을 자르고 빈 줄은 버리고 중복은 제거합니다. `country`는 엔진이
답할 시장을 고를 뿐 프롬프트를 번역하지 않습니다. `prompts × engines`는 capabilities의 `tasksPerRun` 한도
이하여야 합니다.

엔진은 예약 가능한 프롬프트 화면입니다: `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`,
`NAVER_AI_BRIEF`, `NAVER_AI_TAB`, 그리고 지원 중단 별칭 `NAVER`. `GOOGLE_AIO`와 `GOOGLE_AIMODE`는 받아서
`GOOGLE`과 `AIMODE`로 저장합니다. `SOURCE_INFLUENCE` 같은 분석 태스크는 프롬프트 화면이 아니므로 모니터에
예약할 수 없습니다.

일부 엔진으로 제한된 키는 그 엔진만 예약할 수 있으며, 그 밖은 `403 KEY_SCOPE_DENIED`입니다. 계정 단위 모니터
상한에 걸리면 `409 MONITOR_LIMIT`을 반환합니다.

## 실행한 뒤 리포트 읽기

`POST /v1/monitors/{id}/run`은 다음 실행을 즉시 도래시키며, 답변 태스크는 약 1분 안에 나타납니다. 이 실행은
예약 실행처럼 과금되고, 그 기간이 아직 도래 상태인 동안 호출을 재시도해도 두 번 과금하지 않습니다.

`GET /v1/monitors/{id}/analytics`는 리포트의 모든 부분이 기대야 하는 계약입니다. 기간은 **반개구간이며
UTC 기준**입니다. `since`는 포함, `until`은 제외이고, 두 가지 방법 중 하나로 고릅니다.

| 파라미터 | 규칙 |
| - | - |
| `days` | `7`, `30`(기본값), `90` 중 하나이며 현재 시점에서 끝납니다. `since`/`until`과 함께 쓸 수 없습니다. |
| `since`와 `until` | 둘 다 함께 필요하며, **시간대가 포함된** 완전한 ISO 시각이어야 합니다(예: `2026-09-15T00:00:00Z`). 기간은 양수이고 최대 90일이며 미래일 수 없습니다. 단순 `YYYY-MM-DD`는 여기서 거부됩니다. 이식 가능한 기간을 정의할 수 없기 때문입니다. |

선택 필터 두 개가 **모든** 섹션에 한꺼번에 적용됩니다. `engine`(정식 id 또는 공개 별칭)과 `prompt`(정확한
텍스트, 최대 2,000자)입니다. 행은 프롬프트 텍스트를 키로 하므로, 나중에 모니터에서 뺀 프롬프트도 계속
조회할 수 있습니다.

모든 섹션이 그 하나의 코호트를 공유하고, 이전 구간은 길이와 필터가 정확히 같으므로 같은 조건끼리
비교합니다.

| 필드 | 담는 내용 |
| - | - |
| `window` | `since`, `until`, `previousSince`, `previousUntil`, `timezone`, 그리고 기간의 `bounds` 표기. `previousUntil`은 항상 이번 기간의 `since`입니다. |
| `filters` | 적용된 필터를 해석한 값: 정식 엔진 id, 정확한 프롬프트, 또는 `null`. |
| `stats` · `previous` | 이번 기간과 그 이전 구간의 건수와 비율. |
| `changes` | 퍼센트포인트 변화량. 비교가 타당하지 않으면 `null`(아래 참고). |
| `engineRates` | 같은 비율을 엔진별로. 차트를 읽지 않아도 약한 엔진이 보입니다. |
| `series` | UTC 일자와 엔진별 값. `partial`은 기간 경계에서 잘린 날을 표시합니다. |
| `brands` | 내 브랜드(`__you__`)와 추적 중인 모든 경쟁사, 언급 많은 순. 각자 `sampleSize`와 그 기준으로 잰 비율을 가집니다. |
| `voiceSeries` | 같은 브랜드의 UTC 일자별 값, 추세선용. |
| `prompts` | 프롬프트별 합계, 언급률 낮은 순. 각각 엔진별 셀을 가집니다. |
| `opportunities` | 경쟁사는 언급됐는데 내 브랜드는 빠진 셀, 놓친 횟수 많은 순. 작업할 목록입니다. |
| `quality` | 표본의 구성과, 숫자가 말할 수 없는 모든 것. |
| `health` · `healthScope` | 아직 개별로 보이는 태스크의 실행 상태. 별도의 최근 범위이며 분모에 들어가지 않습니다. |

## 숫자의 의미

대시보드 패널에 이름을 붙이기 전에 읽으세요. 이 정의는 공개된 계약이며,
`GET /v1/monitors/capabilities`가 `metrics`로 반환하므로 클라이언트가 숫자 옆에 표시할 수 있습니다.

* 기간, 엔진별 그룹, 셀별 그룹의 \*\*`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 날짜를 알려줍니다. 부분 일자의 낮은 건수는 산술 결과이지 하락이 아닙니다.

채점된 행의 `position`은 답변 텍스트 안에서 가장 먼저 나온 별칭의 **문자 오프셋**입니다. 순위가 아니라
노출 정도의 대리 지표입니다. 브랜드가 없으면 `null`이므로 `0`이 "없음"을 뜻할 일이 없습니다.

## 답변의 출처

`GET /v1/monitors/{id}/sources`는 "어떤 페이지가 이 프롬프트들을 가져가고 있나"에 답합니다. 리포트와 같은
기간과 필터를 쓰며, 원시 인용 수가 아니라 **서로 다른 답변 수**를 세므로 한 답변에서 세 번 인용된 페이지는
한 번으로 셉니다.

| 파라미터 | 규칙 |
| - | - |
| `groupBy` | `domain`(기본값, `www.`를 뗀 호스트) 또는 `page`(레이블이 붙은 전체 URL). |
| `limit` | 1–100, 기본값 20. |
| `cursor` | 이전 응답의 `nextCursor`를 그대로 넘깁니다. `null`이면 목록 끝입니다. |
| `days` / `since`+`until` / `engine` / `prompt` | 리포트와 똑같습니다. |

각 행에는 `citations`와 `prompts`(둘 다 서로 다른 답변 수), 등록한 내 도메인 여부를 뜻하는 `own`, 답변
엔드포인트로 열어 볼 수 있는 `evidenceTaskId`가 있습니다. 여기에는 조용한 상위 N개 자르기가 없습니다. 커서를
따라가면 기간 안의 모든 도메인이나 페이지에 닿을 수 있습니다.

## 인용 추이

`GET /v1/monitors/{id}/citations`는 대시보드 인용 차트에 쓰이는 데이터를 그대로 돌려줍니다.
기간 전체의 일별 인용 수와, 상위 도메인과 페이지마다의 일별 시계열입니다. 저장된 결과만
읽으므로 크레딧을 쓰지 않습니다.

| 파라미터 | 규칙 |
| - | - |
| `days` | `7`, `30`, `90` 중 하나. 기본값 `30`. |
| `since`+`until` | 리포트와 같은 최대 90일의 고정 기간. 지정하면 `days`는 표시용 라벨일 뿐입니다. |
| `engine` / `prompt` | 리포트와 같습니다. |
| `kind` | `all`(기본값), `owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`. |
| `q` | 도메인은 이름으로, 페이지는 URL로 거릅니다. 최대 200자. |
| `offset` | 0–10,000. 목록마다 20개를 반환합니다. |

여기서 인용 1건은 답변 하나에 나온 페이지 하나입니다. 같은 답변에 같은 페이지가 두 번 나와도
1건으로 셉니다. `/sources`는 서로 다른 답변 수를 세므로 숫자가 다를 수 있습니다.

| 필드 | 의미 |
| - | - |
| `totals` | 기간 전체의 `answers`, `citedAnswers`, `citations`, `ownedCitations`. |
| `days` | 측정된 UTC 날짜마다 `answers`, `citations`, `ownedCitations`. 답변은 있지만 인용이 없는 날은 `citations: 0`으로 나오고, 답변이 없는 날은 빠집니다. |
| `domains` / `pages` | 현재 `offset`의 상위 20개. 항목마다 `kind`, `owned`, `citations`, `answers`, `prompts`와 `{day, citations}` 형태의 `daily` 시계열이 있습니다. `daily`에는 인용이 있는 날만 들어갑니다. |
| `types` | `kind`별 인용 수와 도메인 수. 전체 출처 기준입니다. |
| `pagination` | `offset`, `limit`, `totalDomains`, `totalPages`. |

출처 점유율은 그 출처의 `citations`를 `totals.citations`로 나눈 값입니다. `kind`, `q`,
`offset`은 목록만 좁히고, `totals`, `days`, `types`는 항상 기간 안의 모든 출처를 기준으로 합니다.

```bash theme={null}
curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## 채점된 행 내보내기

`GET /v1/monitors/{id}/results`는 행 자체를 반환합니다. 데이터 웨어하우스 적재, 주간 보고 자료, 스프레드시트에
쓰세요.

| 파라미터 | 규칙 |
| - | - |
| `since` · `until` | 반개구간, 기본값은 현재 시점에서 끝나는 최근 30일. `since`는 기존 내보내기와의 호환을 위해 단순 `YYYY-MM-DD`(`00:00:00Z`로 해석)도 받습니다. 리포트 엔드포인트는 받지 않습니다. |
| `engine` · `prompt` | 리포트와 같은 필터. |
| `mentioned` · `cited` | `true`/ `false`. `mentioned=false`가 경쟁 격차 보기입니다. |
| `competitor` | 설정한 경쟁사 이름과 정확히 일치. 저장된 경쟁사 목록에 그 이름이 있는 답변만 남깁니다. |
| `includeEvidence` | 모든 행에 `answerText`, `sources`, `scoringContext`를 더하고 페이지 크기 상한을 낮춥니다. |
| `limit` | 1–10,000, 기본값 10,000. `includeEvidence`를 쓰면 기본값과 최댓값이 100입니다. |
| `format` | `json`(기본값) 또는 `csv`. |
| `cursor` | 이전 응답의 `nextCursor`. |

페이지네이션은 마이크로초 정밀도의 `(ranAt, id)` 키셋 방식이므로 같은 시각을 공유하는 행도 빠지거나
반복되지 않습니다. 추출을 반복 가능하게 하려면 **명시적인 `since`와 `until`을 보내고, 고정한 채로,
`nextCursor`가 `null`이 될 때까지 따라가세요.** 페이지 사이에 기간을 바꾸면 행이 빠지거나 반복될 수 있습니다.
커서는 불투명한 값으로 다루세요. 반환받아 그대로 돌려줄 뿐 직접 만들지 않습니다.

`format=csv`이면 응답은 `text/csv`(Excel이 올바르게 열도록 BOM이 붙은 UTF-8)이고, CSV 본문에는 둘 곳이
없으므로 페이지네이션 상태가 헤더로 옮겨갑니다.

| 헤더 | 의미 |
| - | - |
| `x-next-cursor` | 다음 페이지의 커서. 마지막 페이지에서는 비어 있습니다. |
| `x-result-truncated` | 이 페이지가 반환한 것보다 많은 행이 일치하면 `true`. |
| `x-result-since` · `x-result-until` | 해석된 기간. 이어서 내보낼 때 고정할 수 있습니다. |

열은 `ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id`이고,
`includeEvidence=true`이면 `answer_text, sources, scoring_context`가 더해집니다(`sources`와 `scoring_context`는 셀
안의 JSON 텍스트). 스프레드시트 수식으로 읽힐 수 있는 셀은 쓰기 전에 무력화하므로, 외부 텍스트가 시트에서
수식으로 바뀌지 않습니다.

## 숫자 뒤의 답변 읽기

`GET /v1/monitors/{id}/answers/{taskId}`는 행 하나에 대해 보관된 근거를 반환합니다.

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

채점 맥락이 저장되기 전에 채점된 행은 `scoringKnown: false`와 모니터의 현재 별칭, `null`인
`evidenceTruncated`를 반환합니다. 엔진이 답변 텍스트를 반환하지 않았으면 `answerText`는 `null`입니다.

## 이 영역의 오류

봉투는 다른 곳과 같습니다([오류](/ko/concepts/errors) 참고). 모니터링에만 해당하는 코드는 다음과 같습니다.

| 코드 | 상태 | 발생 조건 |
| - | - | - |
| `VALIDATION_ERROR` | 400 | 잘못된 기간(`days`와 `since`/`until` 혼용, 90일 초과, 시간대 없는 시각), 알 수 없는 엔진, 너무 긴 프롬프트, 범위를 벗어난 `limit`, 또는 집계하기에 너무 큰 리포트. 기간, 엔진, 프롬프트를 좁히세요. |
| `MISSING_API_KEY` / `UNAUTHORIZED` | 401 | 키가 없거나 이 계정의 키가 아닙니다. |
| `KEY_SCOPE_DENIED` | 403 | 키에 허용된 엔진이 모니터의 엔진을 포함하지 않습니다. |
| `NOT_FOUND` | 404 | 이 키로 볼 수 있는 모니터가 없거나(다른 사람 모니터도 같게 보입니다), 그 태스크 id로 채점된 행이 없습니다. |
| `MONITOR_LIMIT` | 409 | 계정이 이미 최대 개수의 모니터를 가지고 있습니다. |
| `RATE_LIMITED` | 429 | 프롬프트 제안(20초에 1회, 시간당 30회) 또는 테스트 알림 이메일(모니터당 5분에 3회). |
| `SUGGEST_FAILED` | 400 / 502 / 503 | 이 브랜드에 대한 프롬프트 제안이 거절됐거나, 제안 서비스가 실패했거나, 이 배포에 설정되지 않았습니다. |

## 에이전트와 함께 쓰기

이 페이지의 엔드포인트만으로 에이전트나 스크립트가 따를 수 있는 실용적인 순서입니다. 예시이니 키, 모니터 id,
기간은 직접 바꾸세요.

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`가 빌 때까지 따라갑니다.

같은 작업은 에이전트용 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`). 쓰기 도구는 변경 작업으로 표시되며, `create_monitor`와
`run_monitor`는 호출 전에 크레딧을 소모한다고 밝힙니다.

## 한도

| 한도 | 값 |
| - | - |
| 계정당 모니터 | 20 |
| 실행당 태스크 | 200 (`prompts × engines`) |
| 모니터당 프롬프트 | 100 |
| 프롬프트 길이 | 2,000자 |
| 브랜드 별칭 | 20 |
| 등록 도메인 | 20 |
| 경쟁사 | 브랜드 모니터: 직접 추가 10곳, 자동으로 찾은 곳 최대 15곳. 카테고리 모니터: 직접 추가 25곳, 자동으로 찾은 곳 최대 25곳 |
| 카테고리 이름 | 80자 |
| 카테고리 모니터의 세부 분야 | 30개, 이름은 각 60자 이하 |
| 실행 간격 | 1–168시간 |
| 리포트 기간 | 90일 |
| 결과 페이지 | 기본 10,000, 최대 10,000. 근거 포함 시 100 |
| 출처 또는 근거 페이지 | 100 |

볼륨을 늘리기 전에 [요금](https://querying.ai/ko/pricing)과 [엔진 레퍼런스](/ko/engines/overview)를 확인하세요.