# Submit an async task

`POST https://api.answerline.dev/v1/async/task`

Queue a task to run asynchronously in the background. The response contains a task ID you can poll for the result, or the result can be delivered by webhook.

## Body

- `taskType` ("AIMODE" | "GOOGLE" | "GOOGLE_NEWS" | "GEMINI" | "CHATGPT" | "COPILOT" | "PERPLEXITY" | "GROK", required): Engine that should handle this task.
- `payload` (object, required): Request body specific to the engine. Needs at least `prompt` (`query` for Google Search).
- `priority` (integer): Priority of the task, from 1 to 10; tasks with higher numbers run first. Default: 1.
- `idempotencyKey` (string): Distinct string that stops the same task from being created twice. No two tasks in your account may share it: the key stays bound while its task is kept (4 to 5 days after it finishes), and a failed task frees it 24 hours after failing.
- `webhook` (object): Settings for the webhook that reports a finished task.
  - `webhook.url` (string, required): Endpoint that gets the webhook POST request once the task finishes.

## Returns

- `success` (boolean, required)
- `task` (object, required): Summary fields that every async task response includes.
  - `task.id` (string, required): Identifier unique to the task.
  - `task.taskType` ("AIMODE" | "GOOGLE" | "GOOGLE_NEWS" | "GEMINI" | "CHATGPT" | "COPILOT" | "PERPLEXITY" | "GROK", required): Engine that handles this task.
  - `task.status` ("QUEUED" | "PROCESSING" | "COMPLETED" | "FAILED", required): Status of the task right now.
  - `task.priority` (integer, required): Priority of the task, from 1 to 10; tasks with higher numbers run first. Default: 1.
  - `task.createdAt` (string, required): Creation time of the task.
  - `task.latencyMs` (integer | null): Time from the task's start to its final outcome, in milliseconds. The wait in the queue before it starts is not counted. Null for tasks in `QUEUED` or `PROCESSING` state, and for tasks that failed before processing began.
  - `task.idempotencyKey` (string | null): Idempotency key supplied with the request, if any.
- `credits` (object, required): Charge details for one async task, in USD.
  - `credits.creditsToCharge` (number, required): USD amount held back from the balance for this task.
  - `credits.creditsCharged` (number | null, required): USD amount charged for the task (0 when a free request covered it); null while it has not finished.

## Responses

- 200: Task created. The response includes its ID and starting status.
- 401: Unauthorized - authentication failed
- 403: Forbidden - INSUFFICIENT_CREDITS: too little balance left to pay for this task
- 409: Conflict - a task already uses this idempotencyKey
- 422: Validation Error - the body of the request is invalid
- 429: Queue Limit Exceeded - the task does not fit in your queue. This status is also returned when the API cannot take the request right now (`SERVICE_OVERLOADED`, sent with `Retry-After` and without limit headers) and when one address presented too many unknown keys (`RATE_LIMIT_EXCEEDED`, with `Retry-After`)
- 500: Internal Server Error

## Request

curl:

```bash
curl -X POST "https://api.answerline.dev/v1/async/task" \
  -H "Authorization: Bearer $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":"Which museums in Chicago are free on weekdays?","country":"US"}}'
```


## Example responses

200:

```json
{
  "success": true,
  "task": {
    "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
    "taskType": "CHATGPT",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-04-09T15:00:00.000Z",
    "latencyMs": null,
    "idempotencyKey": "batch-chatgpt-001"
  },
  "credits": {
    "creditsToCharge": 0.0015,
    "creditsCharged": null
  }
}
```