> ## 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.

# 웹사이트를 Markdown으로 크롤링하는 API (WEB_CRAWL)

> 시작 주소에서 사이트를 크롤링해 각 페이지를 Markdown으로 받습니다. 반환한 페이지 수만큼 과금합니다.

`WEB_CRAWL`은 시작 주소에서 사이트의 링크를 너비 우선으로 따라가며 각 페이지를 [`WEB_SCRAPE`](/ko/engines/web-scrape)처럼 읽습니다. 모든 페이지의 Markdown, 메타데이터, 이미지를 결과 하나로 받습니다.

| | |
| - | - |
| `taskType` | `WEB_CRAWL` |
| 입력 | `url`(필수), `maxPages`, `maxDepth`, `maxChars`, `includePaths`, `excludePaths`, `includeSubdomains`, `country` |
| 크레딧 | 반환한 페이지당 1. 제출할 때 `maxPages`만큼 크레딧을 예약합니다. |
| 국가 | 기본값 `US`. |
| 위치 | 지원하지 않습니다(`422 LOCATION_UNSUPPORTED`). |

## 요청

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "WEB_CRAWL", "payload": { "url": "https://www.example.com/docs", "maxPages": 25, "maxDepth": 2, "includePaths": ["/docs/**"] } }'
```

## 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| `url` | 예 | 시작 주소. `WEB_SCRAPE`와 규칙이 같습니다: 공개 `http` 또는 `https`, 기본 포트, 최대 2,048자. 시작 페이지는 패턴과 `robots.txt`에 관계없이 항상 읽습니다. |
| `maxPages` | 아니요 | 시작 페이지를 포함해 읽을 페이지 수, 1\~100의 정수. 기본값은 10입니다. |
| `maxDepth` | 아니요 | 시작 페이지에서 링크를 따라가는 횟수, 0\~5의 정수. 기본값은 2이며, `0`이면 시작 페이지만 읽습니다. |
| `maxChars` | 아니요 | 페이지마다 `markdown` 길이 상한, 1,000\~50,000의 정수. 기본값은 20,000입니다. |
| `includePaths`, `excludePaths` | 아니요 | [`WEB_MAP`](/ko/engines/web-map)과 같은 경로 패턴: 각각 최대 20개, `/`로 시작, 200자 이하. `*`는 한 마디 안, `**`는 여러 마디에 맞습니다. `excludePaths`가 우선합니다. |
| `includeSubdomains` | 아니요 | `true`면 사이트의 하위 도메인으로 가는 링크도 따라갑니다. 기본값은 `false`입니다. |
| `country` | 아니요 | 페이지를 요청하는 지역. 기본값은 `US`입니다. |

크롤은 같은 사이트에 머물고(`www.`는 있든 없든 같은 사이트), 경로 패턴에 맞고, 파일이 아닌 웹 페이지로 가며(PDF, 이미지, 압축 파일 등 파일은 건너뜀), 사이트 `robots.txt`가 모든 크롤러에 허용한 링크를 따라갑니다.

## 응답

예:

```json theme={"theme":"css-variables"}
{
  "url": "https://www.example.com/docs",
  "pages": [
    {
      "url": "https://www.example.com/docs",
      "finalUrl": "https://www.example.com/docs",
      "depth": 0,
      "statusCode": 200,
      "title": "...",
      "markdown": "# ...",
      "images": [],
      "truncated": false
    }
  ],
  "failed": [{ "url": "https://www.example.com/docs/old", "depth": 1, "error": "the site answered 404 for this page" }],
  "stopReason": "max-pages"
}
```

| 필드 | 설명 |
| - | - |
| `pages` | 읽은 페이지, 크롤이 발견한 순서대로. 각 페이지에는 `WEB_SCRAPE`의 필드와 시작 페이지에서 따라간 링크 횟수인 `depth`가 담깁니다. |
| `failed` | 읽지 못한 페이지. 각각 `url`, `depth`, 사이트가 밝힌 이유인 `error`가 담깁니다. |
| `stopReason` | 크롤이 끝난 이유. 아래를 참고하세요. |

| `stopReason` | 의미 |
| - | - |
| `done` | 따라갈 링크가 남지 않았습니다. |
| `max-pages` | `maxPages`만큼 페이지를 읽었습니다. |
| `failures` | 연속 10쪽을 읽지 못했거나, 실패한 페이지 수가 `maxPages`에 닿았습니다. |
| `time` | 크롤 시간이 다 되었습니다. 약 4분이 지나면 새 페이지를 시작하지 않습니다. |

## 크레딧

제출할 때 태스크는 `maxPages`의 페이지마다 1크레딧을 예약합니다(위 예에서는 25크레딧). 완료되면 `pages`에 담긴 페이지마다 1크레딧을 과금하고 나머지 예약은 풀립니다. `failed`의 페이지는 과금하지 않습니다. 25쪽 중 3쪽을 반환한 크롤은 3크레딧입니다. 예약 방식은 [크레딧과 한도](/ko/concepts/credits-and-limits.md)를 참고하세요.

## 제한과 오류

* 시작 페이지를 읽을 수 없으면 태스크는 `PAGE_UNAVAILABLE`로 실패합니다. 다른 페이지를 읽지 못하면 `failed`에 담고 크롤을 계속합니다.
* 잘못된 옵션은 필드를 명시한 `422 VALIDATION_ERROR`를 반환합니다.
* `WEB_CRAWL`은 `markdown`, `rawResponse`, `searchQueries`를 무시합니다. `html`과 `analysis`는 `422`로, `citationAnalysis`는 `400`으로 거절합니다. [지원하지 않는 플래그](/ko/engines/response-options.md#지원하지-않는-플래그)를 참고하세요.
* 그 밖의 요청 오류는 [오류](/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 페이지를 읽지 않고 사이트 주소 목록만 받는 [웹 맵](/ko/engines/web-map.md)
* 페이지 하나를 읽는 [웹 스크레이프](/ko/engines/web-scrape.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.