> ## 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.

# 异步请求

> 使用 Decodo 网页数据 API 提交和获取异步抓取任务，涵盖任务排队、批量提交和结果轮询。

将多个请求加入队列并立即获得 `task_id`。任务完成后，您可以使用该 `task_id` 获取请求结果。

## 排队单个任务

##### 单个查询或 URL 端点：` https://data.decodo.com/v1/task`

使用您需要的参数向此端点发送 `POST` 请求，即可获得用于在任务完成后获取结果的 `task_id`，以及本次请求所用的参数。

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'POST' \
          --url 'https://data.decodo.com/v1/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer 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://data.decodo.com/v1/task", {
      method: "POST",
      body: JSON.stringify({
        "url": "https://ip.decodo.com"
      }),
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
    }).catch(error => console.log(error));

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

  scrape()
  ```

  ```python Python theme={null}
  import requests
    
  url = "https://data.decodo.com/v1/task"
    
  payload = {
        "url": "https://ip.decodo.com"
  }
    
  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }
    
  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://data.decodo.com/v1/task/{task_id}/results`

向此端点发送 GET 请求，并将 `{task_id}` 替换为上一个 POST 请求返回的 ID，即可获取结果。

<Note>
  在初始请求后的 24 小时内，结果可无限次获取。
</Note>

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'GET' \
          --url 'https://data.decodo.com/v1/task/{task_id}/results' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer TOKEN VALUE'
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://data.decodo.com/v1/task/{task_id}/results", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
    }).catch(error => console.log(error));

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

  scrape()
  ```

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

  task_id = "TASK_ID"

  url = f"https://data.decodo.com/v1/task/{task_id}/results"

  headers = {
      "accept": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

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

***

## 使用 task\_id 查询任务状态

您可以手动查询异步任务的状态：

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'GET' \
          --url 'https://data.decodo.com/v1/task/{task_id}' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer TOKEN VALUE'
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://data.decodo.com/v1/task/{task_id}", {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
    }).catch(error => console.log(error));

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

  scrape()
  ```

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

  task_id = "TASK_ID"

  url = f"https://data.decodo.com/v1/task/{task_id}"

  headers = {
      "accept": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

  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://data.decodo.com/v1/task/batch`

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

<Note>
  批量请求的频率限制为每秒 1 次。
</Note>

<Warning>
  单个批量请求中只能提交多个查询或多个 URL，不能同时提交两者。此外，一个批量请求只能包含一个 `target`，例如下方第二个示例中的 `google_search`。

  可提交的 URL/查询数量取决于您订阅套餐的速率限制。
</Warning>

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'POST' \
          --url 'https://data.decodo.com/v1/task/batch' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer 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://data.decodo.com/v1/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": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
    }).catch(error => console.log(error));

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

  scrape()
  ```

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

  url = "https://data.decodo.com/v1/task/batch"

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

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

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

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

如需批量提交搜索查询，请将它们放在 `query` 中，并指定一个 `target`：

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'POST' \
          --url 'https://data.decodo.com/v1/task/batch' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "target": "google_search",
        "query": [
          "pizza",
          "coffee"
        ],
        "parse": true
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://data.decodo.com/v1/task/batch", {
      method: "POST",
      body: JSON.stringify({
        "target": "google_search",
        "query": ["pizza", "coffee"],
        "parse": true
      }),
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
    }).catch(error => console.log(error));

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

  scrape()
  ```

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

  url = "https://data.decodo.com/v1/task/batch"

  payload = {
      "target": "google_search",
      "query": ["pizza", "coffee"],
      "parse": True
  }

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

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

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

***

## 通过 callback\_url 接收任务状态

#### 在任意异步端点中添加 `callback_url` 参数即可使用此功能

任务完成后，我们会向您的 URL 发送一个 `POST` 请求，其中包含 `task_id`、`status_code` 和时间戳。回调中不包含结果本身，请使用 `task_id` 获取结果。您可以使用[**此类网站**](https://webhook.site)测试接收响应。

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

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'POST' \
          --url 'https://data.decodo.com/v1/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer 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://data.decodo.com/v1/task", {
      method: "POST",
      headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
      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://data.decodo.com/v1/task"

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

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

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

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

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

<CodeGroup>
  ```json JSON theme={null}
  {
    "task_id": "7515697022976960513",
    "status_code": 200,
    "created_at": "2026-10-13 08:56:45",
    "updated_at": "2026-10-13 08:56:45"
  }
  ```
</CodeGroup>

之后，您可以通过以下端点，使用 `task_id` 获取任务结果：

* `https://data.decodo.com/v1/task/{task_id}/results`

例如，要获取上述示例的结果，请向以下地址发送 `GET` 请求：

* `https://data.decodo.com/v1/task/7515697022976960513/results`

# 验证回调

如需验证回调请求确实来自网页数据 API，请在 `passthrough` 参数中添加备注。`passthrough` 参数及其内容会包含在发送回您端点的数据中。

<CodeGroup>
  ```shellscript cURL theme={null}
  # 将 'TOKEN VALUE' 替换为您的 API 密钥
  curl --request 'POST' \
          --url 'https://data.decodo.com/v1/task' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer TOKEN VALUE' \
          --header 'Content-Type: application/json' \
          --data '
      {
        "target": "amazon_pricing",
        "query": "B0BS1QCFHX",
        "parse": true,
        "callback_url": "https://your.callback.url",
        "passthrough": "your_note"
      }
  '
  ```

  ```javascript Node theme={null}
  const scrape = async() => {
    const response = await fetch("https://data.decodo.com/v1/task", {
      method: "POST",
      headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer TOKEN VALUE" // 替换为您的 API 密钥
      },
      body: JSON.stringify({
        target: "amazon_pricing",
        query: "B0BS1QCFHX",
        parse: true,
        callback_url: "https://your.callback.url",
        passthrough: "your_note"
      })
    }).catch(error => console.log(error));

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

  scrape()
  ```

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

  url = "https://data.decodo.com/v1/task"

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

  headers = {
      "accept": "application/json",
      "content-type": "application/json",
      "authorization": "Bearer TOKEN VALUE" # 替换为您的 API 密钥
  }

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

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

回调中随后会包含您的备注：

<CodeGroup>
  ```json JSON theme={null}
  {
    "task_id": "7515716817046773761",
    "status_code": 200,
    "created_at": "2026-10-13 10:15:24",
    "updated_at": "2026-10-13 10:15:24",
    "passthrough": "your_note"
  }
  ```
</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>


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