---
title: "Submit an async task"
method: POST
path: "/v1/async/task"
---

# Submit an async task

`POST /v1/async/task`

## Request

- Base URL: `https://api.answerline.dev`
- URL: `https://api.answerline.dev/v1/async/task`
- Auth: HTTP bearer

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.

## Request body

- BatchTaskRequest
  - `taskType` 'AIMODE' | 'GOOGLE' | 'GOOGLE_NEWS' | 'GEMINI' | 'CHATGPT' | 'COPILOT' | 'PERPLEXITY' | 'GROK', required: AI provider that should handle this task.
  - `payload` object, required: Request body specific to the provider. 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.
  - `webhook` object: Settings for the webhook that reports a finished task.
    - `url` string, uri, required: Endpoint that gets the webhook POST request once the task finishes.

## Response `200`

Task created. The response includes its ID and starting status.

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

## Other responses

- `401`: Unauthorized - authentication failed
- `403`: Forbidden - missing permissions, or 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 - your organization already has the maximum number of queued tasks. This status is also returned when the API key's rate limit is hit and when the API sheds load (`SERVICE_OVERLOADED`, sent with `Retry-After` and without limit headers)
- `500`: Internal Server Error

---

[API](https://skmtc.dev/answerline/apis/answerline-api.md) · [All operations](https://skmtc.dev/answerline/apis/answerline-api/llms.txt) · [OpenAPI document](https://skmtc.dev/answerline/apis/answerline-api/revisions/a9dc35794662?raw)