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

# 创建爬虫

> 启动一个新的爬虫。你会收到一个 `id` 用于跟踪进度。操作可能需要1-10分钟，具体取决于站点、深度和页面参数。

<Tip>
  **完成时获取通知：** 传递 `webhook` 参数和你的端点 URL，以便在爬虫完成时接收一个 HTTP POST。详情请参阅 [Webhooks](/api-reference/common/webhooks)。
</Tip>


## OpenAPI

````yaml zh/openapi/crawls.json POST /v1/crawls
openapi: 3.0.3
info:
  title: 爬虫 API
  version: 1.0.0
servers:
  - url: https://api.olostep.com
security: []
paths:
  /v1/crawls:
    post:
      summary: 开始新的爬虫
      description: 使用指定的参数启动新的爬虫过程。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_url:
                  type: string
                  description: 爬虫的起始点。
                include_urls:
                  type: array
                  items:
                    type: string
                  description: >-
                    使用 glob 语法在爬虫中包含的 URL 路径模式。  默认为 `/**`，包括所有 URL。使用类似
                    `/blog/**` 的模式来爬取特定部分（例如，仅博客页面），`/products/*.html`
                    用于产品页面，或多个模式用于不同部分。支持标准的 glob 特性，如 *（任意字符）和 **（递归匹配）。
                exclude_urls:
                  type: array
                  items:
                    type: string
                  description: 在 glob 模式中排除的 URL 路径名称。例如：`/careers/**`。排除的 URL 将优先于包含的 URL。
                max_pages:
                  type: number
                  description: 爬取的最大页面数量。推荐用于大多数用例，如爬取整个网站。
                max_depth:
                  type: number
                  description: 爬虫的最大深度。用于仅提取最多 n 级链接。
                include_external:
                  type: boolean
                  description: 爬取一级外部链接。
                include_subdomain:
                  type: boolean
                  description: 包含网站的子域名。默认 `false`。
                search_query:
                  type: string
                  description: 可选的搜索查询，用于查找特定链接并按相关性排序结果。
                top_n:
                  type: number
                  description: 可选的数字，仅爬取每个页面上根据搜索查询最相关的前 N 个链接。
                webhook:
                  type: string
                  format: uri
                  description: >-
                    爬虫完成时接收 POST 请求的 HTTPS URL。必须是使用 `http://` 或 `https://`
                    协议的公开可访问 URL。不能指向 localhost 或私有 IP 地址。查看
                    [Webhooks](/api-reference/common/webhooks) 了解负载格式和重试行为。
                timeout:
                  type: number
                  description: 在 n 秒后结束爬虫，并完成到那时为止的页面。可能会比提供的超时多花费约 10 秒。
                follow_robots_txt:
                  type: boolean
                  description: >-
                    是否遵守 robots.txt 规则。如果设置为 `false`，爬虫将不顾 robots.txt
                    的禁止指令抓取网站。默认 `true`。
                  default: true
                scrape_options:
                  type: object
                  description: 控制每个单独页面从 Olostep API 请求的内容。所有字段都是可选的。
                  properties:
                    formats:
                      type: array
                      items:
                        type: string
                        enum:
                          - html
                          - markdown
                          - text
                          - json
                          - screenshot
                      description: >-
                        请求每个抓取页面的输出格式。省略时默认为 `["html", "markdown"]`。`html`
                        总是自动包含。当提供 `parser` 时，`json` 会自动添加。注意：`raw_pdf` 不支持 —
                        PDF 无法被爬取。
                      example:
                        - markdown
                        - screenshot
                    parser:
                      type: string
                      description: >-
                        在每个页面上运行的解析器名称，并生成结构化的 `json` 输出（例如
                        `"@olostep/extract-emails"`）。设置时自动将 `json` 添加到
                        `formats`。
                      example: '@olostep/extract-emails'
              required:
                - start_url
                - max_pages
      responses:
        '200':
          description: 爬虫启动成功。
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 爬虫 ID
                  object:
                    type: string
                    description: 对象的类型。此端点为 "crawl"。
                  status:
                    type: string
                    description: '`in_progress` 或 `completed`'
                  created:
                    type: number
                    description: 创建时间（epoch格式）
                  start_date:
                    type: string
                    description: 创建时间（日期格式）
                  start_url:
                    type: string
                  max_pages:
                    type: number
                  max_depth:
                    type: number
                  exclude_urls:
                    type: array
                    items:
                      type: string
                  include_urls:
                    type: array
                    items:
                      type: string
                  include_external:
                    type: boolean
                  search_query:
                    type: string
                  top_n:
                    type: number
                  current_depth:
                    type: number
                    description: 爬取过程的当前深度。
                  pages_count:
                    type: number
                    description: 已爬取页面的数量
                  webhook:
                    type: string
                  follow_robots_txt:
                    type: boolean
                  credits_consumed:
                    type: integer
                    nullable: true
                    description: 此请求消耗的积分数量。在执行完成后填充。积分是计费的真实来源。
                  cost_usd:
                    type: number
                    nullable: true
                    description: >-
                      此请求的估计成本（以美元计）。在执行完成后填充。根据消耗的积分和你的计划费率计算——99% 准确，但
                      credits_consumed 是权威值。
        '400':
          description: 由于参数错误或缺失导致的错误请求。
        '500':
          description: 内部服务器错误。
      security:
        - Authorization: []
components:
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: Bearer认证头格式为Bearer <token>，其中<token>是你的认证令牌。

````