Scheduled Tasks API

The Scheduled Tasks API allows you to manage tasks that are scheduled to run at specific times or intervals. You can create, update, and delete scheduled tasks, as well as view their execution history.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

Scheduled Tasks in Kubiya allow you to automate the execution of agents on a defined schedule. This API enables you to create, manage, and monitor scheduled tasks that run automatically at specified intervals.

Endpoints

Method	Path	Description
GET	`/api/v1/scheduled_tasks`	List all scheduled tasks
GET	`/api/v1/scheduled_tasks/{taskId}`	Get scheduled task details
POST	`/api/v1/scheduled_tasks`	Create a new scheduled task
PUT	`/api/v1/scheduled_tasks/{taskId}`	Update a scheduled task
DELETE	`/api/v1/scheduled_tasks/{taskId}`	Delete a scheduled task

List Scheduled Tasks

Retrieve all scheduled tasks in your organization.

GET `/api/v1/scheduled_tasks`

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "task-12345",
    "name": "daily-backup-check",
    "description": "Verify backup completion daily",
    "agent": "backup-agent",
    "schedule": "0 9 * * *",
    "prompt": "Check if all daily backups completed successfully",
    "enabled": true,
    "last_run": "2024-03-20T09:00:00Z",
    "next_run": "2024-03-21T09:00:00Z",
    "status": "active",
    "notification": {
      "method": "Slack",
      "destination": "#backups"
    }
  }
]

Get Scheduled Task Details

Retrieve details about a specific scheduled task.

GET `/api/v1/scheduled_tasks/{taskId}`

Path Parameters

Name	Type	Required	Description
`taskId`	string	Yes	ID of the scheduled task

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "task-12345",
  "name": "daily-backup-check",
  "description": "Verify backup completion daily",
  "agent": "backup-agent",
  "schedule": "0 9 * * *",
  "prompt": "Check if all daily backups completed successfully",
  "enabled": true,
  "last_run": "2024-03-20T09:00:00Z",
  "next_run": "2024-03-21T09:00:00Z",
  "status": "active",
  "notification": {
    "method": "Slack",
    "destination": "#backups"
  },
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2024-03-15T14:30:00Z",
  "execution_history": [
    {
      "timestamp": "2024-03-20T09:00:00Z",
      "status": "completed",
      "duration": "45s"
    }
  ]
}

Create Scheduled Task

Create a new scheduled task.

POST `/api/v1/scheduled_tasks`

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "name": "daily-backup-check",
  "description": "Verify backup completion daily",
  "agent": "backup-agent",
  "schedule": "0 9 * * *",
  "prompt": "Check if all daily backups completed successfully",
  "enabled": true,
  "notification": {
    "method": "Slack",
    "destination": "#backups"
  }
}

Response

{
  "id": "task-12345",
  "name": "daily-backup-check",
  "description": "Verify backup completion daily",
  "agent": "backup-agent",
  "schedule": "0 9 * * *",
  "prompt": "Check if all daily backups completed successfully",
  "enabled": true,
  "status": "active",
  "created_at": "2024-03-20T14:30:00Z",
  "next_run": "2024-03-21T09:00:00Z"
}

Update Scheduled Task

Update an existing scheduled task.

PUT `/api/v1/scheduled_tasks/{taskId}`

Path Parameters

Name	Type	Required	Description
`taskId`	string	Yes	ID of the scheduled task to update

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "name": "daily-backup-check",
  "description": "Updated backup verification task",
  "schedule": "0 10 * * *",
  "prompt": "Verify all daily backups and send detailed report",
  "enabled": true,
  "notification": {
    "method": "Slack",
    "destination": "#backups-alerts"
  }
}

Response

{
  "id": "task-12345",
  "name": "daily-backup-check",
  "description": "Updated backup verification task",
  "agent": "backup-agent",
  "schedule": "0 10 * * *",
  "prompt": "Verify all daily backups and send detailed report",
  "enabled": true,
  "status": "active",
  "updated_at": "2024-03-20T15:00:00Z",
  "next_run": "2024-03-21T10:00:00Z"
}

Delete Scheduled Task

Delete a scheduled task.

DELETE `/api/v1/scheduled_tasks/{taskId}`

Path Parameters

Name	Type	Required	Description
`taskId`	string	Yes	ID of the scheduled task to delete

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

A successful delete operation returns an HTTP 200 status with no response body.

Schedule Format

The schedule is specified using cron syntax with the following format:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Common examples:

0 9 * * * - Daily at 9 AM
0 9 * * MON-FRI - Weekdays at 9 AM
0 0 1 * * - Monthly on the 1st at midnight
*/15 * * * * - Every 15 minutes

Example Usage

# List all scheduled tasks
curl -X GET "https://api.kubiya.ai/api/v1/scheduled_tasks" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get scheduled task details
curl -X GET "https://api.kubiya.ai/api/v1/scheduled_tasks/task-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new scheduled task
curl -X POST "https://api.kubiya.ai/api/v1/scheduled_tasks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-backup-check",
    "description": "Verify backup completion daily",
    "agent": "backup-agent",
    "schedule": "0 9 * * *",
    "prompt": "Check if all daily backups completed successfully",
    "enabled": true,
    "notification": {
      "method": "Slack",
      "destination": "#backups"
    }
  }'
 
# Update a scheduled task
curl -X PUT "https://api.kubiya.ai/api/v1/scheduled_tasks/task-12345" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-backup-check",
    "description": "Updated backup verification task",
    "schedule": "0 10 * * *",
    "prompt": "Verify all daily backups and send detailed report",
    "enabled": true,
    "notification": {
      "method": "Slack",
      "destination": "#backups-alerts"
    }
  }'
 
# Delete a scheduled task
curl -X DELETE "https://api.kubiya.ai/api/v1/scheduled_tasks/task-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"

Scheduled tasks are executed automatically based on their defined schedule. Make sure to test your tasks thoroughly before enabling them in production.

Common Errors

HTTP Status	Description
400	Bad Request - Invalid schedule format or missing required fields
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to perform this action
404	Not Found - The specified scheduled task was not found
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up scheduled tasks, you can:

Monitor task execution through the Tasks API
Set up Webhooks to receive task execution notifications
Configure Agents to be used in scheduled tasks

Scheduled Tasks API

On this page