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

# Get Task Status and Results

> Check task status and read results after completion.

# Get Task Status and Results

Query a task by `task_id`. When the task status is `succeeded`, the response automatically includes the first page of normalized results. Use `cursor` and `limit` on the same endpoint to read additional result pages.

## Endpoint

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

Use the `next_cursor` returned under `results` to read the next page:

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

## Response

```json theme={null}
{
  "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": {}
        }
      ]
    }
  }
}
```

## Response Fields

| Field            | Type    | Description                                                                      |
| ---------------- | ------- | -------------------------------------------------------------------------------- |
| `task_id`        | string  | Task identifier                                                                  |
| `status`         | string  | `queued`, `running`, `succeeded`, or `failed`                                    |
| `result_count`   | integer | Number of collected records                                                      |
| `error_message`  | string  | Failure reason when status is `failed`                                           |
| `credits_amount` | number  | Credits charged for the task                                                     |
| `created_time`   | string  | Task creation time                                                               |
| `finished_time`  | string  | Task completion time                                                             |
| `results`        | object  | Present only when `status` is `succeeded`; contains paginated normalized records |

## Pagination

| Query    | Type    | Default | Description                                                                 |
| -------- | ------- | ------- | --------------------------------------------------------------------------- |
| `limit`  | integer | `50`    | Number of records to return, max `500`                                      |
| `cursor` | string  | `null`  | Cursor from the previous `results.next_cursor`. Omit it for the first page. |

<Tip>
  While a task is `queued`, `running`, or `failed`, this endpoint returns task metadata without `results`.
</Tip>


## OpenAPI

````yaml api-manual/agent-api/agent-api.json GET /v1/tasks/{task_id}
openapi: 3.0.0
info:
  title: Agent API
  description: Asynchronous social data collection API
  version: 1.0.0
servers:
  - url: https://api.socq.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /v1/tasks/{task_id}:
    get:
      tags:
        - Agent API
      summary: Get task status and results
      description: >-
        Check task status. When the task has succeeded, the response includes
        cursor-paginated normalized records under data.results.
      operationId: getAgentTask
      parameters:
        - $ref: '#/components/parameters/TaskId'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Task status and optional results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    TaskId:
      name: task_id
      in: path
      required: true
      schema:
        type: string
        example: A1B2C3D4E5F6G7H8
      description: Task ID returned by the submit endpoint
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        nullable: true
      description: >-
        Cursor returned by the previous data.results.next_cursor. Omit for the
        first page.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
      description: Maximum number of result records to return.
  schemas:
    TaskResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/Task'
    Task:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
        result_count:
          type: integer
        error_message:
          type: string
          nullable: true
        credits_amount:
          type: number
        created_time:
          type: string
          format: date-time
        finished_time:
          type: string
          format: date-time
          nullable: true
        results:
          $ref: '#/components/schemas/ResultList'
          description: >-
            Cursor-paginated normalized records. Present only when status is
            succeeded.
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
    ResultList:
      type: object
      properties:
        limit:
          type: integer
          example: 50
        next_cursor:
          type: string
          nullable: true
          example: NTY3ODkw
        has_more:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/ResultItem'
      required:
        - limit
        - has_more
        - items
    ResultItem:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          nullable: true
        platform:
          type: string
        resource:
          type: string
          description: >-
            Product resource, such as posts, reels, search, followers-count, or
            pages.
        type:
          type: string
        url:
          type: string
          nullable: true
        metrics:
          type: object
          description: >-
            Normalized metric names, such as likes_count, comments_count,
            followers_count, or views_count.
          additionalProperties: true
        media:
          type: array
          items:
            type: object
            additionalProperties: true
        created_at:
          type: string
          format: date-time
          nullable: true
        collected_at:
          type: string
          format: date-time
        extra:
          type: object
          description: >-
            Low-frequency or source-specific values that are not part of the
            stable core fields.
          additionalProperties: true
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````