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

# 异步任务查询

> 根据任务 ID 轮询异步任务的执行状态与最终业务结果。

通过统一任务入口提交 `ASYNC` 模式的业务接口（如 GEO 排名查询、GEO 排名监测、品牌得分检测、推广链接检测等）后，服务端会先返回唯一的 `taskId`。调用方通过本接口轮询查询任务的实时处理进度并在成功后获取业务结果。

<Info>
  **推荐轮询间隔：** 建议每隔 **10 秒** 查询一次本接口。任务未完成前不建议高频请求。
</Info>

## 接口速查

| 项目     | 当前接口约定                                            |
| ------ | ------------------------------------------------- |
| 请求方式   | `GET`                                             |
| 请求地址   | `https://api.aibase.cn/v1/openapi/tasks/{taskId}` |
| 身份认证   | Header `AIBase-API-Key`                           |
| 执行模式   | 通用任务查询端点                                          |
| 推荐轮询间隔 | 10 秒                                              |

## 请求头

<ParamField header="AIBase-API-Key" type="string" required>
  AIBase 开放平台 API Key，例如 `AIBase_xxx`。请仅在服务端保存和使用。
</ParamField>

<ParamField header="AIBase-Request-Id" type="string">
  可选的客户端请求追踪标识。
</ParamField>

## 路径参数

<ParamField path="taskId" type="string" required>
  提交异步任务时由平台返回的唯一任务标识，例如 `task_d77143abc87642d4842ff588197faa89`。
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.aibase.cn/v1/openapi/tasks/task_d77143abc87642d4842ff588197faa89 \
    --header "AIBase-API-Key: ${AIBASE_API_KEY}"
  ```

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

  api_key = os.environ["AIBASE_API_KEY"]
  task_id = "task_d77143abc87642d4842ff588197faa89"

  response = requests.get(
      f"https://api.aibase.cn/v1/openapi/tasks/{task_id}",
      headers={"AIBase-API-Key": api_key},
      timeout=30,
  )
  payload = response.json()
  print("当前任务状态:", payload["data"]["status"])
  if payload["data"]["status"] == 2:
      print("业务结果:", payload["data"]["result"])
  ```

  ```javascript Node.js theme={null}
  const apiKey = process.env.AIBASE_API_KEY;
  const taskId = "task_d77143abc87642d4842ff588197faa89";

  const response = await fetch(`https://api.aibase.cn/v1/openapi/tasks/${taskId}`, {
    headers: {
      "AIBase-API-Key": apiKey,
    },
  });
  const payload = await response.json();
  console.log("任务状态:", payload.data?.status);
  if (payload.data?.status === 2) {
    console.log("业务结果:", payload.data.result);
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.aibase.cn/v1/openapi/tasks/task_d77143abc87642d4842ff588197faa89"))
      .header("AIBase-API-Key", System.getenv("AIBASE_API_KEY"))
      .GET()
      .build();

  HttpResponse<String> response = HttpClient.newHttpClient()
      .send(request, HttpResponse.BodyHandlers.ofString());
  ```
</RequestExample>

## 响应参数

<ResponseField name="code" type="integer" required>
  业务状态码。`200` 表示查询接口请求成功。
</ResponseField>

<ResponseField name="msg" type="string" required>
  响应说明。
</ResponseField>

<ResponseField name="data" type="object" required>
  任务详情数据。
</ResponseField>

<ResponseField name="data.taskId" type="string" required>
  任务唯一标识。
</ResponseField>

<ResponseField name="data.status" type="integer" required>
  任务处理状态枚举值（详见下方状态表）。
</ResponseField>

<ResponseField name="data.statusDesc" type="string" required>
  任务状态文字说明，如 `成功`、`待执行`、`失败` 等。
</ResponseField>

<ResponseField name="data.result" type="object">
  业务返回结果。仅在 `status = 2`（SUCCESS）时返回完整的具体业务数据，字段结构由对应的 `apiCode` 决定。
</ResponseField>

<ResponseField name="timeStamp" type="integer" required>
  服务端响应时间戳，单位毫秒。
</ResponseField>

### status 状态码字典

| status | 状态标识          | 说明          | 建议处理逻辑                        |
| :----- | :------------ | :---------- | :---------------------------- |
| `1`    | **PENDING**   | 任务待执行或正在处理中 | 等待 10 秒后发起下一次查询               |
| `2`    | **SUCCESS**   | 任务已成功完成     | 终止轮询，从 `data.result` 读取具体业务数据 |
| `3`    | **FAILED**    | 任务处理失败      | 终止轮询，记录失败原因或触发重试流程            |
| `4`    | **TIMEOUT**   | 任务执行超时      | 终止轮询，记录超时                     |
| `5`    | **CANCELLED** | 任务已被取消      | 终止轮询                          |

<ResponseExample>
  ```json 200 (SUCCESS - 任务完成) theme={null}
  {
    "code": 200,
    "msg": "成功",
    "data": {
      "taskId": "task_d77143abc87642d4842ff588197faa89",
      "status": 2,
      "statusDesc": "成功",
      "result": {}
    },
    "timeStamp": 1789551724519
  }
  ```

  ```json 200 (PENDING - 执行中) theme={null}
  {
    "code": 200,
    "msg": "成功",
    "data": {
      "taskId": "task_d77143abc87642d4842ff588197faa89",
      "status": 1,
      "statusDesc": "待执行",
      "result": null
    },
    "timeStamp": 1789551710000
  }
  ```

  ```json 404 (任务不存在) theme={null}
  {
    "code": 404,
    "msg": "任务不存在或已过期",
    "data": null,
    "timeStamp": 1789551724519
  }
  ```
</ResponseExample>

## 接入注意事项

1. **不可仅依据固定轮询次数判断**：大模型生成与多平台检测耗时受网络和模型并发负载影响，请务必根据返回的 `status` 状态枚举决定是否结束轮询。
2. **遵守 10 秒轮询间隔**：高频轮询会白白消耗客户端计算与网络资源，并可能触发平台的并发限流规则。
3. **结合超时熔断控制**：在业务侧编写循环等待逻辑时，建议加入最大等待时间（例如 5 分钟），超过时间仍为 `status = 1` 则主动熔断报警。