--- slug: developer-api-create-read-tasks title: Create and read Tasks category: capability status: published tags: [create task, read task, poll, status, result, usage, 创建任务, 查询状态, 轮询] aliases: [] lastEditAt: 2026-08-02 --- ## Create a Task ```bash curl -sS https://tycoon.us/api/public/tasks \ -H "Authorization: Bearer $TYCOON_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: organic-growth-2026-08-01" \ -d '{ "prompt": "Improve organic growth through durable, evidence-backed work.", "title": "Organic-growth outcome", "workspace_id": "", "budget_usd": 250, "working_guidance": "Prefer reversible SEO experiments and concise weekly updates.", "playbook_id": "", "outcome": { "target": "Increase qualified organic clicks by 305% from the measured baseline.", "deadline_at": "2026-11-01T00:00:00.000Z", "metric_id": "" } }' ``` First response (`201`): ```json { "task": { "id": "cm...", "title": "Competitor research", "status": "queued", "created_at": "2026-08-01T12:00:00.000Z" }, "workspace": { "id": "cm...", "name": "Growth", "slug": "growth", "task_bound": false }, "idempotent_replay": false } ``` `prompt` is required and limited to 20,000 characters. `title` (200 characters), `workspace_id`, and `budget_usd` (at most 100,000) are optional. Omitting `workspace_id` creates an isolated task-bound workspace; specifying it requires either the API key's controller workspace or a currently valid explicit binding. Omitting `budget_usd` means no per-Task ceiling; it does not make workspace usage free. The response's `workspace` is the immutable execution home for that Task. A later request may use a different or newly created workspace, but no API call can migrate an existing Task. The key controller workspace remains the payer for every one of those Tasks and their direct child contributions. The optional durable-outcome fields — `outcome`, `working_guidance`, and `playbook_id` — are described under *Long-running outcomes*. `skill` is the more explicit Skill input. Send either `skill.id` (an existing Company Skill in the execution workspace) or a Markdown-only `skill.upload`: ```json "skill": { "upload": { "name": "SEO experiment method", "description": "Customer-supplied operating method for this one Task.", "markdown": "# Method\n1. Establish the baseline...", "tags": ["seo", "experiment"] } } ``` Tycoon creates an Astra-private Skill in that Task's execution workspace and pins its first revision to the Task. The upload has no file, connector, secret, workspace-sharing, or standing Skill-management authority. `playbook_id` and `skill` are mutually exclusive. Add `runtime` to an ordinary-key request using the runtime catalog receipt above. Add `callback` to receive events only for this Task, or `cadence` to create an existing Routine-backed follow-up for this long-horizon outcome: ```json { "callback": { "url": "https://customer.example/hooks/organic-growth", "events": ["task.check_in", "task.requires_action", "task.done"], "secret": "a-customer-secret-with-at-least-16-characters" }, "cadence": { "cron": "0 9 * * 1", "timezone": "America/Los_Angeles", "title": "Weekly organic-growth follow-up" } } ``` The callback secret is accepted for delivery signing but never returned or included in a Task projection. `cadence` uses a five-field cron expression and the existing Routine owner; it is not a public scheduler or a second Task lifecycle. A published-method customer may supply a callback, but cannot pick a cadence. ## Read status, result, and usage ```bash curl -sS https://tycoon.us/api/public/tasks/cm... \ -H "Authorization: Bearer $TYCOON_API_KEY" ``` ```json { "task": { "id": "cm...", "reference": "acme-42", "title": "Competitor research", "status": "completed", "created_at": "2026-08-01T12:00:00.000Z", "started_at": "2026-08-01T12:00:03.000Z", "completed_at": "2026-08-01T12:04:21.000Z", "updated_at": "2026-08-01T12:04:21.000Z" }, "outcome": { "updated_at": "2026-08-01T12:04:21.000Z", "summary": "The experiment is live and the next weekly observation is scheduled.", "judgment": "unmet", "trajectory": "on-track", "remaining_gap": "The target lift is not yet proven.", "next": { "kind": "wait", "label": "Observe the weekly Metric sample", "at": "2026-08-08T12:00:00.000Z", "wait_for": "routine observation" }, "measure": { "title": "Qualified organic clicks", "unit": "clicks", "current_value": 125, "baseline_value": 100, "baseline_at": "2026-08-01T12:00:00.000Z", "target_value": null, "last_synced_at": "2026-08-01T12:00:00.000Z" }, "cadences": [{ "purpose": "measurement", "status": "active", "cadence": "weekly", "next_run_at": "2026-08-08T12:00:00.000Z", "health": "healthy" }] }, "playbook": { "id": "", "revision": "", "name": "Growth operating method" }, "result": { "text": "...", "created_at": "2026-08-01T12:04:20.000Z" }, "required_actions": [], "usage": { "input_tokens": 12340, "output_tokens": 1870, "cached_input_tokens": 4200, "cost_usd_micros": "482000", "cost_usd": 0.482, "ledger_entries": 3, "wallet_debit_applied": true, "budget_usd_micros": "25000000" }, "poll_after_ms": null } ``` Statuses are `queued`, `running`, `requires_action`, `waiting`, `completed`, or `canceled`. Before a terminal state, honor `poll_after_ms`. If `required_actions` is non-empty, read its `id`, `action_version`, safe `items`, and `api_resolvable` flag, then follow *Resolve a required action from your backend*. The response deliberately omits workspace memory, system prompts, model reasoning, agent/pod/run identities, child execution traces, and raw Task metadata. Usage includes the API root and any direct child Tasks Astra used to complete it, so delegated work is not silently under-counted. For a completed Success-Brief Task, `result.text` is the accepted result summary from the exact current `Task.currentAcceptedEvaluationId`, projected through the same communication snapshot used by Tasks and Astra. Plain and historical Tasks fall back to the durable close Comment selected by `TaskResult.closeCommentId`. A later Comment, stale evaluation, or invalid/cross-Task pointer cannot silently replace the published result. ## Pause, resume, or cancel a Task Use the canonical lifecycle control adapter when the customer needs to stop or resume work. It requires `tasks:write` and an `Idempotency-Key`. ```bash curl -sS -X POST https://tycoon.us/api/public/tasks/cm.../control \ -H "Authorization: Bearer $TYCOON_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: organic-growth-pause-1" \ -d '{"action":"pause"}' ``` Actions are `pause`, `resume`, and `cancel`. Pause/resume use the existing archive/restore fence; cancel uses the existing Task end owner, terminal notification, timing, and dependent-Task wake path. There is no API-only Task status. A same-body replay returns the same accepted response with `idempotent_replay: true`. ## Next steps - [Long-running outcomes](/help/developer-api-long-running-outcomes) - [Messages, actions, and approvals](/help/developer-api-actions-approvals) - [Idempotency, retries, errors, and limits](/help/developer-api-reliability-errors)