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/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/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/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/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/schedules?status=ACTIVE&workspace_uid=<WORKSPACE_UID>&limit=20&sort=-next_execution_at" \
  -H "X-API-Key: <YOUR_API_KEY>"
When using the sandbox, the workspace UID will be different from your main workspace.

​
Getting a Specific Schedule

​
Example: Get a schedule by UID

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

​
Managing a Schedule (Pause, Resume, Cancel)

​
Example: Pause a schedule

curl -X POST "https://api.captaindata.co/v4/schedules/{scheduled_run_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/schedules/{scheduled_run_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/schedules/{scheduled_run_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.