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

# 同步抓取

> `scrape` 端点运行浏览器会话、执行 JavaScript，并在单次同步请求中返回渲染后的 HTML。

## 入门

### 基础 URL

```
https://scrape.cleariflow.com/v1/scrape
```

### 请求示例

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://example.com",
    "render": {
      "wait_until": "networkidle",
      "timeout_ms": 60000
    }
  }'
```

成功请求将返回渲染后的页面 HTML 及元数据：

```json theme={"system"}
{
  "ok": true,
  "html": "<!DOCTYPE html><html>...</html>",
  "meta": {
    "elapsed_ms": 4521
  }
}
```

### 渲染选项

`render` 对象控制浏览器在捕获 HTML 前如何加载页面。所有字段均为可选，省略时使用服务器默认值。

```json theme={"system"}
{
  "render": {
    "wait_until": "networkidle",
    "timeout_ms": 60000,
    "post_load_wait_ms": 2000,
    "ignore_https_errors": false
  }
}
```

| 字段 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `wait_until` | String | `domcontentloaded` | 何时视为导航完成。需要更快结果用 `domcontentloaded`；初始 HTML 后仍通过 XHR/fetch 加载数据的页面用 `networkidle`。 |
| `timeout_ms` | Integer | `60000` | 等待页面加载的最长时间（毫秒），超时则请求失败。 |
| `post_load_wait_ms` | Integer | `0` | `wait_until` 之后、捕获 HTML 前的额外延迟（毫秒）。适用于动画、懒加载组件或 `networkidle` 后仍在客户端渲染的内容。 |
| `ignore_https_errors` | Boolean | `false` | 为 `true` 时忽略目标页面的 TLS 证书错误。 |

JavaScript 较多、加载后仍持续拉取数据的页面示例:

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://quotes.toscrape.com/js/",
    "render": {
      "wait_until": "networkidle",
      "timeout_ms": 60000,
      "post_load_wait_ms": 1500,
      "ignore_https_errors": false
    }
  }'
```

### 资源选项

`resources` 对象控制浏览器在抓取过程中加载哪些资源类型。当您只需要 HTML 文本和结构时，阻止重型资源可加快请求速度。

```json theme={"system"}
{
  "resources": {
    "block": ["images", "fonts", "media"]
  }
}
```

| 值 | 阻止 |
| - | - |
| `images` | 图片（`<img>`、CSS 背景、作为图片加载的 SVG 图标） |
| `fonts` | Web 字体 |
| `media` | 视频和音频流 |

所有字段均为可选。省略 `resources` 时，除非部署配置了服务器端默认值，否则不会阻止任何资源类型。

示例 — 跳过图片和字体以加快抓取:

```bash theme={"system"}
curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://quotes.toscrape.com/",
    "resources": {
      "block": ["images", "fonts"]
    }
  }'
```

### 请求参数

**url** `String` *required*

要抓取的目标 URL。必须是公开的 HTTP 或 HTTPS URL。对 localhost 和私有 IP 的请求会被 SSRF 防护阻止。

**api\_key** `String` *required*

您的唯一 API 密钥。

**session\_id** `String`

可选会话 ID，用于在多次抓取请求间复用浏览器状态（Cookie、本地存储）。

**fingerprint** `String`

浏览器指纹预设。支持值：`desktop_en_us`、`desktop_ru_ru`、`mobile_en_us`。

**render** `Object`

浏览器会话的渲染选项。

**render.wait\_until** `String`

判定导航完成的时机。值：`domcontentloaded`、`networkidle`。默认：`domcontentloaded`。

**render.timeout\_ms** `Integer`

等待页面加载的最长时间（毫秒）。默认：60000。

**render.post\_load\_wait\_ms** `Integer`

页面加载事件后、捕获内容前的额外等待时间（毫秒）。

**render.ignore\_https\_errors** `Boolean`

为 `true` 时忽略目标页面的 TLS 证书错误。

**resources** `Object`

资源加载控制。

**resources.block** `Array`

要阻止的资源类型。支持值：`images`、`fonts`、`media`。

**actions** `Array`

捕获内容前执行的浏览器操作有序列表。每个操作是包含 `type` 字段的对象。

**actions\[].type** `String` *required*

操作类型。支持值：`wait`、`wait_for`、`click`、`type`、`scroll`。

**actions\[].selector** `String`

用于 `wait_for`、`click` 或 `type` 操作的 CSS 选择器。

**actions\[].text** `String`

`type` 操作要输入的文本。

**actions\[].to** `String`

`scroll` 操作的滚动目标（如 `bottom`）。

**actions\[].wait\_ms** `Integer`

`wait` 操作的等待时长（毫秒）。

**actions\[].timeout\_ms** `Integer`

`wait_for` 操作的超时时间（毫秒）。

**cookies** `Array`

导航前注入的 Cookie。每个 Cookie 对象需要 `name` 和 `value`；可选字段：`domain`、`path`。

### 响应参数

API 响应以通用轻量的 [JSON 格式](https://www.json.org/json-en.html) 返回。

**ok** `Boolean`

抓取是否成功完成。

**html** `String`

渲染后的页面 HTML。

**meta** `Object`

抓取元数据，包括最终 URL、HTTP 状态码和处理时长。

**error** `Object`

当 `ok` 为 `false` 时的错误详情。


## OpenAPI

````yaml openapi/scrape.json POST /v1/scrape
openapi: 3.0.3
info:
  title: Web Scraping API (Browser-as-a-Service)
  version: 1.0.0
  description: High-load browser scraping API backed by Camoufox workers.
servers:
  - url: https://scrape.cleariflow.com
    description: Production server
security: []
paths:
  /v1/scrape:
    post:
      summary: Synchronous scrape (Camoufox)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
      responses:
        '200':
          description: Scrape result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Quota reached
        '429':
          description: Too many requests
        '500':
          description: Internal server error
components:
  schemas:
    ScrapeRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        api_key:
          type: string
          description: Your Cleariflow API key, passed in the JSON request body.
        session_id:
          type: string
        fingerprint:
          type: string
          description: Preset string (desktop_en_us|desktop_ru_ru|mobile_en_us|...)
        render:
          $ref: '#/components/schemas/RenderOptions'
        resources:
          $ref: '#/components/schemas/ResourceOptions'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        artifacts:
          type: array
          items:
            type: string
            enum:
              - html
              - screenshot
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
    ScrapeResponse:
      type: object
      properties:
        ok:
          type: boolean
        html:
          type: string
        artifacts:
          type: object
          additionalProperties: true
        meta:
          type: object
          additionalProperties: true
        error:
          type: object
          additionalProperties: true
    RenderOptions:
      type: object
      properties:
        wait_until:
          type: string
          enum:
            - domcontentloaded
            - networkidle
        timeout_ms:
          type: integer
        post_load_wait_ms:
          type: integer
    ResourceOptions:
      type: object
      properties:
        block:
          type: array
          items:
            type: string
            enum:
              - images
              - fonts
              - media
    Action:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - wait
            - wait_for
            - click
            - type
            - scroll
        selector:
          type: string
        text:
          type: string
        to:
          type: string
        wait_ms:
          type: integer
        timeout_ms:
          type: integer
    Cookie:
      type: object
      required:
        - name
        - value
      properties:
        path:
          type: string
        value:
          type: string
        name:
          type: string
        domain:
          type: string

````

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