Create async task
Queue a single extraction job to run in the background and get back a task identifier you can poll or receive results for through a webhook.
Overview
Send this request when you want the platform to run an extraction without holding your HTTP connection open. The response returns immediately with a task id and an initial status of QUEUED. From there you have two ways to collect the finished result: poll GET /v1/async/task/{id} until the status reports completion, or register a webhook.url so the platform posts the result to your endpoint as soon as the job finishes.
The scheduler drains the queue by priority first — higher values run ahead of lower ones — and preserves first-in, first-out ordering among jobs that share the same priority.
Authorization
| Field | Type | Description |
|---|---|---|
| Authorization | string (header, required) | Bearer credential in the form Bearer <token>, where <token> is your API key. |
Request body
| Field | Type | Description |
|---|---|---|
| taskType | enum<string> (required) | Which AI engine handles the job. Accepted values: AIMODE, GOOGLE, GOOGLE_NEWS, GEMINI, CHATGPT, COPILOT, PERPLEXITY, GROK. |
| payload | object (required) | Engine-specific input. At minimum include a prompt (or query for Google Search), plus optional fields such as country. |
| priority | integer (default 1) | Scheduling weight from 1 to 10. Larger numbers are dispatched sooner; omitting it leaves the job at the lowest priority of 1. |
| idempotencyKey | string (optional) | A caller-chosen identifier, unique within your account, that guards against creating the same task twice. Reusing a key that already exists yields a 409 response. |
| webhook | object (optional) | Delivery target for the completion callback. Supply webhook.url to have the finished result pushed to your service. |
Priority and idempotency
Priority is a hint to the scheduler, not a guarantee of exact ordering across the whole fleet — it simply moves your job ahead of anything queued at a lower level. Idempotency keys are the safe way to retry a submission after a network hiccup: if the first call already registered the task, the retry is rejected with a 409 rather than silently duplicating work.
Response example
{
"success": true,
"task": {
"id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
"taskType": "CHATGPT",
"status": "QUEUED",
"priority": 5,
"createdAt": "2026-08-14T09:20:00.000Z",
"idempotencyKey": "your-custom-identifier-123"
},
"credits": {
"creditsToCharge": 10,
"creditsCharged": null
}
}Response fields
| Field | Type | Description |
|---|---|---|
| success | boolean | True when the task was accepted into the queue. |
| task | object | Summary of the queued job: id, taskType, status, priority, createdAt, and the echoed idempotencyKey. |
| credits | object | Billing preview for the job. creditsToCharge is the estimated cost; creditsCharged stays null until the task actually runs. |
Notes
Common status codes for this endpoint include 200 (queued), 401 (bad or missing credential), 409 (idempotency key already used), 422 (invalid body), 429 (rate limited), and 500 (server error). If a job stays queued longer than expected, check your account's queue depth before retrying, and reach out to [email protected] with the task id if a result never arrives.