> ## 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,
      "schema_id": "account",
      "schema_version": "1.0",
      "items": [
        {
          "id": "25025320",
          "platform": "instagram",
          "resource": "followers-count",
          "type": "profile_metrics",
          "url": "https://www.instagram.com/instagram",
          "published_at": null,
          "collected_at": "2026-07-07T18:30:48Z",
          "username": "instagram",
          "name": "Instagram",
          "text": null,
          "avatar_url": null,
          "cover_url": null,
          "website": null,
          "is_verified": true,
          "is_private": false,
          "location": null,
          "metrics": {
            "followers_count": 685829413,
            "following_count": 251,
            "posts_count": 8000
          }
        }
      ]
    }
  }
}
```

## 响应字段

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

\| `results.schema_id` | 字符串 | 资源 Schema ID |
\| `results.schema_version` | 字符串 | 资源 Schema 版本 |

## 分页

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

\| `fields` | 字符串 | `null` | 最多 50 个逗号分隔字段或点路径。 |

除非被 `fields` 投影省略，否则所有声明字段都会保留。不可获得的标量和对象返回 `null`；确定为零、假值和空集合时分别保留 `0`、`false` 和 `[]`。

> [!TIP]
>
> 当任务是 `queued`、`running` 或 `failed` 时，此端点返回不带 `results` 的任务元数据。


## OpenAPI

````yaml zh/api-manual/agent-api/agent-api.json GET /v1/tasks/{task_id}
openapi: 3.1.0
info:
  title: SocQ Agent API 中文版
  version: v1-050b21a3b206
  description: 根据 SocQ 能力目录生成的异步社交数据 API。
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/tasks/{task_id}:
    get:
      summary: 获取任务状态和分页结果
      operationId: getAgentTask
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 任务 ID。
        - name: cursor
          in: query
          schema:
            type: string
          description: 分页游标。
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: 本次返回的最大记录数。
        - name: fields
          in: query
          schema:
            type: string
          description: 最多 50 个逗号分隔字段或点路径。
      responses:
        '200':
          description: 任务详情
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '使用 `Authorization: Bearer <token>` 请求头进行身份验证。'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 也可以通过 `x-api-key` 请求头提供 API Key。

````

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