Tasks

The Tasks API lets you schedule HTTP callback tasks, check their status, and manage their lifecycle.

Create a task

POST /v1/tasks

Request body

Field	Type	Required	Default	Description
targetUrl	string	Yes	-	The URL to call when the task executes. Must be a valid HTTP/HTTPS URL.
method	string	No	"POST"	HTTP method: GET, POST, PUT, or DELETE
headers	object	No	{}	Custom headers to include in the callback request. Values starting with tok_ are resolved from the Token Vault.
body	string	No	-	Request body (JSON stringified). Ignored for GET requests.
maxWaitTime	number	No	30	Maximum time (in seconds) to wait for the callback response
timeout	number	No	30	HTTP timeout (in seconds) for each attempt
delayUntil	string	No	-	ISO 8601 timestamp. Task will not execute until this time.
maxRetries	number	No	3	Maximum retry attempts (0-10)
retryBackoff	string	No	"exponential"	Retry strategy: linear or exponential
priority	number	No	5	Priority level (1-10). Higher numbers are processed first.
onCompleteUrl	string	No	-	Webhook URL to notify when task completes (success or failure)
provider	string	No	-	AI provider template ID (e.g., "fal", "replicate"). See Provider Templates.
pollConfig	object	No	-	Custom polling configuration for AI APIs. Required fields: urlTemplate, statusPath, doneValues, failValues. See AI Polling.

Example request

curl -X POST https://api.asyncqueue.io/v1/tasks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.example.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer service-token"
    },
    "body": "{\"action\": \"process\", \"data\": {\"id\": 123}}",
    "maxRetries": 3,
    "retryBackoff": "exponential",
    "priority": 8,
    "onCompleteUrl": "https://api.example.com/task-complete"
  }'

Example response (201 Created)

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "teamId": "team-uuid",
    "status": "pending",
    "targetUrl": "https://api.example.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer service-token"
    },
    "body": "{\"action\": \"process\", \"data\": {\"id\": 123}}",
    "maxWaitTime": 30,
    "timeout": 30,
    "maxRetries": 3,
    "retryCount": 0,
    "retryBackoff": "exponential",
    "priority": 8,
    "onCompleteUrl": "https://api.example.com/task-complete",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

---

Get a task

GET /v1/tasks/:id

Query parameters

Parameter	Type	Default	Description
wait	number	0	Long poll timeout in seconds (max 25). The API holds the connection and returns immediately when the task status changes. If no change occurs within the timeout, the current state is returned.

Example request

# Instant response
curl https://api.asyncqueue.io/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer your-api-key"

# Long poll - wait up to 20 seconds for a status change
curl "https://api.asyncqueue.io/v1/tasks/550e8400-e29b-41d4-a716-446655440000?wait=20" \
  -H "Authorization: Bearer your-api-key"

Example response - completed task

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "targetUrl": "https://api.example.com/webhook",
    "method": "POST",
    "maxRetries": 3,
    "retryCount": 0,
    "result": {
      "statusCode": 200,
      "headers": {"content-type": "application/json"},
      "body": "{\"success\": true, \"processedId\": 123}",
      "duration": 1234
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "startedAt": "2024-01-15T10:30:01.000Z",
    "completedAt": "2024-01-15T10:30:02.234Z"
  }
}

Example response - failed task

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "targetUrl": "https://api.example.com/webhook",
    "maxRetries": 3,
    "retryCount": 3,
    "error": "fetch failed: ECONNREFUSED",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "completedAt": "2024-01-15T10:30:15.000Z"
  }
}

---

List tasks

GET /v1/tasks

Query parameters

Parameter	Type	Default	Description
status	string	-	Filter by status: pending, delayed, processing, waiting, polling, completed, failed, timeout, cancelled
limit	number	50	Number of results (max 100)
offset	number	0	Pagination offset
sortOrder	string	"desc"	Sort by creation time: asc or desc

Example request

curl "https://api.asyncqueue.io/v1/tasks?status=pending&limit=10" \
  -H "Authorization: Bearer your-api-key"

Example response

{
  "tasks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "targetUrl": "https://api.example.com/webhook",
      "method": "POST",
      "maxRetries": 3,
      "retryCount": 0,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

---

Cancel a task

POST /v1/tasks/:id/cancel

Only tasks with status pending, delayed, waiting, or polling can be cancelled.

Example request

curl -X POST https://api.asyncqueue.io/v1/tasks/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer your-api-key"

Example response

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "targetUrl": "https://api.example.com/webhook",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "completedAt": "2024-01-15T10:31:00.000Z"
  }
}

---

Task status lifecycle

Tasks progress through these statuses:

Status	Description
pending	Queued and waiting to be processed
delayed	Waiting for its delayUntil time
processing	Worker is executing the callback
waiting	Waiting for external signal or callback
polling	Polling an AI provider’s status endpoint
completed	Callback returned successfully (2xx, 3xx, or 4xx)
failed	All retry attempts exhausted
timeout	Task exceeded maxWaitTime
cancelled	Cancelled before processing started

---

Error responses

// 400 - Validation error
{"error": "targetUrl is required"}
{"error": "targetUrl must be a valid HTTP/HTTPS URL"}
{"error": "method must be one of: GET, POST, PUT, DELETE"}
{"error": "maxRetries must be a number between 0 and 10"}
{"error": "priority must be an integer between 1 and 10"}
{"error": "delayUntil must be a valid ISO 8601 date"}

// 401 - Authentication error
{"error": "API key required"}
{"error": "Invalid or revoked API key"}

// 403 - Authorization error
{"error": "Access denied"}

// 404 - Not found
{"error": "Task not found"}

// 429 - Rate limit exceeded
{"error": "Rate limit exceeded. Upgrade your plan for higher limits."}