> ## 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 async status

> Get organization-wide async queue metrics including queued and processing task counts, and concurrency usage.

## Overview

This endpoint provides real-time visibility into your organization's async task queue and processing capacity. Use it to:

* **Monitor queue health**: Track how many tasks are waiting to be processed
* **Understand processing capacity**: See current concurrency usage versus your plan limit
* **Debug delays**: Identify if tasks are queued due to high volume or concurrency limits
* **Plan capacity**: Decide whether to upgrade your plan based on actual usage

The response includes four key metrics:

* **queuedTasks**: Number of tasks currently waiting in the queue (status: `QUEUED`)
* **processingTasks**: Number of tasks actively being processed (status: `PROCESSING`)
* **priorityBreakdown**: Queued task counts per priority level, so you can see how your queue is distributed across priorities
* **concurrency**: Current concurrency slot usage compared to your plan's maximum

## Response fields

| Field                          | Type    | Description                                                                                                    |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------- |
| `queuedTasks`                  | integer | Number of tasks currently queued for your organization                                                         |
| `processingTasks`              | integer | Number of tasks currently being processed for your organization                                                |
| `priorityBreakdown`            | array   | Queued task counts per priority level, ordered by priority descending. Only includes levels with queued tasks. |
| `priorityBreakdown[].priority` | integer | The priority level (1-10)                                                                                      |
| `priorityBreakdown[].count`    | integer | Number of queued tasks at this priority level                                                                  |
| `concurrency.used`             | integer | Number of concurrent slots currently in use                                                                    |
| `concurrency.max`              | integer | Maximum allowed concurrent tasks for your organization (based on your plan)                                    |

<Info>
  The `concurrency` object may be `null` if concurrency information cannot be retrieved at the time of the request. This is rare but can occur during system maintenance.
</Info>

## Example usage

### Check current queue status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cloro.dev/v1/async/status" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  {
    "queuedTasks": 3,
    "processingTasks": 2,
    "priorityBreakdown": [
      { "priority": 10, "count": 1 },
      { "priority": 5, "count": 1 },
      { "priority": 1, "count": 1 }
    ],
    "concurrency": {
      "used": 2,
      "max": 5
    }
  }
  ```
</CodeGroup>

### Monitor queue status programmatically

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from 'axios';

  const API_KEY = process.env.API_KEY;
  const STATUS_URL = 'https://api.cloro.dev/v1/async/status';

  async function checkQueueStatus() {
    try {
      const response = await axios.get(STATUS_URL, {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      });

      const { queuedTasks, processingTasks, priorityBreakdown, concurrency } = response.data;

      console.log(`Queue status:`);
      console.log(`  Queued: ${queuedTasks} tasks`);
      console.log(`  Processing: ${processingTasks} tasks`);

      if (priorityBreakdown.length > 0) {
        console.log(`  Priority breakdown:`);
        for (const { priority, count } of priorityBreakdown) {
          console.log(`    Priority ${priority}: ${count} tasks`);
        }
      }

      if (concurrency) {
        console.log(`  Concurrency: ${concurrency.used}/${concurrency.max} slots used`);
        console.log(`  Available: ${concurrency.max - concurrency.used} slots`);
      }

      // Alert if queue is getting large
      if (queuedTasks > 100) {
        console.warn('Warning: Queue has over 100 tasks waiting');
      }

      // Alert if approaching concurrency limit
      if (concurrency && concurrency.used / concurrency.max > 0.8) {
        console.warn('Warning: Using over 80% of concurrency limit');
      }

      return response.data;
    } catch (error) {
      console.error('Error checking queue status:', error.message);
      throw error;
    }
  }

  // Check status every 30 seconds
  setInterval(checkQueueStatus, 30000);
  ```

  ```python Python theme={null}
  import requests
  import time

  API_KEY = 'YOUR_API_KEY'
  STATUS_URL = 'https://api.cloro.dev/v1/async/status'

  def check_queue_status():
      try:
          response = requests.get(
              STATUS_URL,
              headers={'Authorization': f'Bearer {API_KEY}'}
          )
          response.raise_for_status()

          data = response.json()
          queued_tasks = data['queuedTasks']
          processing_tasks = data['processingTasks']
          priority_breakdown = data.get('priorityBreakdown', [])
          concurrency = data.get('concurrency')

          print(f'Queue status:')
          print(f'  Queued: {queued_tasks} tasks')
          print(f'  Processing: {processing_tasks} tasks')

          if priority_breakdown:
              print(f'  Priority breakdown:')
              for entry in priority_breakdown:
                  print(f'    Priority {entry["priority"]}: {entry["count"]} tasks')

          if concurrency:
              used = concurrency['used']
              max_concurrent = concurrency['max']
              available = max_concurrent - used
              print(f'  Concurrency: {used}/{max_concurrent} slots used')
              print(f'  Available: {available} slots')

              # Alert if approaching concurrency limit
              if used / max_concurrent > 0.8:
                  print('Warning: Using over 80% of concurrency limit')

          # Alert if queue is getting large
          if queued_tasks > 100:
              print('Warning: Queue has over 100 tasks waiting')

          return data

      except requests.exceptions.RequestException as e:
          print(f'Error checking queue status: {e}')
          raise

  # Check status every 30 seconds
  while True:
      check_queue_status()
      time.sleep(30)
  ```
