> ## 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. # Create async task > Submit an asynchronous task for background processing. Returns a task ID that you can use to poll for results or receive via webhook. ## Overview Use this endpoint to submit a task for asynchronous processing. You'll receive a `taskId` in the response that you can use to: * **Poll for results** via [`GET /v1/async/task/{taskId}`](/api-reference/endpoint/get-task-status) * **Receive results via webhook** if you provide a `webhook.url` in the request All newly created tasks start with status `QUEUED`. The scheduler processes tasks by [priority](/guides/making-requests/async#request-prioritization) first (higher numbers first), then in FIFO order within the same priority level. ## Priority You can optionally set a `priority` from 1 (lowest, default) to 10 (highest). Tasks with higher priority are processed before lower-priority ones. If you don't specify a priority, it defaults to 1. Monitor your queue's priority distribution using the [async status endpoint](/api-reference/endpoint/get-async-status). ## Idempotency You can optionally include an `idempotencyKey` to prevent duplicate task creation. If you submit a request with an idempotency key that has already been used, the API returns a `409 Conflict` error. ## Example usage ```bash cURL theme={null} curl -X POST "https://api.cloro.dev/v1/async/task" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "taskType": "CHATGPT", "priority": 5, "idempotencyKey": "your-custom-identifier-123", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "What is the weather in New York?", "country": "US" } }' ``` ```json Response theme={null} { "success": true, "task": { "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9", "taskType": "CHATGPT", "status": "QUEUED", "priority": 5, "createdAt": "2025-11-10T15:00:00.000Z", "idempotencyKey": "your-custom-identifier-123" }, "credits": { "creditsToCharge": 10, "creditsCharged": 0 } } ``` ## OpenAPI ````yaml api-reference/openapi.json POST /v1/async/task 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: post: summary: Create async task description: >- Submit an asynchronous task for background processing. Returns a task ID that you can use to poll for results or receive via webhook. operationId: createAsyncTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchTaskRequest' example: taskType: CHATGPT priority: 5 idempotencyKey: your-custom-identifier-123 webhook: url: https://your-app.com/webhook-handler payload: prompt: What is the weather in New York? country: US responses: '200': description: Task created successfully. Returns task ID and initial status. content: application/json: schema: $ref: '#/components/schemas/AsyncTaskCreateResponse' '401': description: Unauthorized - Authentication error content: application/json: schema: $ref: '#/components/schemas/AuthenticationError' '409': description: Conflict - Task with this idempotencyKey already exists content: application/json: schema: $ref: '#/components/schemas/ConflictError' '422': description: Validation Error - Invalid request body content: application/json: schema: $ref: '#/components/schemas/ValidationError' '429': description: Queue Limit Exceeded - Organization has reached maximum queued tasks content: application/json: schema: $ref: '#/components/schemas/QueueLimitError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalError' security: - bearerAuth: [] components: schemas: BatchTaskRequest: type: object required: - taskType - payload properties: taskType: type: string enum: - AIMODE - GOOGLE - GOOGLE_NEWS - GEMINI - CHATGPT - COPILOT - PERPLEXITY - GROK description: The AI provider to use for this task. example: CHATGPT payload: type: object description: >- Provider-specific request payload. Must include at least `prompt` (or `query` for Google Search). example: prompt: What do you know about Acme Corp? country: US priority: type: integer description: >- Task priority level (1-10). Higher numbers are processed first. Defaults to 1. minimum: 1 maximum: 10 default: 1 example: 5 idempotencyKey: type: string description: >- Unique string to prevent duplicate task creation. Must be unique across your account. example: batch-chatgpt-001 webhook: type: object description: Webhook configuration for task completion notification. properties: url: type: string format: uri description: URL to receive the webhook POST request when the task completes. example: https://your-app.com/webhook-handler required: - url additionalProperties: false additionalProperties: false AsyncTaskCreateResponse: type: object required: - success - task - credits properties: success: type: boolean example: true task: $ref: '#/components/schemas/AsyncTaskSummary' credits: $ref: '#/components/schemas/AsyncTaskCredits' 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' ConflictError: type: object properties: error: type: object properties: code: type: string example: RESOURCE_CONFLICT message: type: string example: Resource conflict timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' ValidationError: type: object properties: success: type: boolean example: false error: type: string example: Request validation failed details: type: array items: type: object properties: field: type: string example: prompt message: type: string example: Prompt cannot be empty QueueLimitError: type: object required: - success - error properties: success: type: boolean example: false error: type: object required: - code - message - timestamp properties: code: type: string enum: - QUEUE_LIMIT_EXCEEDED example: QUEUE_LIMIT_EXCEEDED message: type: string example: Batch would exceed queue capacity details: type: object properties: queuedCount: type: integer description: Current number of tasks in the queue. example: 99950 batchSize: type: integer description: Number of tasks in the submitted batch. example: 100 maxQueueSize: type: integer description: Maximum allowed queue size. example: 100000 remainingCapacity: type: integer description: Number of tasks that can still be added to the queue. example: 50 timestamp: type: string format: date-time example: '2026-04-09T15: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 ````