---
title: "Run Task"
method: POST
path: "/tasks"
tags: ["Tasks"]
---

# Run Task

`POST /tasks`

Create and dispatch a new agent task. Returns the task ID and device stream details.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- TaskCreate
  - `agentId` integer
  - `llmModel` string — The LLM model identifier to use for the task (e.g. 'google/gemini-3.5-flash')
  - `task` string, required
  - `maxSteps` integer
  - `temperature` number
  - `reasoning` boolean
  - `accessibility` boolean
  - `vision` boolean
  - `executionTimeout` integer
  - `credentials` PackageCredentials[]
    - `packageName` string, required
    - `credentialNames` string[], required
  - `apps` string[]
  - `files` string[]
  - `outputSchema` object, nullable
  - `vpnCountry` 'US' | 'BR' | 'FR' | 'DE' | 'IN' | 'JP' | 'KR' | 'ZA'
  - `subagentModel` string — LLM model used by sub-agent roles: executor, app_opener, structured_output
  - `stealth` boolean
  - `continueOnFailure` boolean
  - `memoryNamespace` string — Memory namespace for cross-task personalization
  - `deviceId` string, uuid, required — The ID of the device to run the task on.
  - `displayId` integer — The display ID of the device to run the task on.

## Response `201`

Successful Response

- TaskCreatedResponse
  - `id` string, uuid, required — The ID of the task
  - `status` 'queued' | 'created' | 'running' | 'cancelling' | 'completed' | 'failed' | 'cancelled', required
  - `streamUrl` string, nullable — The URL of the stream (null when queued)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `409` — Conflict
- `412` — Precondition Failed
- `422` — Unprocessable Content
- `500` — Internal Server Error

## Changes

- **2026-08-13** `02da4f9ce3fd` — 2 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the non-success response with the status `409`
- **2026-07-28** `2021bc9144be` — 1 info
  - removed the `paused` enum value from the `status` response property for the response status `201`
- **2026-07-23** `f1f39508a8f7` — 2 info
  - the `llmModel` request property default value changed from `google/gemini-3.1-flash-lite` to `google/gemini-3.5-flash`
  - the `subagentModel` request property default value changed from `google/gemini-3.1-flash-lite` to `google/gemini-3.5-flash`
- **2026-05-26** `3991e7ab0365` — 3 info
  - added the new optional request property `accessibility`
  - the `llmModel` request property default value changed from `google/gemini-3.1-flash-lite-preview` to `google/gemini-3.1-flash-lite`
  - the `subagentModel` request property default value changed from `google/gemini-3.1-flash-lite-preview` to `google/gemini-3.1-flash-lite`

[Change history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/tasks/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) · [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/droidrun/droidrun-cloud/revisions/a1453ac769d4/schema)