Tasks

What is a task?

A task is a unit of work your agent hands off to Ploton. Your agent describes what it needs in plain language, and Ploton 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.",
    "user_id": "user_123"
  }'

{
	"id": "task_9vR3nQ",
	"status": "running",
	"tool": "crm",
	"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 jane@acme.com using the onboarding_v2 template",
    "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",
	"tool": "crm",
	"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",
	"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

Ploton learns from every task run. The first time it 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 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