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

# 获取任务状态和结果

> 完成后检查任务状态并读取结果。

# 获取任务状态和结果

通过`task_id`查询任务。当任务状态为 `succeeded` 时，响应自动包含标准化结果的第一页。在同一端点上使用 `cursor` 和 `limit` 来读取其他结果页。

## 端点

```http theme={"system"}
GET https://api.socq.ai/v1/tasks/{task_id}
```

使用`results`下返回的`next_cursor`来读取下一页：

```http theme={"system"}
GET https://api.socq.ai/v1/tasks/{task_id}?limit=50&cursor=NTY3ODkw
```

## 响应

```json theme={"system"}
{
  "code": 200,
  "data": {
    "task_id": "A1B2C3D4E5F6G7H8",
    "status": "succeeded",
    "result_count": 1,
    "error_message": null,
    "credits_amount": 0,
    "created_time": "2026-07-07T18:30:32",
    "finished_time": "2026-07-07T18:30:48",
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "items": [
        {
          "id": "25025320",
          "platform": "instagram",
          "resource": "followers-count",
          "type": "profile_metrics",
          "username": "instagram",
          "name": "Instagram",
          "url": "https://www.instagram.com/instagram",
          "metrics": {
            "followers_count": 685829413,
            "following_count": 251,
            "posts_count": 8000
          },
          "collected_at": "2026-07-07T18:30:48",
          "extra": {}
        }
      ]
    }
  }
}
```

## 响应字段

| 领域               | 类型  | 描述                                        |
| ---------------- | --- | ----------------------------------------- |
| `task_id`        | 字符串 | 任务标识符                                     |
| `status`         | 字符串 | `queued`、`running`、`succeeded` 或 `failed` |
| `result_count`   | 整数  | 采集的记录数量                                   |
| `error_message`  | 字符串 | 状态为`failed`时失败原因                          |
| `credits_amount` | 数量  | 任务所需的积分                                   |
| `created_time`   | 字符串 | 任务创建时间                                    |
| `finished_time`  | 字符串 | 任务完成时间                                    |
| `results`        | 对象  | 仅当`status`为`succeeded`时存在；包含分页规范化记录       |

## 分页

| 查询       | 类型  | 默认     | 描述                                           |
| -------- | --- | ------ | -------------------------------------------- |
| `limit`  | 整数  | `50`   | 返回的记录数，最大值 `500`                             |
| `cursor` | 字符串 | `null` | Cursor 源自之前的 `results.next_cursor`。在第一页中省略它。 |

<Tip>
  当任务是 `queued`、`running` 或 `failed` 时，此端点返回不带 `results` 的任务元数据。
</Tip>


## OpenAPI

````yaml api-manual/agent-api/agent-api.json GET /v1/tasks/{task_id}
openapi: 3.1.0
info:
  title: SocQ Agent API
  version: v1-57489840196e
  description: Asynchronous social data API generated from the SocQ Capability Registry.
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/tasks/{task_id}:
    get:
      summary: Get task status and paginated results
      operationId: getAgentTask
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Task detail
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````