Tasks

Endpoints for creating, retrieving, updating, and deleting scheduled tasks, plus viewing task execution events.

Get Tasks

Retrieve scheduled tasks for the authenticated user's agent. Returns active tasks with their recent execution history.

POST /api/v1/tasks/get | GET /api/v1/tasks/get

Auth: API Key

POST Examples

# Get all active tasks
curl -X POST https://api.droyd.ai/api/v1/tasks/get \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Filter by Task Type:

curl -X POST https://api.droyd.ai/api/v1/tasks/get \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_types": "trading",
    "limit": 10
  }'

GET Examples

# Get all active tasks
curl -X GET "https://api.droyd.ai/api/v1/tasks/get" \
  -H "x-droyd-api-key: YOUR_API_KEY"
 
# Filter by task type
curl -X GET "https://api.droyd.ai/api/v1/tasks/get?task_types=general&limit=10" \
  -H "x-droyd-api-key: YOUR_API_KEY"
 
# Get specific tasks by ID
curl -X GET "https://api.droyd.ai/api/v1/tasks/get?ids=123,456" \
  -H "x-droyd-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "scheduled_task_id": 123,
      "task_title": "Daily DeFi Research",
      "status": "active",
      "action_type": "research",
      "instructions": "Research the latest DeFi trends on Solana",
      "cron_string": "30 9 * * *",
      "notification_destinations": [],
      "default_strategy_legs": null,
      "portfolio_budget_percent": null,
      "recent_tasks": [
        {
          "completed_at": "2025-01-15T09:35:00Z",
          "task_title": "Daily DeFi Research",
          "result_summary": "Found 5 trending protocols..."
        }
      ]
    }
  ]
}

Request Parameters (POST)

Parameter	Type	Required	Default	Description
`task_types`	string	No	`all`	Filter by task type: `all`, `general`, or `trading`
`scheduled_task_ids`	number[]	No	-	Fetch specific tasks by their IDs
`limit`	number	No	`50`	Maximum number of tasks to return (1-100)

Query Parameters (GET)

Parameter	Maps To	Description
`task_types`	`task_types`	Task type filter: `all`, `general`, or `trading`
`ids`	`scheduled_task_ids`	Comma-separated task IDs
`limit`	`limit`	Results limit

Notes

Only returns active tasks
general maps to research-type tasks internally

Create Task

Create a new scheduled task with a cron schedule. The task will be automatically executed by the agent at the specified schedule.

POST /api/v1/tasks/create

Auth: API Key

Examples

Research Task:

curl -X POST https://api.droyd.ai/api/v1/tasks/create \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_title": "Daily DeFi Research",
    "instructions": "Research the latest DeFi trends on Solana. Focus on new protocols, TVL changes, and notable developments.",
    "cron_string": "30 9 * * *",
    "action_type": "research"
  }'

Trading Task (with defaults):

curl -X POST https://api.droyd.ai/api/v1/tasks/create \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_title": "Weekly Trading Scan",
    "cron_string": "0 12 * * 1,3,5",
    "action_type": "trading",
    "portfolio_budget_percent": 0.05
  }'

Response

{
  "success": true,
  "data": {
    "scheduled_task_id": 123,
    "owner_id": 1,
    "agent_id": 5,
    "task_title": "Daily DeFi Research",
    "action_type": "research",
    "instructions": "Research the latest DeFi trends...",
    "status": "active",
    "cron_string": "30 9 * * *",
    "schedule_id": "sched_abc123"
  }
}

Request Parameters

Parameter	Type	Required	Default	Description
`task_title`	string	Yes	-	Task title (1-200 characters)
`instructions`	string	Conditional	-	Task instructions (1-5000 chars). Required for research tasks, optional for trading (defaults applied)
`cron_string`	string	Yes	-	Cron schedule expression (e.g. `"30 9 * * *"` for daily at 9:30 UTC)
`action_type`	string	No	`research`	Task type: `research` or `trading`
`notification_destinations`	string[]	No	`[]`	Notification channels
`portfolio_budget_percent`	number	No	-	Portfolio budget allocation for trading tasks (0-1)
`default_strategy_legs`	object	No	-	Default trading strategy legs for trading tasks

Notes

Task creation is subject to plan limits (e.g. free: 1, pro: 10 active tasks)
Returns 403 if the scheduled task limit for your plan is reached
The cron schedule is automatically registered — tasks will begin executing at the next scheduled time
For trading tasks, if instructions or default_strategy_legs are not provided, system defaults are applied automatically

Update Task

Update properties of an existing scheduled task. Supports updating instructions, schedule, status, and other configuration.

POST /api/v1/tasks/update

Auth: API Key

Examples

Update Instructions:

curl -X POST https://api.droyd.ai/api/v1/tasks/update \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_task_id": 123,
    "patch": {
      "instructions": "Research DeFi trends on Solana and Base. Include TVL data and new protocol launches."
    }
  }'

Change Schedule:

curl -X POST https://api.droyd.ai/api/v1/tasks/update \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_task_id": 123,
    "patch": {
      "cron_string": "0 14 * * 1,3,5"
    }
  }'

Pause a Task:

curl -X POST https://api.droyd.ai/api/v1/tasks/update \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_task_id": 123,
    "patch": {
      "status": "paused"
    }
  }'

Resume a Task:

curl -X POST https://api.droyd.ai/api/v1/tasks/update \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_task_id": 123,
    "patch": {
      "status": "active"
    }
  }'

Response

{
  "success": true,
  "data": {
    "scheduled_task_id": 123,
    "task_title": "Daily DeFi Research",
    "status": "active",
    "cron_string": "0 14 * * 1,3,5"
  }
}

Request Parameters

Parameter	Type	Required	Description
`scheduled_task_id`	number	Yes	ID of the task to update
`patch`	object	Yes	Object with fields to update (at least one required)

Patch Fields

Field	Type	Description
`task_title`	string	Task title (1-200 characters)
`instructions`	string	Task instructions (1-5000 characters)
`status`	string	`active` or `paused`
`action_type`	string	`research` or `trading`
`cron_string`	string	New cron schedule expression
`notification_destinations`	string[]	Notification channels
`portfolio_budget_percent`	number	Portfolio budget (0-1)
`default_strategy_legs`	object	Trading strategy legs

Notes

Changing cron_string automatically updates the schedule
Pausing a task removes its schedule; resuming recreates it
Returns 404 if the task doesn't exist or doesn't belong to your agent

Delete Task

Soft-delete a scheduled task. The task is marked as cancelled and its schedule is removed.

POST /api/v1/tasks/delete

Auth: API Key

Example

curl -X POST https://api.droyd.ai/api/v1/tasks/delete \
  -H "x-droyd-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_task_id": 123
  }'

Response

{
  "success": true
}

Request Parameters

Parameter	Type	Required	Description
`scheduled_task_id`	number	Yes	ID of the task to delete

Notes

Performs a soft delete (sets status to cancelled)
Automatically removes the associated schedule
Returns 404 if the task doesn't exist or doesn't belong to your agent

Task Events

Retrieve execution events for a specific task run.

GET /api/v1/agent/task/events

Auth: API Key

Example

curl -X GET "https://api.droyd.ai/api/v1/agent/task/events?run_id=abc-123-def" \
  -H "x-droyd-api-key: YOUR_API_KEY"