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

# Tasks

> Read the persisted status of a server-managed asynchronous captcha task. The server starts monitoring after HTTP 201 and continues even if the client disconnects or never polls; this endpoint never drives task processing; reading a ready result preserves the existing one-time settlement behavior. It returns processing until the server persists ready, or HTTP 504 timeout after the 120-second deadline.



## OpenAPI

````yaml /openapi/hcaptcha.json post /captcha/tasks
openapi: 3.0.0
info:
  title: hCaptcha verification code recognition service
  version: 1.0.0
  description: >-
    API reference for hCaptcha verification code recognition service on Ace Data
    Cloud.
servers:
  - url: https://api.acedata.cloud
    description: Ace Data Cloud API
security:
  - bearerAuth: []
paths:
  /captcha/tasks:
    post:
      summary: Tasks
      description: >-
        Read the persisted status of a server-managed asynchronous captcha task.
        The server starts monitoring after HTTP 201 and continues even if the
        client disconnects or never polls; this endpoint never drives task
        processing; reading a ready result preserves the existing one-time
        settlement behavior. It returns processing until the server persists
        ready, or HTTP 504 timeout after the 120-second deadline.
      operationId: queryCaptchaTask
      parameters:
        - in: header
          name: accept
          schema:
            enum:
              - application/json
            type: string
          required: false
          description: Specifies the format of the response from the server.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - task_id
              properties:
                task_id:
                  type: string
                  example: 61138bb6-19aa-11ec-a9c8-0242ac110002
                  description: >-
                    The task id returned when a token API was called with
                    async=true.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  task_id: 61138bb6-19aa-11ec-a9c8-0242ac110002
                  status: ready
                  token: P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni......
                properties:
                  success:
                    type: boolean
                    description: Whether the query succeeded.
                  task_id:
                    type: string
                    description: The task id being polled.
                  started_at:
                    type: number
                    description: >-
                      When the task began processing, as a Unix timestamp in
                      seconds (float).
                  finished_at:
                    type: number
                    description: >-
                      When the task produced its result, as a Unix timestamp in
                      seconds (float). Absent while the task is still
                      processing.
                  elapsed:
                    type: number
                    description: >-
                      Processing time in seconds (float, 3 decimals). Absent
                      while the task is still processing.
                  trace_id:
                    type: string
                    description: 本次请求的追踪 ID，排查问题时提供给技术支持。
                  type:
                    type: string
                    description: 任务类型。
                  user_id:
                    type: string
                    description: 发起该任务的账号 ID。
                  actor_user_id:
                    type: string
                    description: 实际执行者的账号 ID。通过授权代发时与 `user_id` 不同。
                  api_id:
                    type: string
                    description: 该任务所属接口的 ID。
                  application_id:
                    type: string
                    description: 该任务计费所用应用的 ID。
                  credential_id:
                    type: string
                    description: 发起该任务所用凭证的 ID。
                  authorization_id:
                    type: string
                    description: 该任务使用的授权 ID。未通过授权发起时为 null。
                  status:
                    type: string
                    enum:
                      - processing
                      - ready
                    description: >-
                      Persisted task state. 'processing' means the server is
                      still working; 'ready' means the result is stored. Reading
                      processing state has no lifecycle or billing side effects.
                  token:
                    type: string
                    description: >-
                      The solved verification token (token APIs). Present only
                      when status is 'ready'.
                  solution:
                    type: object
                    description: >-
                      The recognition result for recognition/recaptcha2 and
                      recognition/hcaptcha. Present only when status is 'ready'.
                    additionalProperties: true
                  text:
                    type: string
                    description: >-
                      The recognized text for recognition/image2text. Present
                      only when status is 'ready'.
                required:
                  - success
                  - task_id
                  - status
          description: OK, the request is successful.
        '400':
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_query
                    message: no task_id specified
                  trace_id: 2efa9340-b21b-4e26-9e14-4aac95f343ab
                additionalProperties: true
          description: Bad request, possibly due to a missing task_id.
        '401':
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: invalid_token
                    message: The specified token is invalid or wrong.
                  trace_id: 2efa9340-b21b-4e26-9e14-4aac95f343ab
                additionalProperties: true
          description: Unauthorized, invalid or missing authorization token.
        '404':
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: task not found
                  trace_id: 2efa9340-b21b-4e26-9e14-4aac95f343ab
                additionalProperties: true
          description: The specified task_id does not exist.
        '504':
          content:
            application/json:
              schema:
                type: object
                example:
                  detail: The captcha task timed out.
                  code: timeout
                  success: false
                  task_id: 61138bb6-19aa-11ec-a9c8-0242ac110002
                  status: failed
                  started_at: 1784885653
                  finished_at: 1784885765.4
                  elapsed: 112.4
                properties:
                  detail:
                    type: string
                    description: A stable description of the terminal task failure.
                  code:
                    type: string
                    enum:
                      - timeout
                    description: The terminal task timeout code.
                  success:
                    type: boolean
                    enum:
                      - false
                  task_id:
                    type: string
                    description: The task id that reached a terminal failure.
                  status:
                    type: string
                    enum:
                      - failed
                  started_at:
                    type: number
                    description: >-
                      When the task began processing, as a Unix timestamp in
                      seconds.
                  finished_at:
                    type: number
                    description: >-
                      When the task reached its terminal failure, as a Unix
                      timestamp in seconds.
                  elapsed:
                    type: number
                    description: Processing time before the terminal failure, in seconds.
                required:
                  - detail
                  - code
                  - success
                  - task_id
                  - status
          description: >-
            The server-managed task reached its 120-second deadline without a
            result. Repeated reads return the same timeout, and the task is not
            charged.
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token from https://platform.acedata.cloud

````