</CodeGroup>

## Use cases

### Capacity planning

Monitor concurrency usage patterns to determine if you need to upgrade your plan:

```javascript theme={null}
const stats = await checkQueueStatus();

// If consistently at or near max concurrency, consider upgrading
if (stats.concurrency.used >= stats.concurrency.max * 0.9) {
  console.log('Consider upgrading to a higher plan for better throughput');
}
```

### Queue health monitoring

Track queue size to detect processing bottlenecks or high-volume periods:

```python theme={null}
data = check_queue_status()

# Alert if queue is backing up
if data['queuedTasks'] > 1000:
    send_alert('High queue volume - consider optimizing task submission')
```

### Throttling task submission

Adjust your task submission rate based on current queue status:

```javascript theme={null}
const status = await checkQueueStatus();

// Only submit more tasks if queue is manageable
if (status.queuedTasks < 500) {
  await submitNextBatch();
} else {
  console.log('Queue is full, waiting before submitting more tasks');
  await delay(60000); // Wait 1 minute
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/async/status
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/status:
    get:
      summary: Get async queue status
      description: >-
        Get organization-wide async queue metrics including queued and
        processing task counts, and concurrency usage.
      operationId: getAsyncStatus
      responses:
        '200':
          description: Successful response with queue metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncStatusResponse'
        '401':
          description: Unauthorized - Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    AsyncStatusResponse:
      type: object
      required:
        - queuedTasks
        - processingTasks
        - priorityBreakdown
      properties:
        queuedTasks:
          type: integer
          description: Number of tasks currently queued for this organization.
          example: 3
        processingTasks:
          type: integer
          description: Number of tasks currently being processed for this organization.
          example: 2
        priorityBreakdown:
          type: array
          description: >-
            Queued task counts per priority level, ordered by priority
            descending. Only includes priority levels that have queued tasks.
          items:
            type: object
            required:
              - priority
              - count
            properties:
              priority:
                type: integer
                description: The priority level (1-10).
                minimum: 1
                maximum: 10
                example: 5
              count:
                type: integer
                description: Number of queued tasks at this priority level.
                example: 2
        concurrency:
          type: object
          nullable: true
          description: >-
            Current concurrency usage. Null if unable to retrieve concurrency
            information.
          properties:
            used:
              type: integer
              description: Number of concurrent slots currently in use.
              example: 2
            max:
              type: integer
              description: Maximum allowed concurrent tasks for this organization.
              example: 5
    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'
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````