> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# SEO API

> BeatAPI 키 하나로 키워드 데이터, 도메인 순위, 백링크, Domain Rating, 사이트 트래픽을 조회하세요. 애플리케이션과 에이전트를 위해 응답으로 바로 답하는 12개 도구입니다.

12개 도구로 애플리케이션이나 에이전트가 SEO 데이터를 얻을 수 있습니다. 키워드 검색량과 순위 경쟁 난이도, 도메인에 검색 트래픽을 가져오는 키워드와 페이지, 경쟁 도메인, 백링크, Domain Rating, 사이트 방문 수를 확인할 수 있습니다. 각 도구는 `/v1/seo/` 아래의 `POST` 하나이며, BeatAPI API 키를 사용하고 응답 하나로 답합니다. 에이전트는 같은 도구를 [기능](#agents)으로 사용할 수 있습니다.

## 빠른 시작

```bash
curl https://api.beatapi.io/v1/seo/keyword-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis cluster"],"country":"us"}'
```

```json
{
  "object": "seo.keyword_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "monthly_searches": [{ "year": 2026, "month": 9, "search_volume": 590 }]
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

## 인증

모든 호출에 BeatAPI API 키를 `Authorization: Bearer <key>`로 보내세요. 키는 `sk-` 접두사가 있든 없든 동작합니다. 키는 [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요. 모든 도구는 `https://api.beatapi.io`에 있으며 계정 잔액을 사용합니다.

## 도구 선택

| 필요한 것                               | 도구                   |
| ----------------------------------- | -------------------- |
| 이미 가진 키워드의 검색량, CPC, 난이도, 의도, 월별 기록 | `keyword-overview`   |
| 주제 관련 새 키워드                         | `keyword-ideas`      |
| 키워드 목록의 난이도만                        | `keyword-difficulty` |
| 한 시장에서의 도메인 검색 현황                   | `domain-overview`    |
| 도메인이 순위에 오른 키워드, 또는 특정 키워드의 순위      | `ranked-keywords`    |
| 검색 트래픽순 도메인 페이지                     | `top-pages`          |
| 같은 키워드로 경쟁하는 도메인                    | `competitors`        |
| 도메인 링크 프로필 수치                       | `backlink-summary`   |
| 링크 목록 자체                            | `backlinks`          |

Domain Rating과 사이트 전체 방문 수는 [Domain Rating과 사이트 트래픽](#domain-rating-and-site-traffic)을 참고하세요.

실시간 검색 결과 페이지 도구는 없습니다. 특정 키워드에서 도메인의 순위를 확인하려면 `contains`와 함께 `ranked-keywords`를 호출하세요. 실시간 순위가 아니라 마지막으로 기록된 순위입니다.

## 국가와 언어

`country`와 `language`로 시장을 고릅니다. 해당 국가, 해당 언어의 Google 검색입니다. 키워드 도구와 `domain-overview`, `ranked-keywords`, `top-pages`, `competitors`가 이 필드를 받습니다. 백링크 도구는 시장 개념이 없으며 두 필드를 모두 거부합니다.

| 필드         | 기본값         | 규칙                                                                           |
| ---------- | ----------- | ---------------------------------------------------------------------------- |
| `country`  | `us`        | 두 글자 소문자 코드(예: `us`, `gb`, `de`, `jp`). 약 90개 시장을 지원하며, 중국(`cn`)은 지원하지 않습니다. |
| `language` | 해당 시장의 주 언어 | 해당 시장의 언어 중 하나(예: `us`의 `es`, `ca`의 `fr`, `hk`의 `zh-TW`).                    |

목록에 없는 국가나 언어는 `400 bad_request`로 거부되며, 메시지에 해당 시장에서 쓸 수 있는 값이 표시됩니다: `language 'de' is not covered in us; use one of: en, es`.

## limit과 offset

`keyword-ideas`, `ranked-keywords`, `top-pages`, `competitors`, `backlinks`는 행을 페이지 단위로 반환합니다.

| 필드       | 기본값   | 범위                                                                 |
| -------- | ----- | ------------------------------------------------------------------ |
| `limit`  | `100` | 1~~1000행, `competitors`에서는 1~~999행. 반환된 행은 모두 과금되므로 필요한 만큼만 요청하세요. |
| `offset` | `0`   | 건너뛸 행 수 0\~10000. 다음 페이지는 여기에 `limit`을 더하세요.                       |

이 응답에는 `limit`과 `offset`이 다시 들어 있으며, 알 수 있는 경우 전체 행 수인 `total`도 포함됩니다.

## 응답

모든 도구는 동기식으로 응답합니다. 결과는 `POST`에 대한 응답에 들어 있으므로 폴링할 필요가 없습니다. 대부분의 호출은 몇 초 안에 끝납니다.

| 필드                    | 설명                                                                                                    |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `object`              | 도구 이름(예: `seo.ranked_keywords`).                                                                      |
| `request_id`          | 지원 요청 시 함께 적어 주세요. 이 id로 `GET /v1/tasks/{id}`를 호출하면 `output` 아래에 같은 결과가 반환되므로, 응답을 잃어버려도 결과는 잃지 않습니다. |
| `country`, `language` | 사용된 시장(시장을 받는 도구에서).                                                                                  |
| `domain`              | 사용된 도메인(도메인을 받는 도구에서). 전체 URL은 도메인으로 줄이고 앞의 `www.`는 제거합니다.                                            |
| `results[]`           | 행 목록(목록을 반환하는 도구에서). 다른 도구는 필드를 최상위에 둡니다.                                                             |
| `billed_rows`         | 이 호출에서 과금된 행 수.                                                                                       |
| `has_data`            | `domain-overview`, `backlink-summary`, Domain Rating·사이트 트래픽 도구에 있습니다. `false`는 해당 도메인의 기록이 없다는 뜻입니다. |
| `usage`               | 각 응답 끝에 있으며, 호출 비용을 나타냅니다.                                                                            |

`usage.price_usd`는 미국 달러 기준 정산 금액입니다. `billing_unit`은 항상 `request`, `quantity`는 항상 `1`이며, `billed_rows`는 청구 대상 행 수입니다.

데이터에 없는 수치는 행에서 빠지므로 사용하기 전에 필드가 있는지 확인하세요. 알 수 없는 요청 필드는 `400 bad_request`로 거부됩니다. 철자가 틀린 필드를 조용히 버리면 원래 질문과 다른 질문에 답하게 되기 때문입니다.

## 키워드 도구

### 키워드 개요

`POST https://api.beatapi.io/v1/seo/keyword-overview`

이미 가진 키워드의 검색량, CPC, 경쟁도, 난이도, 의도, 월별 기록. 아무도 검색하지 않는 키워드는 0이 아니라 누락된 상태로 반환됩니다.

| 필드         | 타입        |  필수 | 설명                                                |
| ---------- | --------- | --: | ------------------------------------------------- |
| `keywords` | string\[] |   예 | 키워드 1\~100개, 각각 최대 80자. 소문자로 변환되며 중복은 한 번만 계산됩니다. |
| `country`  | string    | 아니요 | [국가와 언어](#country-and-language)를 참고하세요.           |
| `language` | string    | 아니요 | [국가와 언어](#country-and-language)를 참고하세요.           |

응답은 [빠른 시작](#quick-start)에 있습니다. 각 행의 필드:

| 필드                   | 설명                                                              |
| -------------------- | --------------------------------------------------------------- |
| `keyword`            | 키워드.                                                            |
| `search_volume`      | 이 시장의 월간 검색 수.                                                  |
| `cpc_usd`            | 유료 광고의 클릭당 비용(미국 달러).                                           |
| `competition`        | 광고주 경쟁도, 0\~1.                                                  |
| `keyword_difficulty` | 순위에 오르기 어려운 정도, 0\~100.                                         |
| `intent`             | 주요 검색 의도(예: `informational`, `navigational`).                   |
| `updated_at`         | 이 키워드 데이터가 마지막으로 갱신된 시점.                                        |
| `monthly_searches[]` | 월별 `year`, `month`, `search_volume`. `keyword-overview`에만 있습니다. |

### 키워드 아이디어

`POST https://api.beatapi.io/v1/seo/keyword-ideas`

시드 키워드와 관련된 키워드를 관련성 높은 순으로 반환합니다. 행에는 `monthly_searches`를 뺀 `keyword-overview`의 필드가 있습니다.

| 필드                    | 타입        |  필수 | 설명                                         |
| --------------------- | --------- | --: | ------------------------------------------ |
| `keywords`            | string\[] |   예 | 시드 키워드 1\~20개, 각각 최대 80자.                  |
| `limit`, `offset`     | integer   | 아니요 | [limit과 offset](#limit-and-offset)을 참고하세요. |
| `country`, `language` | string    | 아니요 | [국가와 언어](#country-and-language)를 참고하세요.    |

```bash
curl https://api.beatapi.io/v1/seo/keyword-ideas \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis sentinel"],"limit":20}'
```

### 키워드 난이도

`POST https://api.beatapi.io/v1/seo/keyword-difficulty`

여러 키워드의 `keyword_difficulty`만 한 번에 조회합니다. `keyword-overview`와 같은 필드를 받습니다.

```json
{
  "object": "seo.keyword_difficulty",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    { "keyword": "redis cluster", "keyword_difficulty": 15 },
    { "keyword": "redis sentinel", "keyword_difficulty": 2 }
  ],
  "billed_rows": 2,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0186",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

## 도메인 도구

네 도구 모두 `example.com` 같은 `domain`과 `country`, `language`를 받습니다.

### 도메인 개요

`POST https://api.beatapi.io/v1/seo/domain-overview`

한 시장에서 도메인의 자연 검색·유료 검색 현황. 검색 트래픽만 해당하며 사이트 전체 방문 수가 아닙니다.

```bash
curl https://api.beatapi.io/v1/seo/domain-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","country":"us"}'
```

```json
{
  "object": "seo.domain_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "has_data": true,
  "organic": {
    "ranking_keywords": 22125,
    "search_traffic_estimate": 108626.58,
    "traffic_value_usd_estimate": 483101.98,
    "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
    "new": 18919,
    "up": 1048,
    "down": 1105,
    "lost": 4041
  },
  "paid": { "ranking_keywords": 0, "search_traffic_estimate": 0 },
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 필드                           | 설명                                                         |
| ---------------------------- | ---------------------------------------------------------- |
| `ranking_keywords`           | 이 시장에서 순위에 오른 키워드 수.                                       |
| `search_traffic_estimate`    | 월간 추정 검색 트래픽.                                              |
| `traffic_value_usd_estimate` | 그 트래픽을 광고로 살 때의 추정 비용(미국 달러).                              |
| `rank_distribution`          | 순위별 키워드 수: `1`, `2-3`, `4-10`, `11-20`, `21-30`, `31-100`. |
| `new`, `up`, `down`, `lost`  | 최근 새로 순위에 오르거나, 순위가 오르거나, 내리거나, 순위에서 사라진 키워드 수.            |

기록이 없는 도메인은 `has_data: false`와 함께 반환되며 `organic`도 `paid`도 없습니다. 트래픽이 0이라는 뜻이 아니라 데이터가 없다는 뜻이며, 호출은 과금됩니다.

### 순위 키워드

`POST https://api.beatapi.io/v1/seo/ranked-keywords`

한 시장에서 도메인이 순위에 오른 키워드를 검색량 높은 순으로 반환합니다.

| 필드                    | 타입      |  필수 | 설명                                                 |
| --------------------- | ------- | --: | -------------------------------------------------- |
| `domain`              | string  |   예 | 도메인.                                               |
| `contains`            | string  | 아니요 | 이 텍스트를 포함한 키워드만(최대 80자, 대소문자 무시). `%`와 `_`는 거부됩니다. |
| `limit`, `offset`     | integer | 아니요 | [limit과 offset](#limit-and-offset)을 참고하세요.         |
| `country`, `language` | string  | 아니요 | [국가와 언어](#country-and-language)를 참고하세요.            |

```bash
curl https://api.beatapi.io/v1/seo/ranked-keywords \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","contains":"cluster","limit":1}'
```

```json
{
  "object": "seo.ranked_keywords",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 108,
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "position": 1,
      "absolute_position": 2,
      "url": "https://redis.io/docs/cluster/",
      "title": "Redis cluster",
      "position_seen_at": "2026-09-14 04:53:47 +00:00",
      "search_traffic_estimate": 12.35
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

행에는 `keyword-ideas`의 필드에 다음 필드가 더해집니다.

| 필드                        | 설명                                               |
| ------------------------- | ------------------------------------------------ |
| `position`                | 자연 검색 결과 중 순위.                                   |
| `absolute_position`       | 검색 결과 페이지의 모든 요소를 포함한 순위.                        |
| `url`, `title`            | 순위에 오른 페이지.                                      |
| `position_seen_at`        | 해당 순위가 기록된 시점. 순위는 스냅숏이며 몇 주 또는 몇 달 전 값일 수 있습니다. |
| `search_traffic_estimate` | 이 키워드가 해당 페이지에 가져오는 월간 추정 검색 트래픽.                |

### 상위 페이지

`POST https://api.beatapi.io/v1/seo/top-pages`

도메인의 페이지를 추정 검색 트래픽이 높은 순으로 반환합니다. 필드: `domain`, `limit`, `offset`, `country`, `language`. 각 행에는 `url`과 해당 페이지의 [현황 필드](#domain-overview)가 있습니다.

```json
{
  "object": "seo.top_pages",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 1104,
  "results": [
    {
      "url": "https://redis.io/",
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58,
      "traffic_value_usd_estimate": 483101.98,
      "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
      "new": 18919,
      "up": 1048,
      "down": 1105,
      "lost": 4041
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

### 경쟁 도메인

`POST https://api.beatapi.io/v1/seo/competitors`

같은 검색 키워드로 경쟁하는 도메인을 반환합니다. 필드: `domain`, `limit`, `offset`, `country`, `language`. 조회한 도메인 자신과 youtube.com, wikipedia.org 같은 대형 범용 사이트는 행에서 제외되며, `total`은 남은 도메인 수입니다.

```json
{
  "object": "seo.competitors",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 9,
  "results": [
    {
      "domain": "example.com",
      "shared_keywords": 4706,
      "avg_position": 29.6,
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 필드                        | 설명                      |
| ------------------------- | ----------------------- |
| `domain`                  | 경쟁 도메인.                 |
| `shared_keywords`         | 두 도메인이 모두 순위에 오른 키워드 수. |
| `avg_position`            | 그 키워드들에서의 평균 순위.        |
| `ranking_keywords`        | 전체적으로 순위에 오른 키워드 수.     |
| `search_traffic_estimate` | 월간 추정 검색 트래픽.           |

## 백링크 도구

### 백링크 요약

`POST https://api.beatapi.io/v1/seo/backlink-summary`

도메인의 링크 프로필입니다. 필드는 `domain` 하나뿐입니다.

```json
{
  "object": "seo.backlink_summary",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "link_authority": 500,
  "backlinks": 920428,
  "referring_domains": 32647,
  "referring_main_domains": 28596,
  "referring_pages": 748383,
  "referring_ips": 19191,
  "broken_backlinks": 8482,
  "broken_pages": 2773,
  "spam_score": 28,
  "first_seen": "2019-01-15 22:56:44 +00:00",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 필드                                            | 설명                                             |
| --------------------------------------------- | ---------------------------------------------- |
| `link_authority`                              | 링크 프로필의 권위 점수. 이 데이터 세트 고유의 0\~1000 척도입니다.     |
| `backlinks`                                   | 발견된 링크 수.                                      |
| `referring_domains`, `referring_main_domains` | 링크하는 도메인 수, 그리고 하위 도메인을 하나로 계산한 수.             |
| `referring_pages`, `referring_ips`            | 링크하는 페이지와 IP 주소 수.                             |
| `broken_backlinks`, `broken_pages`            | 아무 곳으로도 연결되지 않는 링크 수와, 더 이상 동작하지 않는 도메인 페이지 수. |
| `spam_score`                                  | 프로필의 스팸 점수. 높을수록 스팸일 가능성이 큽니다.                 |
| `first_seen`                                  | 도메인으로 향하는 링크가 처음 발견된 시점.                       |

도메인 기록이 없으면 `has_data`는 `false`이며 다른 필드는 없고, 호출은 과금됩니다.

### 백링크

`POST https://api.beatapi.io/v1/seo/backlinks`

도메인을 가리키는 링크를 강한 순으로 반환합니다.

| 필드                | 타입      |  필수 | 설명                                                             |
| ----------------- | ------- | --: | -------------------------------------------------------------- |
| `domain`          | string  |   예 | 도메인.                                                           |
| `one_per_domain`  | boolean | 아니요 | 기본값은 `true`로, 링크하는 도메인마다 링크 하나입니다. 모든 링크를 받으려면 `false`로 설정하세요. |
| `limit`, `offset` | integer | 아니요 | [limit과 offset](#limit-and-offset)을 참고하세요.                     |

```json
{
  "object": "seo.backlinks",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 28843,
  "results": [
    {
      "source_url": "https://blog.example.com/caching",
      "source_domain": "blog.example.com",
      "source_title": "Caching notes",
      "source_authority": 493,
      "source_country": "CZ",
      "target_url": "https://redis.io/",
      "anchor": "Redis",
      "link_type": "anchor",
      "dofollow": true,
      "spam_score": 3,
      "first_seen": "2025-04-26 07:12:33 +00:00",
      "last_seen": "2026-06-18 19:14:30 +00:00",
      "is_new": false,
      "is_lost": false,
      "is_broken": false
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 필드                                            | 설명                                    |
| --------------------------------------------- | ------------------------------------- |
| `source_url`, `source_domain`, `source_title` | 링크하는 페이지.                             |
| `source_authority`                            | 링크하는 도메인의 링크 권위 점수, 0\~1000.          |
| `source_country`                              | 링크하는 도메인의 국가.                         |
| `target_url`, `anchor`                        | 링크 대상 페이지와 링크 텍스트.                    |
| `link_type`                                   | 링크 종류(예: `anchor`).                   |
| `dofollow`                                    | 링크가 권위를 전달하는지 여부.                     |
| `spam_score`                                  | 이 링크의 스팸 점수. 높을수록 스팸일 가능성이 큽니다.       |
| `first_seen`, `last_seen`                     | 링크가 처음과 마지막으로 발견된 시점.                 |
| `is_new`, `is_lost`, `is_broken`              | 링크가 새로 생겼는지, 사라졌는지, 아무 곳으로도 연결되지 않는지. |

## 수치 해석

* **검색 트래픽.** `search_traffic_estimate`는 추정 검색 트래픽이며 사이트 전체 방문 수가 아닙니다.
* **추정치.** 트래픽과 가치 수치는 추정치이며 사이트를 실측한 값이 아닙니다.
* **링크 권위.** `link_authority`는 이 데이터 세트 고유의 0\~1000 척도입니다.
* **키워드 난이도**는 이 데이터 세트 고유의 척도입니다. 다른 도구의 점수와 비교하지 마세요.
* **누락은 0이 아닙니다.** 누락된 수치는 알 수 없는 값이며 0이 아닙니다.
* **실시간 검색 결과 페이지 없음.** 실시간 검색 결과 페이지 도구는 없습니다. 특정 키워드에서 도메인의 순위를 확인하려면 `contains`와 함께 [`ranked-keywords`](#ranked-keywords)를 사용하세요. 실시간 순위가 아니라 마지막으로 기록된 순위입니다.
* **Domain Rating과 사이트 트래픽**은 [수치 해석](#reading-these-numbers)에 별도 설명이 있습니다.

## 과금

| 도구                                                                                                                          |     호출당 |   반환된 행당 |
| --------------------------------------------------------------------------------------------------------------------------- | ------: | -------: |
| `keyword-overview`, `keyword-ideas`, `keyword-difficulty`, `domain-overview`, `ranked-keywords`, `top-pages`, `competitors` | \$0.018 | \$0.0003 |
| `backlink-summary`, `backlinks`                                                                                             | \$0.035 | \$0.0002 |

Domain Rating과 사이트 트래픽은 [별도 가격](#prices-of-these-tools)이 있습니다.

* `domain-overview`와 `backlink-summary`는 기록 하나를 반환하며 이는 한 행으로 계산되고, `has_data`가 `false`이면 0행입니다. `ranked-keywords`의 100행을 반환하는 호출은 \$0.048입니다.
* 결과가 없는 호출도 호출당 요금은 부과됩니다. 거부된 요청(`400`)과 실패한 호출(`503`)은 비용이 들지 않습니다.
* 호출을 실행하기 전에 잔액이 최대 비용(`limit`의 모든 행 또는 보낸 모든 키워드)을 감당할 수 있어야 합니다. 이후에는 실제로 반환된 만큼만 청구됩니다.
* 클라이언트가 같은 요청을 재시도할 수 있다면 `Idempotency-Key` 헤더를 보내세요. 같은 키를 다른 본문으로 재사용하면 `409 idempotency_conflict`로 거부됩니다.

## 에이전트

SEO 데이터 전용 MCP 도구는 따로 없습니다. BeatAPI MCP 엔드포인트 `https://beatapi.io/mcp`에서 에이전트는 다음 레퍼런스로 `capabilities_search`, `capabilities_inspect`, `capabilities_run`을 사용합니다.

| 레퍼런스                          | 도구                   |
| ----------------------------- | -------------------- |
| `data:seo.keyword_overview`   | `keyword-overview`   |
| `data:seo.keyword_ideas`      | `keyword-ideas`      |
| `data:seo.keyword_difficulty` | `keyword-difficulty` |
| `data:seo.domain_overview`    | `domain-overview`    |
| `data:seo.ranked_keywords`    | `ranked-keywords`    |
| `data:seo.top_pages`          | `top-pages`          |
| `data:seo.competitors`        | `competitors`        |
| `data:seo.backlink_summary`   | `backlink-summary`   |
| `data:seo.backlinks`          | `backlinks`          |

Domain Rating과 사이트 트래픽의 레퍼런스는 [해당 도구와 함께 나와 있습니다](#references-for-agents).

Inspect는 입력 스키마와 현재 가격을 보여 줍니다. `input`는 도구의 요청 본문이며, Run은 결과로 응답합니다.

```json
{ "reference": "data:seo.ranked_keywords", "operation": "start", "input": { "domain": "redis.io", "contains": "cluster", "limit": 20 } }
```

같은 세 호출을 REST로 `POST /v1/capabilities/search`, `/v1/capabilities/inspect`, `/v1/capabilities/run`에서 쓸 수 있습니다. [Capabilities API](/capabilities)를 참고하세요.

## 오류

오류는 표준 BeatAPI 오류 형식을 사용하며 모든 오류에 `retryable`이 있습니다. 재시도 정책은 [오류](/errors)를 참고하세요.

```json
{
  "error": {
    "code": "bad_request",
    "message": "country 'cn' is not covered; use a two-letter code such as us, gb, de or jp (China is not covered)",
    "retryable": false,
    "request_id": "req_abc123"
  }
}
```

| HTTP 상태 | 코드                                                                    | 의미                                                                    |
| ------: | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
|     400 | `bad_request`                                                         | 잘못되었거나 알 수 없는 필드, 유효하지 않은 키워드나 도메인, 지원하지 않는 시장입니다. 메시지에 해당 필드가 표시됩니다. |
|     401 | `missing_api_key` / `invalid_api_key`                                 | 키를 보내지 않았거나 키가 잘못되었거나 만료·비활성화·소진되었습니다.                                |
|     402 | `insufficient_credits`                                                | 잔액 부족: 잔액이 0이거나 호출 가격보다 적습니다.                                         |
|     403 | `forbidden`                                                           | 키나 계정에 이 호출 권한이 없습니다.                                                 |
|     409 | `idempotency_conflict`                                                | `Idempotency-Key`를 다른 본문으로 재사용했습니다.                                   |
|     429 | `rate_limit_exceeded`                                                 | 요청이 너무 많습니다. `retry_after_seconds`만큼 기다리세요.                           |
|     500 | `internal_error`                                                      | 예기치 않은 내부 오류입니다. 재시도할 수 있습니다.                                         |
|     503 | `processing_unavailable`, `processing_timeout` 또는 `processing_failed` | SEO 데이터를 일시적으로 사용할 수 없거나 호출이 너무 오래 걸렸습니다. 백오프를 두고 재시도하세요.             |

`503`은 과금되지 않습니다. BeatAPI는 `502`로 응답하지 않습니다.

## Domain Rating과 사이트 트래픽

도구 세 개가 더 있으며 같은 방식으로 동작합니다. 같은 키, 응답으로 바로 반환되는 결과, 같은 `usage`와 오류를 사용합니다. `domain`을 받고 시장 개념이 없으므로 `country`와 `language`는 거부됩니다. `limit`이나 `offset`은 없습니다.

| 필요한 것                          | 도구                      |
| ------------------------------ | ----------------------- |
| SEO 팀이 도메인을 비교할 때 쓰는 0\~100 점수 | `domain-rating`         |
| 그 점수의 월별 추이                    | `domain-rating-history` |
| 사이트 전체 방문 수, 유입 경로, 방문자 행동     | `site-traffic`          |

### Domain Rating

`POST https://api.beatapi.io/v1/seo/domain-rating`

```bash
curl https://api.beatapi.io/v1/seo/domain-rating \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io"}'
```

```json
{
  "object": "seo.domain_rating",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "domain_rating": 90,
  "link_rank": 1927,
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

`domain_rating`은 0\~100입니다. `link_rank`는 링크 기준 도메인의 전 세계 순위이며, 낮을수록 강합니다.

### Domain Rating 기록

`POST https://api.beatapi.io/v1/seo/domain-rating-history`

```json
{
  "object": "seo.domain_rating_history",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "results": [
    { "month": "2025-12", "domain_rating": 89 },
    { "month": "2026-01", "domain_rating": 89 },
    { "month": "2026-02", "domain_rating": 89 },
    { "month": "2026-03", "domain_rating": 89 },
    { "month": "2026-04", "domain_rating": 89 },
    { "month": "2026-05", "domain_rating": 89 },
    { "month": "2026-06", "domain_rating": 90 },
    { "month": "2026-07", "domain_rating": 90 },
    { "month": "2026-08", "domain_rating": 90 },
    { "month": "2026-09", "domain_rating": 90 },
    { "month": "2026-10", "domain_rating": 90 }
  ],
  "billed_rows": 11,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.044",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

알 수 없는 도메인은 `has_data: false`, 빈 `results`, `billed_rows: 1`을 반환합니다.

### 사이트 트래픽

`POST https://api.beatapi.io/v1/seo/site-traffic`

모든 채널에서 웹사이트로 들어온 추정 전체 방문 수와 유입 경로, 국가, 순위, 참여도.

| 필드       | 타입      |  필수 | 설명                              |
| -------- | ------- | --: | ------------------------------- |
| `domain` | string  |   예 | 도메인.                            |
| `months` | integer | 아니요 | 기록 개월 수: `3`(기본값), `6` 또는 `12`. |

```bash
curl https://api.beatapi.io/v1/seo/site-traffic \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","months":3}'
```

```json
{
  "object": "seo.site_traffic",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "months": 3,
  "has_data": true,
  "site_visits_estimate": 734682,
  "monthly_visits": [
    { "month": "2026-07", "visits": 827501 },
    { "month": "2026-08", "visits": 789909 },
    { "month": "2026-09", "visits": 734682 }
  ],
  "global_rank": 66213,
  "country_rank": { "country": "IN", "rank": 19016 },
  "category": "computers_electronics_and_technology/programming_and_developer_software",
  "category_rank": 634,
  "bounce_rate": 0.4254,
  "pages_per_visit": 3.3174,
  "avg_visit_seconds": 116.2764,
  "traffic_sources": {
    "direct": 0.3293,
    "search": 0.4836,
    "paid_search": 0.0072,
    "social": 0.0435,
    "paid_social": 0.0026,
    "referrals": 0.0992,
    "mail": 0.0114,
    "display_ads": 0.0035,
    "affiliate": 0,
    "gen_ai": 0.0197
  },
  "top_countries": [{ "country": "IN", "share": 0.1995 }],
  "top_keywords": [{ "keyword": "redis", "search_volume": 193980, "cpc_usd": 2.78 }],
  "title": "Redis - Real-time data for agents & apps",
  "description": "Developers love Redis. Unlock the full potential of the Redis database with Redis Enterprise and start building blazing fast apps.",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 필드                                     | 설명                                           |
| -------------------------------------- | -------------------------------------------- |
| `site_visits_estimate`                 | 최근 한 달의 추정 방문 수.                             |
| `monthly_visits[]`                     | 월별 `month`와 `visits`.                        |
| `global_rank`                          | 전체 사이트 중 순위. 낮을수록 큽니다.                       |
| `country_rank`                         | 한 국가에서의 순위: `country`, `rank`.               |
| `category`, `category_rank`            | 사이트 카테고리와 그 카테고리 내 순위.                       |
| `bounce_rate`                          | 한 페이지만 보고 떠난 방문 비율, 0\~1.                    |
| `pages_per_visit`, `avg_visit_seconds` | 방문당 페이지 조회 수와 평균 방문 시간(초).                   |
| `traffic_sources`                      | 채널별 방문 비율, 0\~1.                             |
| `top_countries[]`                      | 방문이 가장 많은 국가와 각 국가의 `share`(0\~1).           |
| `top_keywords[]`                       | 검색 방문을 가져오는 키워드와 `search_volume`, `cpc_usd`. |
| `title`, `description`                 | 사이트 자체의 제목과 설명.                              |

### 수치 해석

* **두 종류의 트래픽.** `search_traffic_estimate`는 추정 검색 트래픽이고 `site_visits_estimate`는 모든 채널의 전체 방문 수입니다. 서로 다른 지표이므로 더하거나 비교하지 마세요. 방문 수는 순 방문자 수가 아닙니다.
* **두 가지 권위 점수.** `link_authority`는 이 데이터 세트 고유의 0~~1000 척도이고, `domain_rating`은 0~~100입니다. 서로 변환할 수 없습니다.
* **기록 없음.** `has_data: false`는 도메인 기록이 없다는 뜻이며, 점수나 트래픽이 0인 것과 다릅니다. 새 사이트는 점수가 `0`이면서 `link_rank`일 수 있습니다.

### 도구별 가격

| 도구                      |             가격 |
| ----------------------- | -------------: |
| `domain-rating`         |    호출당 \$0.005 |
| `domain-rating-history` | 반환된 월당 \$0.004 |
| `site-traffic`, 3개월     |        \$0.005 |
| `site-traffic`, 6개월     |         \$0.01 |
| `site-traffic`, 12개월    |        \$0.015 |

* `has_data`가 `false`이면 `domain-rating`과 `site-traffic`이 과금됩니다. 알 수 없는 도메인에 대한 `domain-rating-history`는 월 데이터를 반환하지 않으며 1개월분인 \$0.004가 청구됩니다.
* 거부된 요청(`400`)과 실패한 호출(`503`)은 비용이 들지 않습니다.
* `domain-rating-history`를 실행하기 전에 잔액이 24개월 기록 비용을 감당할 수 있어야 합니다. 이후에는 실제로 반환된 만큼만 청구됩니다.

### 에이전트용 레퍼런스

| 레퍼런스                             | 도구                      |
| -------------------------------- | ----------------------- |
| `data:seo.domain_rating`         | `domain-rating`         |
| `data:seo.domain_rating_history` | `domain-rating-history` |
| `data:seo.site_traffic`          | `site-traffic`          |