Tasks

What is a task?

A task is a unit of work your agent routes to a subagent. Your agent describes what it needs in plain language and specifies which subagent should handle it. The subagent figures out the rest — selecting tools, building a workflow, handling auth, recovering from failures, and returning structured results.

One task is one task regardless of how complex it is internally. A simple weather lookup and a multi-step CRM sync involving OAuth, pagination, and data transformation both count as one task.

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Pull all open deals from user_123'\''s CRM account. Return deal name, amount, stage, and expected close date.",
    "sub_agent": "crm-agent",
    "user_id": "user_123"
  }'

{
	"id": "task_9vR3nQ",
	"status": "running",
	"sub_agent": "crm-agent",
	"created_at": "2025-06-15T09:14:00Z"
}

Your agent gets an immediate acknowledgment and moves on. Ploton calls back when done.

Task lifecycle

Every task moves through these states:

stateDiagram-v2
    [*] --> pending
    pending --> running
    pending --> cancelled
    running --> complete
    running --> failed
    running --> waiting
    waiting --> running : Input received
    complete --> [*]
    failed --> [*]
    cancelled --> [*]

States

The waiting state

Some tasks need user interaction. Most commonly, OAuth consent for a service the user hasn’t connected yet. When this happens, the task enters waiting and Ploton sends a task.waiting webhook with a URL you can show the user:

{
	"event": "task.waiting",
	"task_id": "task_9vR3nQ",
	"timestamp": "2025-06-15T09:14:02Z",
	"data": {
		"reason": "oauth_consent_required",
		"service": "crm",
		"auth_url": "https://ploton.ai/auth/crm?session=sess_abc123",
		"message": "User needs to authorize CRM access"
	}
}

Once the user completes the flow, the task picks up where it left off.

Creating tasks

Required fields

Optional fields

Example: task with metadata

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Send a welcome email to [email protected] using the onboarding_v2 template",
    "sub_agent": "billing-agent",
    "user_id": "user_456",
    "metadata": {
      "internal_request_id": "req_abc789",
      "triggered_by": "signup_flow"
    }
  }'

Retrieving tasks

Get a single task

curl https://api.ploton.ai/v1/tasks/task_9vR3nQ \
  -H "Authorization: Bearer $PLOTON_API_KEY"

{
	"id": "task_9vR3nQ",
	"status": "complete",
	"sub_agent": "crm-agent",
	"created_at": "2025-06-15T09:14:00Z",
	"completed_at": "2025-06-15T09:14:07Z",
	"result": {
		"deals": [
			{
				"name": "Acme Corp - Enterprise",
				"amount": 48000,
				"stage": "Negotiation",
				"expected_close": "2025-07-01"
			}
		]
	},
	"metadata": {}
}

List tasks

curl "https://api.ploton.ai/v1/tasks?status=complete&limit=10" \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Query parameters: status, user_id, limit (default 20, max 100), offset.

Cancelling tasks

Cancel a task that’s pending or running:

curl -X POST https://api.ploton.ai/v1/tasks/task_9vR3nQ/cancel \
  -H "Authorization: Bearer $PLOTON_API_KEY"

If the task already completed or failed, the cancel request returns a 409 Conflict.

Task errors

When a task fails, the response includes an error object:

{
	"id": "task_9vR3nQ",
	"status": "failed",
	"sub_agent": "crm-agent",
	"error": {
		"code": "auth_token_expired",
		"message": "The user's CRM OAuth token has expired and automatic refresh failed.",
		"tool": "crm",
		"recoverable": true,
		"suggestion": "Prompt the user to re-authorize CRM access"
	}
}

recoverable tells you whether retrying is likely to work (possibly after user action). suggestion gives you a next step.

Trained tasks

Subagents learn from every task run. The first time a crm-agent hits a CRM, it connects, authenticates, and fetches data. By the fiftieth run, it already knows the rate limits, the field naming quirks, the optimal batch size. Training is scoped to each subagent’s domain.

Training builds two kinds of knowledge:

• Tool knowledge — API endpoints, auth flows, data formats, pagination patterns, rate limits, required scopes. Built from real interactions, not just docs.
• Execution memory — which OAuth scopes were needed, which field mappings handled edge cases, which retry strategies recovered from failures, what batch sizes worked best under load.

Think of it less like a cache and more like institutional memory that gets better over time.

Run 1:   Connect → OAuth → fetch → success. Learned: required scopes.
Run 5:   Reuse known scopes → skip discovery → 40% faster. Learned: rate limits.
Run 20:  Schema changed → adapt field mapping → recover. Learned: field renames.
Run 50:  Knows batch sizes, failure patterns, recovery paths → handles edge cases automatically.

Training is automatic — you don’t configure or maintain it. Tasks just get better over time as a side effect of running.

Ploton ships with pre-trained tools for popular services (see Tools: Built-in tools for the list). You can also train Ploton on your own services — see Registering Custom Tools.

Next steps

• Workflows — how Ploton builds and adapts execution plans
• Webhooks — receive task results and lifecycle events
• REST API — full endpoint reference for task operations