Skip to main content

​
Overview

Shannon supports recurring task execution using Temporal’s native Schedule API. Create cron-based schedules that automatically execute tasks at specified intervals.

​
Features

  • Cron-based scheduling with timezone support
  • Resource limits to prevent abuse
  • Budget control per execution
  • Execution history with cost tracking
  • Pause/Resume/Delete operations
  • Multi-tenant isolation with user/tenant ownership

​
Create Schedule

Create a new recurring task schedule. 
curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Daily summary",
    "description": "Generate daily activity summary",
    "cron_expression": "0 9 * * *",
    "timezone": "America/New_York",
    "task_query": "Summarize yesterday'\''s activity",
    "task_context": {
      "report_format": "markdown"
    },
    "max_budget_per_run_usd": 5.0,
    "timeout_seconds": 600
  }'

​
Request Body

FieldTypeRequiredDescription
namestringYesSchedule name (max 255 chars)
descriptionstringNoOptional description
cron_expressionstringYesCron schedule (5-field format)
timezonestringNoIANA timezone (default: UTC)
task_querystringYesQuery to execute
task_contextobjectNoAdditional context for the task
max_budget_per_run_usdnumberNoMax budget per execution (default: 10.0)
timeout_secondsintegerNoExecution timeout (default: 600)

​
Response

{
  "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Schedule created successfully",
  "next_run_at": "2025-12-16T09:00:00-05:00"
}

​
List Schedules

List schedules with pagination and filtering. 
curl "http://localhost:8080/api/v1/schedules?page=1&page_size=50&status=ACTIVE" \
  -H "Authorization: Bearer <token>"

​
Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number
page_sizeinteger50Items per page (max 100)
statusstring-Filter by status (ACTIVE, PAUSED)

​
Response

{
  "schedules": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Daily summary",
      "cron_expression": "0 9 * * *",
      "timezone": "America/New_York",
      "status": "ACTIVE",
      "next_run_at": "2025-12-16T09:00:00-05:00",
      "total_runs": 45,
      "successful_runs": 43,
      "failed_runs": 2
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

​
Get Schedule

Get details of a specific schedule. 
curl "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Authorization: Bearer <token>"

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Daily summary",
  "description": "Generate daily activity summary",
  "cron_expression": "0 9 * * *",
  "timezone": "America/New_York",
  "task_query": "Summarize yesterday's activity",
  "task_context": {"report_format": "markdown"},
  "max_budget_per_run_usd": 5.0,
  "timeout_seconds": 600,
  "status": "ACTIVE",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z",
  "next_run_at": "2025-01-16T09:00:00-05:00",
  "last_run_at": "2025-01-15T09:00:00-05:00",
  "total_runs": 45,
  "successful_runs": 43,
  "failed_runs": 2
}

​
Update Schedule

Update an existing schedule. 
curl -X PUT "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "cron_expression": "0 10 * * *",
    "max_budget_per_run_usd": 8.0
  }'

​
Request Body

All fields are optional. Only provided fields will be updated.
FieldTypeDescription
namestringNew schedule name
descriptionstringNew description
cron_expressionstringNew cron schedule
timezonestringNew timezone
task_querystringNew task query
task_contextobjectNew context
max_budget_per_run_usdnumberNew budget limit
timeout_secondsintegerNew timeout

​
Get Execution History

Get execution history for a schedule. 
curl "http://localhost:8080/api/v1/schedules/{id}/runs?page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

​
Response

{
  "runs": [
    {
      "id": "run-123",
      "schedule_id": "550e8400-e29b-41d4-a716-446655440000",
      "task_id": "task-dev-456",
      "status": "COMPLETED",
      "started_at": "2025-01-15T09:00:00Z",
      "completed_at": "2025-01-15T09:02:30Z",
      "duration_seconds": 150,
      "cost_usd": 0.45,
      "tokens_used": 12500
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20
}

​
Pause Schedule

Pause a schedule to stop future executions. 
curl -X POST "http://localhost:8080/api/v1/schedules/{id}/pause" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"reason": "Temporary maintenance"}'

​
Response

{
  "message": "Schedule paused successfully",
  "paused_at": "2025-01-15T10:00:00Z"
}

​
Resume Schedule

Resume a paused schedule. 
curl -X POST "http://localhost:8080/api/v1/schedules/{id}/resume" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"reason": "Maintenance complete"}'

​
Response

{
  "message": "Schedule resumed successfully",
  "next_run_at": "2025-01-16T09:00:00-05:00"
}

​
Delete Schedule

Delete a schedule permanently. 
curl -X DELETE "http://localhost:8080/api/v1/schedules/{id}" \
  -H "Authorization: Bearer <token>"

​
Response

{
  "message": "Schedule deleted successfully"
}

​
Cron Expression Format

Uses standard cron syntax (5 fields): 
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

​
Common Examples

ExpressionDescription
0 9 * * *Daily at 9:00 AM
0 */4 * * *Every 4 hours
0 0 * * 1Every Monday at midnight
30 8 1 * *First day of month at 8:30 AM
0 12 * * 1-5Weekdays at noon
0 0 1,15 * *1st and 15th of each month

​
Resource Limits

Shannon enforces resource limits to prevent abuse:
LimitDefaultEnvironment Variable
Max schedules per user50SCHEDULE_MAX_PER_USER
Minimum interval60 minutesSCHEDULE_MIN_INTERVAL_MINS
Max budget per run$10.00SCHEDULE_MAX_BUDGET_USD
Schedules that exceed budget limits will be paused automatically.

​
Error Responses

StatusErrorDescription
400Invalid cron expressionCron syntax error
400Interval too shortBelow minimum interval
403Schedule limit reachedMax schedules per user exceeded
404Schedule not foundInvalid schedule ID
409Schedule already pausedCannot pause paused schedule

​
Next Steps

Submit Tasks

One-time task submission

Temporal Workflows

Understand workflow execution