跳转到内容
CoreClaw Logo CoreClaw

运行 Worker

方法： POST

端点： /api/v1/scraper/run

使用 Content-Type: application/json 发送请求体。

在线试用

Section titled “在线试用”
POST/api/v1/scraper/runStart scraper run
Required

Stored only in this browser tab. Sent only to https://openapi.coreclaw.com.

BodyRequiredapplication/json
FieldTypeRequiredDescription
scraper_slugstringyesUnique scraper identifier.
versionstringyesScraper version. Must be copied from `/api/scraper` -> `data.version`.
is_asyncbooleanyes`true` returns immediately with `run_slug`; `false` performs a synchronous execution flow.
inputobjectyes
callback_urlstring—Webhook URL for async completion callbacks. Optional; include it when webhook orchestration is needed.
Request body (JSON)

什么时候使用这个接口

Section titled “什么时候使用这个接口”

当您希望通过 scraper_slug 直接启动某个 Worker 时，使用这个接口。

scraper_slug 从哪里来

Section titled “scraper_slug 从哪里来”

scraper_slug 是 Worker ID——每个 Worker 的唯一标识符。每个 Worker 都有一个固定的 scraper_slug。

获取方式：

请求示例

Section titled “请求示例”
{
    "scraper_slug": "YOUR_SCRAPER_SLUG",
    "version": "YOUR_WORKER_VERSION",
    "input": {
        "parameters": {
            "system": {
                "cpus": 0.125,
                "memory": 512,
                "execute_limit_time_seconds": 1800,
                "max_total_charge": 0,
                "max_total_traffic": 0,
                "proxy_region": "CH"
            },
            "custom": {
                "startURLs": [
                    {
                        "url": "https://example.com"
                    }
                ]
            }
        }
    },
    "callback_url": "https://your-callback.example.com/webhook",
    "is_async": true
}

参数

Section titled “参数”
参数必填类型说明
scraper_slug是stringWorker ID——要运行的 Worker 的唯一标识符
version是stringWorker 版本
input是object输入参数
is_async是booleantrue：异步执行（默认），false：同步执行（等待完成）
callback_url否string用于接收运行结果的回调地址

system 参数

Section titled “system 参数”
参数示例类型必填说明
proxy_regionUSstring否执行节点（ISO 3166-1 alpha-2 国家代码）。常用：US、CN、HK、JP、SG、DE、GB、FR。完整支持列表请参考 Swagger 定义。
cpus0.125number是容器 CPU 核心数
memory512integer是容器内存大小（MB）。支持的值：512、1024、2048、4096、8192、16384
execute_limit_time_seconds1800integer是容器执行超时（秒）
max_total_charge0integer是最大费用（美元）
max_total_traffic0integer是最大流量（MB）

custom 参数

Section titled “custom 参数”

input.parameters.custom 不是固定结构——每个 Worker 各不相同。以下两种方式可查看具体字段：

  • API：调用 GET /api/scraper?slug=<scraper_slug>，从响应的 data.parameters.custom 获取。properties[] 中每一项对应 input.parameters.custom 的一个字段。
  • Console：在 CoreClaw Console 中打开该 Worker，进入 Input 选项卡，点击右上角的 API 按钮，选择 API clients 即可查看可直接使用的代码片段。

Worker Input 选项卡中的 API clients 按钮

构造 custom 时：

  • 使用 properties[].name 作为字段名
  • 严格匹配声明的 type、嵌套结构和数组形状
  • 对于 required: true 的字段，必须显式提供
  • 如果 custom 为空，或结构不匹配，接口会返回 400 Bad Request

如何获取 version

Section titled “如何获取 version”

可以从以下位置获得 Worker 版本：

校验行为

Section titled “校验行为”
  • callback_url 在此端点可选。在 /api/v1/task/run 和 /api/v1/rerun 中必填。
  • 请勿将 run_slug（运行记录 ID）或 task_slug（任务 ID）传入 scraper_slug 字段——每种 slug 类型不同，不可互换。
  • 如果只提供通用 system 参数，但缺少该 Worker 描述符要求的 custom 字段，请求仍会失败。

响应示例

Section titled “响应示例”
{
    "code": 0,
    "message": "success",
    "data": {
        "run_slug": "01KSFDS8XWTJME33C08XMCR6B9"
    }
}

响应字段

Section titled “响应字段”
参数示例类型说明
code0Integer全局状态码
messagesuccessString响应消息
data-Object响应数据
run_slug01KSFDS8XWTJME33C08XMCR6B9String运行记录 ID——本次执行的唯一标识符