> ## 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_SCRAPE)

> 웹 페이지나 PDF 하나를 읽어 본문을 Markdown으로, 제목, 메타데이터, 이미지와 함께 받습니다.

`WEB_SCRAPE`는 페이지 하나를 읽어 본문을 Markdown으로 반환합니다. 제목, 문단, 목록, 표, 링크, 이미지가 들어가고 사이트의 헤더, 푸터, 내비게이션은 빠집니다. 쇼핑몰 상품 페이지처럼 스크립트가 그리는 페이지는 화면을 그린 뒤에 읽습니다. 검색 결과를 읽으려면 [`GOOGLE_SERP`](/ko/engines/google-serp) `organicResults`의 `link`를 넣으세요.

| | |
| - | - |
| `taskType` | `WEB_SCRAPE` |
| 입력 | `url`(필수), `maxChars`, `country` |
| 크레딧 | 태스크당 1, 여러 페이지 PDF 포함 |
| 국가 | 보내지 않으면 `US`, 쿠팡과 올리브영 쇼핑 페이지는 `KR`. |
| 위치 | 지원하지 않습니다(`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_SCRAPE", "payload": { "url": "https://www.example.com/guide", "maxChars": 50000 } }'
```

태스크는 비동기로 실행됩니다. 결과는 [비동기 태스크](/ko/concepts/async-tasks.md)에 설명한 방법으로 읽으세요.

## 파라미터

| 필드 | 필수 | 설명 |
| - | - | - |
| `url` | 예 | 기본 포트를 쓰는 공개 `http` 또는 `https` 주소, 최대 2,048자. 인증 정보가 든 주소, 사설·내부 호스트, 다른 포트는 `422 VALIDATION_ERROR`를 반환합니다. |
| `maxChars` | 아니요 | `markdown` 길이 상한, 1,000\~200,000의 정수. 기본값은 100,000입니다. |
| `country` | 아니요 | 페이지를 요청하는 언어와 지역. 생략하면 국내 쿠팡·올리브영 쇼핑 페이지는 `KR`, 나머지는 `US`를 사용합니다. |

## 응답

예:

```json theme={"theme":"css-variables"}
{
  "url": "https://www.example.com/guide",
  "finalUrl": "https://www.example.com/guide",
  "statusCode": 200,
  "title": "...",
  "description": "...",
  "author": "...",
  "publishedAt": "2026-09-12T07:36:36Z",
  "siteName": "...",
  "language": "en",
  "image": "https://...",
  "markdown": "# ...\n\n...\n\n![...](https://...)",
  "images": [{ "url": "https://...", "alt": "..." }],
  "truncated": false
}
```

| 필드 | 설명 |
| - | - |
| `url` | 보낸 주소. |
| `finalUrl` | 리다이렉트를 따라간 뒤의 주소. |
| `statusCode` | 읽은 페이지의 HTTP 상태. |
| `markdown` | 본문. 완료된 태스크에서는 비어 있지 않습니다. |
| `images` | `markdown`에 나오는 이미지를 나온 순서대로 담습니다. |
| `truncated` | `markdown`이 `maxChars`에서 멈췄으면 `true`. 가능하면 문단 경계에서 자릅니다. |
| `title`, `description`, `author`, `publishedAt`, `siteName`, `language`, `image` | 페이지가 밝힌 값이 있을 때 들어갑니다. |

## PDF

HTML, 일반 텍스트, 텍스트 내장 PDF를 지원합니다. PDF는 페이지 순서의 텍스트와, 있으면 제목·저자·주제(`description`)·언어를 반환하며 `images: []`입니다. OCR, 첨부 파일, 원본 배치 복원은 지원하지 않습니다.

| PDF 제한 | 값 |
| - | - |
| 다운로드 크기 | 8 MiB |
| 페이지 | 100 |
| 추출 텍스트 | 1,000,000자 |
| 추출 시간 | 20초 |

`maxChars`와 무관하게 전체 문서를 검사하며, 반환하는 Markdown만 줄입니다. 텍스트 없음·암호화·손상·불완전한 다운로드·제한 초과 PDF는 `PAGE_UNAVAILABLE`로 실패합니다.

## 제한과 오류

* 읽을 수 없는 페이지는 태스크를 `PAGE_UNAVAILABLE`과 이유로 실패시킵니다: 지원하지 않는 형식, 404나 410을 돌려주는 페이지, 요청을 거절한 사이트.
* `url` 규칙을 어기는 주소로 리다이렉트되면 태스크가 실패합니다. 규칙은 리다이렉트마다 다시 검사합니다.
* `WEB_SCRAPE`는 `markdown`, `rawResponse`, `searchQueries`를 무시합니다. `html`과 `analysis`는 `422`로, `citationAnalysis`는 `400`으로 거절합니다. [지원하지 않는 플래그](/ko/engines/response-options.md#지원하지-않는-플래그)를 참고하세요.
* 그 밖의 요청 오류는 [오류](/ko/concepts/errors.md)에 정리되어 있습니다.

## 관련 문서

* 한 사이트의 여러 페이지를 읽는 [웹 크롤](/ko/engines/web-crawl.md)
* 사이트 주소 목록을 먼저 받는 [웹 맵](/ko/engines/web-map.md)


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