Managing Schedules

This guide explains how to create, list, retrieve, update, pause, resume, and delete schedules using the Captain Data API.

​

Creating a Schedule

• Use the API to schedule an action by calling the appropriate action’s /schedule endpoint (e.g., /v4/api/actions/{action-name}/schedule).
• You can schedule a one-time run in the future, or set up a recurring schedule using a cron expression.

Parameters:

• inputs: The inputs for your action (array).
• callback: Object with a url (required) to receive results.
• cron: (optional) POSIX cron expression for recurring schedules.
• schedule_at: (optional) ISO8601 date-time for a one-shot schedule.
• timezone: (optional) IANA timezone string (e.g., “Europe/Paris”).

​

Example: Create a recurring schedule

curl -X POST "https://api.captaindata.co/v4/api/actions/{action-name}/schedule" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [ ... ],
    "callback": { "url": "https://yourdomain.com/callback" },
    "cron": "0 8 * * 1",  // Every Monday at 8am
    "timezone": "Europe/Paris"
  }'

​

Example: Create a one-time schedule

curl -X POST "https://api.captaindata.co/v4/api/actions/{action-name}/schedule" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [ ... ],
    "callback": { "url": "https://yourdomain.com/callback" },
    "schedule_at": "2024-07-01T10:00:00Z"
  }'

​

Creating CRON Expressions

A CRON expression is a string used to define the schedule for recurring jobs. It consists of five fields separated by spaces, representing:

1. Minute (0-59)
2. Hour (0-23)
3. Day of month (1-31)
4. Month (1-12)
5. Day of week (0-6, where 0 = Sunday)

Examples:

• 0 9 * * 1-5 — Every weekday (Monday to Friday) at 9:00 AM
• 30 2 * * * — Every day at 2:30 AM
• 0 0 1 * * — On the first day of every month at midnight
• */15 * * * * — Every 15 minutes

You can use online tools like crontab.guru to build and test your CRON expressions.

​

Listing Schedules

• Use GET /v4/api/schedules to retrieve all schedules.
• You can filter by status, action_name, user_uid, workspace_uid, and more. Pagination is supported via limit and offset. Sorting is available using the sort parameter (prefix with - for descending order).

​

Example: List all active schedules for a workspace

curl -X GET "https://api.captaindata.co/v4/api/schedules?status=ACTIVE&workspace_uid=<WORKSPACE_UID>&limit=20&sort=-next_execution_at" \
  -H "X-API-Key: <YOUR_API_KEY>"

​

Getting a Specific Schedule

• Use GET /v4/api/schedules/{schedule_uid} with the schedule UID to fetch details.

​

Example: Get a schedule by UID

curl -X GET "https://api.captaindata.co/v4/api/schedules/{schedule_uid}" \
  -H "X-API-Key: <YOUR_API_KEY>"

​

Managing a Schedule (Pause, Resume, Cancel)

• Use POST /v4/api/schedules/{schedule_uid}/{action} to update a schedule’s status.
• Actions: pause, resume, cancel.

​

Example: Pause a schedule

curl -X POST "https://api.captaindata.co/v4/api/schedules/{schedule_uid}/pause" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

​

Example: Resume a schedule

curl -X POST "https://api.captaindata.co/v4/api/schedules/{schedule_uid}/resume" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

​

Example: Cancel (delete) a schedule

curl -X POST "https://api.captaindata.co/v4/api/schedules/{schedule_uid}/cancel" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

​

Updating a Schedule

• To update timing or inputs, cancel the existing schedule and create a new one with the desired parameters.

See the API Reference for detailed endpoint usage, parameters, and more examples.