REST API | Ploton Docs

Tasks

A task is a unit of work. You create one, Ploton runs it.

All endpoints require an Authorization: Bearer <api_key> header.

Create a task

POST /v1/tasks

Creates a task and starts running it immediately.

Request body

Field	Type	Required	Default	Description
`prompt`	string	Yes	—	Natural language description of the work to perform. Max 10,000 characters.
`user_id`	string	No	`null`	The end-user this task is for. Required for tasks that touch user-specific services.
`metadata`	object	No	`{}`	Arbitrary key-value pairs. Handy for correlating tasks with your own records.
`mode`	string	No	`"live"`	Set to `"test"` to validate the prompt and preview tool selection without actually executing.

Example request

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Pull all contacts from user_123'\''s CRM account created in the last 30 days. Return name, email, and company.",
    "user_id": "user_123",
    "metadata": {
      "source": "lead_enrichment_pipeline"
    }
  }'

Example response

{
  "id": "task_8xK2mP",
  "status": "running",
  "tool": "crm",
  "created_at": "2025-06-15T14:22:00Z",
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Error responses

Status	Code	Cause
`400`	`invalid_request`	Missing `prompt` field or invalid JSON
`401`	`invalid_api_key`	Bad or revoked API key
`422`	`prompt_too_long`	Prompt exceeds 10,000 characters
`429`	`rate_limit_exceeded`	Too many requests — check `Retry-After` header

Get a task

GET /v1/tasks/:task_id

Returns a task by ID. Includes the result if the task is done, or the error if it failed.

Path parameters

Parameter	Type	Description
`task_id`	string	The task ID (e.g., `task_8xK2mP`)

Example request

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

Example response (complete)

{
  "id": "task_8xK2mP",
  "status": "complete",
  "tool": "crm",
  "created_at": "2025-06-15T14:22:00Z",
  "completed_at": "2025-06-15T14:22:07Z",
  "result": {
    "contacts": [
      {
        "name": "Jane Smith",
        "email": "[email protected]",
        "company": "Acme Corp"
      },
      {
        "name": "Bob Chen",
        "email": "[email protected]",
        "company": "Globex Inc"
      }
    ]
  },
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Example response (failed)

{
  "id": "task_8xK2mP",
  "status": "failed",
  "tool": "crm",
  "created_at": "2025-06-15T14:22:00Z",
  "failed_at": "2025-06-15T14:22:04Z",
  "error": {
    "code": "auth_token_expired",
    "message": "The user's OAuth token has expired and automatic refresh failed.",
    "recoverable": true,
    "suggestion": "Prompt the user to re-authorize access"
  },
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Error responses

Status	Code	Cause
`401`	`invalid_api_key`	Bad or revoked API key
`404`	`task_not_found`	No task exists with this ID

List tasks

GET /v1/tasks

Returns tasks, paginated.

Query parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `pending`, `running`, `complete`, `failed`, `waiting`, `cancelled`
`user_id`	string	—	Filter by end-user ID
`limit`	integer	20	Items per page (max 100)
`offset`	integer	0	Number of items to skip

Example request

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

Example response

{
  "data": [
    {
      "id": "task_8xK2mP",
      "status": "complete",
      "tool": "crm",
      "created_at": "2025-06-15T14:22:00Z",
      "completed_at": "2025-06-15T14:22:07Z"
    },
    {
      "id": "task_3nL7pR",
      "status": "complete",
      "tool": "payments",
      "created_at": "2025-06-15T13:10:00Z",
      "completed_at": "2025-06-15T13:10:12Z"
    }
  ],
  "has_more": true
}

List responses omit result and error. Hit GET /v1/tasks/:task_id for the full object.

Cancel a task

POST /v1/tasks/:task_id/cancel

Cancels a pending, running, or waiting task. Returns 409 if the task already finished or failed.

Path parameters

Parameter	Type	Description
`task_id`	string	The task ID to cancel

Example request

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

Example response

{
  "id": "task_8xK2mP",
  "status": "cancelled",
  "cancelled_at": "2025-06-15T14:22:05Z"
}

Error responses

Status	Code	Cause
`401`	`invalid_api_key`	Bad or revoked API key
`404`	`task_not_found`	No task exists with this ID
`409`	`task_already_complete`	Task has already completed, failed, or been cancelled

Get a task trace

GET /v1/tasks/:task_id/trace

Returns the step-by-step execution trace for a task: what ran, in what order, and how long each step took.

Example request

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

Example response

{
  "task_id": "task_8xK2mP",
  "steps": [
    {
      "tool": "crm",
      "action": "authenticate",
      "status": "complete",
      "duration_ms": 120
    },
    {
      "tool": "crm",
      "action": "fetch_contacts",
      "status": "complete",
      "duration_ms": 890,
      "note": "Filtered to last 30 days, 47 contacts returned"
    },
    {
      "tool": "crm",
      "action": "format_response",
      "status": "complete",
      "duration_ms": 15
    }
  ],
  "total_duration_ms": 1025
}

Use traces to debug failures or find where time is going.

Next steps

Webhooks — Event types and payload reference
API Overview — Rate limits, error codes, pagination