Skip to Content
APISchedules API

Schedules API

Schedules enable automated task execution at specific times or intervals. Create one-time tasks or recurring schedules using cron expressions.

The Schedule Object

{
  "id": "sched_abc123",
  "userId": "user_xxx",
  "name": "Daily Cleanup",
  "description": "Clean temp files every morning",
  "task": "Delete all files in /tmp older than 24 hours",
  "agentId": "agent_xxx",
  "environmentId": "env_xxx",
  "scheduleType": "recurring",
  "cronExpression": "0 9 * * *",
  "timezone": "America/New_York",
  "enabled": true,
  "nextRunAt": "2025-01-16T09:00:00Z",
  "lastRunAt": "2025-01-15T09:00:00Z",
  "runCount": 15,
  "successCount": 14,
  "failureCount": 1,
  "createdAt": "2025-01-01T10:00:00Z",
  "updatedAt": "2025-01-15T09:00:00Z"
}

Attributes

AttributeTypeDescription
idstringUnique identifier (sched_*)
userIdstringOwner user ID
namestringSchedule name
descriptionstringOptional description
taskstringTask to execute
agentIdstringAgent to use
environmentIdstringEnvironment for execution
scheduleTypestringone-time or recurring
cronExpressionstringCron expression (recurring only)
scheduledTimestringISO timestamp (one-time only)
timezonestringTimezone for scheduling
enabledbooleanWhether schedule is active
nextRunAtstringNext scheduled execution
lastRunAtstringLast execution time
runCountnumberTotal executions
successCountnumberSuccessful executions
failureCountnumberFailed executions

Create Schedule

POST /v1/schedules

Request Body

ParameterTypeRequiredDescription
namestringYesSchedule name
taskstringYesTask to execute
scheduleTypestringYesone-time or recurring
cronExpressionstringFor recurringCron expression
scheduledTimestringFor one-timeISO 8601 timestamp
agentIdstringNoAgent to use
environmentIdstringNoEnvironment for execution
timezonestringNoTimezone (default: UTC)
enabledbooleanNoEnable immediately (default: true)
descriptionstringNoOptional description
metadataobjectNoCustom metadata

Example: Recurring Schedule

curl -X POST https://api.computer-agents.com/v1/schedules \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Report",
    "task": "Generate and email the daily metrics report",
    "scheduleType": "recurring",
    "cronExpression": "0 9 * * *",
    "timezone": "America/New_York",
    "agentId": "agent_xxx"
  }'

Example: One-Time Schedule

curl -X POST https://api.computer-agents.com/v1/schedules \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy to Production",
    "task": "Run deployment script for version 2.0",
    "scheduleType": "one-time",
    "scheduledTime": "2025-01-20T03:00:00Z"
  }'

Response

{
  "schedule": {
    "id": "sched_abc123",
    "name": "Daily Report",
    "scheduleType": "recurring",
    "cronExpression": "0 9 * * *",
    "timezone": "America/New_York",
    "enabled": true,
    "nextRunAt": "2025-01-16T14:00:00Z",
    "runCount": 0,
    "successCount": 0,
    "failureCount": 0,
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Cron Expression Guide

Cron expressions define when recurring schedules run:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common Examples

ExpressionDescription
0 9 * * *Every day at 9:00 AM
0 9 * * 1-5Weekdays at 9:00 AM
0 */2 * * *Every 2 hours
0 9 1 * *First day of each month at 9:00 AM
30 14 * * 0Sundays at 2:30 PM
0 0 * * *Midnight every day

All times are interpreted in the schedule’s timezone. Default is UTC.

List Schedules

GET /v1/schedules

Query Parameters

ParameterTypeDescription
agentIdstringFilter by agent
environmentIdstringFilter by environment
appIdstringFilter by app
scheduleTypestringone-time or recurring
enabledbooleanFilter by enabled status
limitnumberMax results
offsetnumberPagination offset

Example

curl "https://api.computer-agents.com/v1/schedules?enabled=true" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "sched_abc123",
      "name": "Daily Report",
      "scheduleType": "recurring",
      "enabled": true,
      "nextRunAt": "2025-01-16T14:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 5,
  "stats": {
    "total": 5,
    "enabled": 3,
    "disabled": 2
  }
}

Get Schedule

GET /v1/schedules/:id

Response

{
  "schedule": {
    "id": "sched_abc123",
    "name": "Daily Report",
    "task": "Generate and email the daily metrics report",
    "scheduleType": "recurring",
    "cronExpression": "0 9 * * *",
    "timezone": "America/New_York",
    "enabled": true,
    "nextRunAt": "2025-01-16T14:00:00Z",
    "lastRunAt": "2025-01-15T14:00:00Z",
    "runCount": 15,
    "successCount": 14,
    "failureCount": 1
  }
}

Update Schedule

PATCH /v1/schedules/:id

Request Body

ParameterTypeDescription
namestringNew name
taskstringNew task
cronExpressionstringNew cron expression
timezonestringNew timezone
enabledbooleanEnable/disable

Example

curl -X PATCH https://api.computer-agents.com/v1/schedules/sched_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cronExpression": "0 10 * * *"}'

Delete Schedule

DELETE /v1/schedules/:id

Example

curl -X DELETE https://api.computer-agents.com/v1/schedules/sched_abc123 \
  -H "Authorization: Bearer $API_KEY"

Trigger Schedule Manually

Run a schedule immediately, regardless of its next scheduled time.

POST /v1/schedules/:id/trigger

Example

curl -X POST https://api.computer-agents.com/v1/schedules/sched_abc123/trigger \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "thread": {
    "id": "thread_xxx",
    "status": "running"
  },
  "message": "Schedule triggered - execution started"
}

Enable/Disable Schedule

Enable

PATCH /v1/schedules/:id/enable

Disable

PATCH /v1/schedules/:id/disable

Response

{
  "schedule": {
    "id": "sched_abc123",
    "enabled": true
  }
}

Schedule via Thread Creation

You can also create schedules when creating threads:

curl -X POST https://api.computer-agents.com/v1/threads \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Run database backup" }],
    "schedule": {
      "type": "recurring",
      "name": "Nightly Backup",
      "cronExpression": "0 2 * * *"
    }
  }'

This creates both the thread and schedule in one request.

Errors

StatusErrorDescription
400Bad RequestInvalid cron expression or parameters
402Payment RequiredInsufficient budget for execution
404Not FoundSchedule not found
Last updated on
Files APIStreaming (SSE)