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

# 异步请求

> 网页抓取 API 异步请求

将多个请求排队并立即接收 `task_id` - 任务完成后，您可以使用该 `task_id` 检索请求结果。

## 排队单个任务

##### 单个查询或 URL 端点：`https://scraper-api.decodo.com/v3/task`

向此端点发出 `POST` 请求，使用您首选的参数来接收 `task_id`，以便在任务完成后检索，同时还会返回使用的参数。

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v3/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "url": "https://ip.decodo.com"
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task", {
      method: "POST",
      body: JSON.stringify({
        "url": "https://ip.decodo.com"
      }),
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests
    
  url = "https://scraper-api.decodo.com/v3/task"
    
  payload = {
        "url": "https://ip.decodo.com"
  }
    
  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }
    
  response = requests.post(url, json=payload, headers=headers)
    
  print(response.text)
  ```
</CodeGroup>

#### 响应示例：

<CodeGroup>
  ```json JSON expandable theme={null}
  {
    "url": "https://ip.decodo.com",
    "page_from": 1,
    "limit": 10,
    "geo": null,
    "device_type": "desktop",
    "headless": null,
    "parse": false,
    "locale": null,
    "domain": "com",
    "output_schema": null,
    "created_at": "2026-03-04 11:51:04",
    "id": "7434928397127555073",
    "status": "pending",
    "content_encoding": "utf-8",
    "updated_at": "2026-03-04 11:51:04",
    "page_count": 1,
    "http_method": "get",
    "cookies": [],
    "force_headers": false,
    "force_cookies": false,
    "headers": [],
    "session_id": null,
    "successful_status_codes": [],
    "follow_redirect": null,
    "payload": null,
    "store_id": null,
    "headers_cookies_policy": false
  }
  ```
</CodeGroup>

***

## 使用 task\_id 检索结果

##### **单个查询或 URL 端点：** `https://scraper-api.decodo.com/v3/task/{task_id}/results`

向此端点发出 GET 请求，将 `{task_id}` 替换为从之前的 POST 请求中收到的 ID 以检索结果。

<Note>
  结果可以在初始请求后的 24 小时内无限次检索
</Note>

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'GET' \
          --url 'https://scraper-api.decodo.com/v3/task/{task_id}/results' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task/{task_id}/results", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests

  task_id = "TASK_ID"

  url = f"https://scraper-api.decodo.com/v3/task/{task_id}/results"

  headers = {
      "accept": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }

  response = requests.get(url, headers=headers)
  ```
</CodeGroup>

***

## 使用 task\_id 获取任务状态

可以手动检查异步任务状态：

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'GET' \
          --url 'https://scraper-api.decodo.com/v3/task/{task_id}' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task/{task_id}", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests

  task_id = "TASK_ID"

  url = f"https://scraper-api.decodo.com/v3/task/{task_id}"

  headers = {
      "accept": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }

  response = requests.get(url, headers=headers)
  ```
</CodeGroup>

响应将包含请求信息和任务状态。

如果任务正在进行中，状态将设置为 `pending`：

<CodeGroup>
  ```json JSON theme={null}
  {
      "status": "pending",
      "id": "7447868801825135617",
      "created_at": "2026-04-09 04:51:37",
      "updated_at": "2026-04-09 04:51:37",
      "target": "google_ai_mode",
      "query": "best health trackers under $200",
      "page_from": 1,
      "limit": 10,
      "device_type": "desktop",
      "headless": "html",
      "parse": true,
      "domain": "com",
      "page_count": 1,
      "force_headers": false,
      "force_cookies": false,
      "headers_cookies_policy": false
  }
  ```
</CodeGroup>

当任务成功完成时，状态将更改为 `done`：

<CodeGroup>
  ```json JSON theme={null}
  {
      "status": "done",
      "id": "7447866391652228097",
      "created_at": "2026-04-09 04:42:02",
      "updated_at": "2026-04-09 04:42:16",
      "target": "google_ai_mode",
      "query": "best health trackers under $200",
      "page_from": 1,
      "limit": 10,
      "device_type": "desktop",
      "headless": "html",
      "parse": true,
      "domain": "com",
      "page_count": 1,
      "force_headers": false,
      "force_cookies": false,
      "headers_cookies_policy": false
  }
  ```
</CodeGroup>

如果任务失败，状态将设置为 `faulted`。

***

## 排队多个任务

##### **批量查询或 URL 端点：** `https://scraper-api.decodo.com/v3/task/batch`

向此端点发出 POST 请求，以 JSON 格式提供多个查询或 URL。

<Note>
  批量请求限制为每秒 1 个请求。
