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

# Get task status

> Fetch the status and result of an asynchronous task.

## Overview

You can poll this endpoint to check the status of an asynchronous task. The `status` field can have one of the following values:

* `QUEUED`: The task has been received and is waiting to be processed.
* `PROCESSING`: The task is actively being processed.
* `COMPLETED`: The task has finished successfully. The `response` object will contain the full result.
* `FAILED`: The task failed to complete. The `response` object may contain error details.

When a task is in a `QUEUED` or `PROCESSING` state, the response will only contain the current status. Once the task is `COMPLETED` or `FAILED`, the response will include a `response` object containing the full result.

## Task retention policy

COMPLETED and FAILED tasks are stored in our system for **24 hours** after completion. During this time, you can retrieve the full results using the task ID. After 24 hours, the task record and its associated response data are permanently deleted from our system.

HTML URLs included in responses expire after **24 hours** from generation, regardless of the task's retention status.

## Example usage

### Check a pending task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cloro.dev/v1/async/task/b27a21e1-7c39-4aa2-a347-23e828c426f9" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response (QUEUED) theme={null}
  {
    "task": {
      "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
      "taskType": "CHATGPT",
      "status": "QUEUED",
      "priority": 1,
      "createdAt": "2025-11-10T15:00:00.000Z",
      "idempotencyKey": "your-unique-key"
    },
    "credits": {
      "creditsToCharge": 10,
      "creditsCharged": 0
    }
  }
  ```
</CodeGroup>

### Fetch a completed task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cloro.dev/v1/async/task/b27a21e1-7c39-4aa2-a347-23e828c426f9" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response (COMPLETED) theme={null}
  {
    "task": {
      "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
      "taskType": "CHATGPT",
      "status": "COMPLETED",
      "priority": 1,
      "createdAt": "2025-11-10T15:00:00.000Z",
      "idempotencyKey": "your-unique-key"
    },
    "credits": {
      "creditsToCharge": 10,
      "creditsCharged": 10
    },
    "response": {
      "model": "gpt-5-3-mini",
      "html": "...",
      "text": "...",
      "sources": [],
      "shoppingCards": [],
      "entities": [],
      "markdown": "...",
      "searchQueries": []
    }
  }
  ```
</CodeGroup>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/async/task/{taskId}
openapi: 3.1.0
info:
  title: cloro
  description: API for monitoring AI responses across different providers and regions
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.cloro.dev
    description: Production server
security:
  - bearerAuth: []
paths:
  /v1/async/task/{taskId}:
    get:
      summary: Get async task status
      description: Fetch the status and result of an asynchronous task.
      operationId: getTaskStatus
      parameters:
        - name: taskId
          in: path
          required: true
          description: The ID of the task to fetch.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response with the task status and result if completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponse'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found - Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    TaskStatusResponse:
      type: object
      required:
        - task
        - credits
      properties:
        task:
          $ref: '#/components/schemas/AsyncTaskSummary'
        credits:
          $ref: '#/components/schemas/AsyncTaskCredits'
        response:
          type: object
          description: >-
            The full response object, present only when the task is COMPLETED or
            FAILED.
    AuthenticationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_API_KEY
                - INVALID_API_KEY_FORMAT
                - INVALID_OR_EXPIRED_API_KEY
              example: MISSING_API_KEY
            message:
              type: string
              example: Missing or invalid API key
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    NotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: Route not found
            details:
              type: object
              properties:
                id:
                  type: string
                  example: /v1/invalid-endpoint
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    InternalError:
      type: object
      oneOf:
        - properties:
            success:
              type: boolean
              example: false
            error:
              type: string
              example: Maximum retries exceeded
        - properties:
            error:
              type: object
              properties:
                code:
                  type: string
                  example: INTERNAL_SERVER_ERROR
                message:
                  type: string
                  example: Internal server error
                timestamp:
                  type: string
                  format: date-time
                  example: '2025-01-15T12:00:00.000Z'
    AsyncTaskSummary:
      type: object
      required:
        - id
        - taskType
        - status
        - priority
        - createdAt
      description: Common task summary fields shared across async task responses.
      properties:
        id:
          type: string
          format: uuid
          description: Unique task identifier.
          example: b27a21e1-7c39-4aa2-a347-23e828c426f9
        taskType:
          type: string
          enum:
            - AIMODE
            - GOOGLE
            - GOOGLE_NEWS
            - GEMINI
            - CHATGPT
            - COPILOT
            - PERPLEXITY
            - GROK
          description: The AI provider for this task.
          example: CHATGPT
        status:
          type: string
          enum:
            - QUEUED
            - PROCESSING
            - COMPLETED
            - FAILED
          description: Current task status.
          example: QUEUED
        priority:
          type: integer
          description: >-
            Task priority level (1-10). Higher numbers are processed first.
            Defaults to 1.
          minimum: 1
          maximum: 10
          example: 1
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the task was created.
          example: '2026-04-09T15:00:00.000Z'
        idempotencyKey:
          type:
            - string
            - 'null'
          description: The idempotency key if one was provided.
          example: batch-chatgpt-001
    AsyncTaskCredits:
      type: object
      required:
        - creditsToCharge
        - creditsCharged
      description: Credit information for an async task.
      properties:
        creditsToCharge:
          type: number
          description: Credits reserved for this task.
          example: 10
        creditsCharged:
          type:
            - number
            - 'null'
          description: Credits actually charged. Null until the task completes.
          example: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````