{"slug":"tasks","title":"Tasks","path":"tasks.md","markdown":"# Tasks\n\nA task is an immediate (one-shot) agent run created through this API. Create queues a job and returns right away; poll status, then fetch scrubbed history when it finishes.\n\n**Scope:** only jobs with a public `tsk_…` id minted by `POST /v1/tasks`. Schedule-triggered runs and product-UI jobs are not listed or addressable here. Tasks do not support webhooks. Job event streams and permission/credential gate submission are not part of this API.\n\nTypical flow: create → poll get → history when terminal → optional delete or clear.\n\n## Identifiers\n\n| Field | Role |\n| ----- | ---- |\n| `id` | Stable handle (`tsk_…`). Use this in get/history/cancel/retry/delete and CLI `-id` / `-ids`. |\n| `agentId` | Site agent (`ag_…` from `agents list`). |\n| `knowledgebaseId` | Knowledgebase (`kb_…`) the agent runs against. |\n\nExample task object:\n\n```json\n{\n  \"id\": \"tsk_7k2m9x4q\",\n  \"agentId\": \"ag_7k2m9x4q\",\n  \"agentName\": \"Kobold AI\",\n  \"knowledgebaseId\": \"kb_qc0rp0gz\",\n  \"prompt\": \"Summarize new files\",\n  \"state\": \"queued\",\n  \"createdAt\": \"2026-07-16T19:24:19.812169Z\"\n}\n```\n\n**States:** `queued`, `running`, `completed`, `failed`, `cancelled`. You may also see `needs_permission`, `required_credentials`, or `waiting_on_child` when a run is blocked. There are no public endpoints to unblock gates; cancel the task or wait for a future gate API.\n\n`usage` (when present) has `inputTokens`, `outputTokens`, and `toolCalls`. Optional timestamps: `startedAt`, `finishedAt`. Optional `error` on failure.\n\n## List\n\nLists tasks created via this API for your key (newest first). Query: `offset`, `limit` (default `50`). Orphan aliases (runner job already gone) are omitted from the page and cleaned up server-side.\n\n```bash\nkobold-cli tasks list\nkobold-cli tasks list -offset 0 -limit 20\n```\n\n```http\nGET /v1/tasks?offset=0\u0026limit=50\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nResponse:\n\n```json\n{\n  \"tasks\": [ /* Task objects */ ],\n  \"offset\": 0,\n  \"limit\": 50,\n  \"total\": 3\n}\n```\n\n## Create\n\nQueues an immediate run. Same inputs as schedule create minus `interval` and `hooks`. Enforces active/total task and day/month token limits. Mints `tsk_…`.\n\n```bash\nkobold-cli tasks create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt \"Summarize new files\"\nkobold-cli tasks create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt ./prompt.md\n```\n\n```http\nPOST /v1/tasks\nAuthorization: Bearer \u003capi_key\u003e\nContent-Type: application/json\n\n{\n  \"agentId\": \"ag_7k2m9x4q\",\n  \"knowledgebaseId\": \"kb_qc0rp0gz\",\n  \"prompt\": \"Summarize new files\"\n}\n```\n\nSuccess returns a `Task`, typically with `state: \"queued\"`. Unknown agent or knowledgebase for your key → `404`. Limit exceeded → `429`.\n\n## Get (poll)\n\n```bash\nkobold-cli tasks get -id tsk_7k2m9x4q\n```\n\n```http\nGET /v1/tasks/tsk_7k2m9x4q\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nUnknown or other-tenant id → `404`.\n\n## History\n\nChat-like result after (or during) a run. Every transcript message with `role == \"system\"` is dropped. `response` is the last non-empty assistant text after that scrub. Raw event streams are not exposed.\n\n```bash\nkobold-cli tasks history -id tsk_7k2m9x4q\n```\n\n```http\nGET /v1/tasks/tsk_7k2m9x4q/history\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nExample shape:\n\n```json\n{\n  \"response\": \"Here is a short summary…\",\n  \"transcript\": [\n    { \"role\": \"user\", \"text\": \"Summarize new files\" },\n    { \"role\": \"assistant\", \"text\": \"Here is a short summary…\" }\n  ],\n  \"state\": \"completed\",\n  \"usage\": {\n    \"inputTokens\": 1200,\n    \"outputTokens\": 340,\n    \"toolCalls\": 2\n  }\n}\n```\n\n## Cancel\n\nSoft-cancels a non-terminal task. The row is kept with `state: \"cancelled\"`. Already-terminal tasks are rejected.\n\n```bash\nkobold-cli tasks cancel -id tsk_7k2m9x4q\n```\n\n```http\nPOST /v1/tasks/tsk_7k2m9x4q/cancel\nAuthorization: Bearer \u003capi_key\u003e\n```\n\n## Retry\n\nRequeues a `failed` task. Other states are rejected.\n\n```bash\nkobold-cli tasks retry -id tsk_7k2m9x4q\n```\n\n```http\nPOST /v1/tasks/tsk_7k2m9x4q/retry\nAuthorization: Bearer \u003capi_key\u003e\n```\n\n## Delete\n\nHard-deletes the runner job and its public alias.\n\n```bash\nkobold-cli tasks delete -id tsk_7k2m9x4q\n```\n\n```http\nDELETE /v1/tasks/tsk_7k2m9x4q\nAuthorization: Bearer \u003capi_key\u003e\n```\n\nCLI prints `{\"ok\": true}` on success.\n\n## Clear (bulk delete)\n\nHard-deletes several API-created tasks. Unknown ids are skipped.\n\n```bash\nkobold-cli tasks clear -ids tsk_7k2m9x4q,tsk_abc12345\n```\n\n```http\nPOST /v1/tasks/clear\nAuthorization: Bearer \u003capi_key\u003e\nContent-Type: application/json\n\n{\n  \"ids\": [\"tsk_7k2m9x4q\", \"tsk_abc12345\"]\n}\n```\n\nResponse: `{ \"cleared\": N }` (rows actually removed upstream).\n\n## Related\n\n- [CLI reference](cli-reference.md) — full `tasks` flags\n- [Getting started](getting-started.md) — API key and `stats get` for task/token ceilings\n- Agents: `kobold-cli agents list` for `ag_…` ids\n- Knowledgebases: [Knowledgebases](knowledgebases.md) for `kb_…` ids\n"}