</Note>

<Warning>
  在单个批次中，您可以提交多个查询或 URL，但不能同时提交两者。此外，一个批次必须只有一个 `target`，如下面示例中显示的 `google_search`。

  每个批量请求最多可以提交 3000 个 URL/查询。
</Warning>

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v3/task/batch' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "url": [
          "https://ip.decodo.com",
          "https://ip.decodo.com",
          "https://ip.decodo.com"
      	],
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task/batch", {
      method: "POST",
      body: JSON.stringify({
        "url": ["https://ip.decodo.com", "https://ip.decodo.com", "https://ip.decodo.com"]
      }),
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests

  url = "https://scraper-api.decodo.com/v3/task"

  payload = {
      "urls": [
          "https://ip.decodo.com",
          "https://ip.decodo.com",
          "https://ip.decodo.com"
      ]
  }

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }

  response = requests.post(url, json=payload, headers=headers
  ```
</CodeGroup>

***

## 将任务状态接收到您的 callback\_url

#### 通过输入 `callback_url` 作为参数之一，这将适用于任何异步端点

任务完成后，我们将向您提供的 URL 发出 POST 请求，其中包含 `task_id` 和使用的参数。您可以使用[**像这样的网站**](https://webhook.site)来测试接收响应。

##### **使用单个任务端点的示例：**

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v3/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "url": "https://ip.decodo.com",
        "callback_url": "https://your.url"
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task", {
      method: "POST",
      headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
      body: JSON.stringify({
        url: "https://ip.decodo.com",
        callback_url: "https://your.url"
      })
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests

  url = "https://scraper-api.decodo.com/v3/task"

  payload = {
      "url": "https://ip.decodo.com",
      "callback_url": "https://your.url"
  }

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.text)
  ```
</CodeGroup>

##### **您将收到的响应示例：**

<CodeGroup>
  ```json JSON expandable theme={null}
  {
    "id": "7039164056019693569",
    "status": "done",
    "target": "universal",
    "query": "",
    "url": "https://ip.decodo.com",
    "domain": "com",
    "limit": 10,
    "locale": null,
    "geo": null,
    "device_type": "desktop",
    "page_from": 1,
    "parse": 0,
    "output_schema": null,
    "headless": null,
    "priority": 0,
    "persist": true,
    "content_encoding": "utf-8",
    "created_at": "2023-03-08 09:24:52",
    "updated_at": "2023-03-08 09:24:52"
  ```
</CodeGroup>

然后，您可以使用 `id` 通过此端点检索任务结果：

* `https://scraper-api.decodo.com/v3/task/{task_id}/results`

例如，要检索上述示例的结果，您需要向以下地址发送 `GET` 请求：

* `https://scraper-api.decodo.com/v3/task/7039164056019693569/results`

# 验证回调

要验证回调请求确实来自 Scraper API，请在 `passthrough` 参数中包含一个注释。参数 `passthrough` 及其内容将出现在发送回您端点的有效负载中。

<CodeGroup>
  ```shellscript cURL theme={null}
  # update 'TOKEN VALUE' with your authorization token
  curl --request 'POST' \
          --url 'https://scraper-api.decodo.com/v3/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Basic TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "target": "amazon_pricing",
        "query": "B0BS1QCFHX",
        "parse": true,
        "callback_url": "https://your.callback.url",
        "passtrough": "your_note"
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://scraper-api.decodo.com/v3/task", {
      method: "POST",
      headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Basic TOKEN VALUE" // 使用您的授权令牌更新
      },
      body: JSON.stringify({
        target: "amazon_pricing",
        query: "B0BS1QCFHX",
        parse: true,
        callback_url: "https://your.callback.url",
        passtrough: "your_note"
      })
    }).catch(error => console.log(error));

    console.log(await response.json())
  }

  scrape()
  ```

  ```python Python theme={null}
  import requests

  url = "https://scraper-api.decodo.com/v3/task"

  payload = {
      "target": "amazon_pricing",
      "query": "B0BS1QCFHX",
      "parse": True,
      "callback_url": "https://your.callback.url",
      "passtrough": "your_note"
  }

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Basic TOKEN VALUE" # 使用您的授权令牌更新
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.text)
  ```
</CodeGroup>

***

<Columns cols={2}>
  <Card title="支持" href="https://direct.lc.chat/12092754" cta="让我们聊聊！">
    需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
    您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。
  </Card>

  <Card title="反馈" href="mailto:feedback@decodo.com" cta="分享反馈">
    找不到您要找的内容？请求一篇文章！ \
    有反馈意见？分享您对我们如何改进的想法。
  </Card>
</Columns>