Skip to main content
POST
/
public
/
v1
/
tasks
/
{taskId}
/
runs
Queue task run
curl --request POST \
  --url https://api.komos.ai/public/v1/tasks/{taskId}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "clientRequestId": "checkout-48219",
  "inputs": {
    "url": "https://example.com/orders/48219",
    "runHeadless": true
  }
}'
{
  "run": {
    "id": "220a501c-82f4-43e2-8107-3d8e0c0f4c1b",
    "taskId": "79c6b1aa-24d1-45b3-8c94-9a2e2a2f55bc",
    "status": "COMPLETED",
    "triggerType": "api",
    "timestamps": {
      "createdAt": "2025-10-13T15:02:44.812Z",
      "startedAt": "2025-10-13T15:02:47.001Z",
      "finishedAt": "2025-10-13T15:03:28.559Z"
    },
    "progress": {
      "currentStep": 5,
      "stepsTotal": 5
    },
    "inputs": {
      "url": "https://example.com/orders/48190"
    },
    "outputs": {
      "summary": "Completed order checkout scrape"
    },
    "logsUrl": "https://api.komos.ai/public/v1/task-runs/220a501c-82f4-43e2-8107-3d8e0c0f4c1b/logs",
    "error": null,
    "cancelReason": null
  }
}
Use this endpoint to queue a new asynchronous run for an existing task. Provide a UUID task ID from the Komos dashboard and optional input overrides that match the task’s input schema.

​
Request

​
Path parameters

  • taskId — UUID for the saved task.

​
Body fields

  • inputs (object, optional) — Key/value overrides that map to the task’s declared inputs. Any keys omitted fall back to defaults defined in the task.
  • clientRequestId (string, optional) — Supply a unique value per task to make the request idempotent. Repeating the same value returns 200 OK with the previously created run.

​
Example

curl -X POST \
  https://api.komos.ai/public/v1/tasks/4df7d6f9-56be-4f77-9b18-25ad908a20b7/runs \
  -H 'Authorization: Bearer sk_live_example' \
  -H 'Content-Type: application/json' \
  -d '{
        "clientRequestId": "checkout-48219",
        "inputs": {
          "url": "https://example.com/orders/48219",
          "runHeadless": true
        }
      }'

​
Responses

  • 202 Accepted — The run was created and queued for execution. The payload contains the run resource with status: "PENDING".
  • 200 OK — A run with the supplied clientRequestId already exists; the response returns the existing run without enqueuing another execution.
  • 400 Bad Request — Invalid task ID or payload shape.
  • 401 Unauthorized — Missing or malformed API key.
  • 402 Payment Required — Your organization exhausted its run allotment; the response includes usage details.
  • 404 Not Found — The task does not exist or is not accessible to the current organization.
  • 503 Service Unavailable — A transient queue error prevented dispatch; retry with exponential backoff.
Once accepted, poll GET /public/v1/task-runs/{runId} or subscribe to task-run.* webhooks to follow execution.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
taskId
string<uuid>
required

UUID of the Komos task to execute.

Body

application/json
​
inputs
object

Overrides to the task input schema.

​
clientRequestId
string

Optional idempotency key unique per task and organization.

Response

Existing run returned because the clientRequestId was reused.

​
run
object
required