Captain Data supports multiple ways to execute actions and workflows, including synchronous runs, asynchronous runs, and scheduled executions. This section explains the different execution modes and how to choose the right one for your use case.

  • Synchronous Runs: Immediate execution, results returned in real-time.
  • Asynchronous Runs: Execution happens in the background, results can be fetched later.
  • Scheduled Runs: Actions are scheduled to run at a specific time or on a recurring basis.

Learn more in the following pages about managing runs and schedules.

​
Execution Statuses

When running actions in async or schedule mode, the following statuses may be encountered:

  • CREATED: The run or schedule has been created but not yet queued for execution.
  • INVALID: The run or schedule is invalid (e.g., due to bad input or configuration).
  • QUEUED: The run is waiting in the queue to be executed.
  • SCHEDULED: The run is scheduled to execute at a future time (applies to scheduled/CRON jobs).
  • BLOCKED: The run is blocked, usually due to dependencies or resource limits.
  • STOPPED: The run was stopped before completion (manually or by the system).
  • RUNNING: The run is currently in progress.
  • FAILED: The run has failed.
  • PARTIAL_SUCCEEDED: The run completed with some errors, but partial results are available.
  • SUCCEEDED: The run completed successfully.

​
Live Mode

You receive data immediately as it is processed, making this the easiest mode to implement for quick integrations.

However, if you reach a limit or receive a 429 Too Many Requests response, you will need to implement your own retry logic to handle rate limiting and continue fetching results.

When using live (synchronous) mode, you are responsible for implementing pagination in your integration. The API will return results in pages, and you must request subsequent pages as needed.

For async and schedule modes, Captain Data automatically handles pagination for you. Results are distributed as soon as possible via the callback or are available incrementally, not just at the end of the run.

​
Async Mode

  • When you run an action asynchronously e.g., Extract LinkedIn People Async, the execution happens in the background.
  • You receive a callback on a defined webhook URL once the run is complete.
  • The callback payload includes the results field, which contains the data you requested.
  • This allows you to integrate the results directly into your system without polling.

​
Callbacks Structure

Callback Delivery: Both async and schedule modes deliver results via the callback URL provided in your request.

Consistent Format: All execution modes use the same action logic, so inputs and results are identical regardless of mode.

Error Handling: Errors follow the standard API error format.

async callback format
{
  "run": {
    "run_uid": "string",
    "batch_uid": "string",
    "status": "CREATED" || "INVALID" || "QUEUED" || "SCHEDULED" || "BLOCKED" || "STOPPED" || "RUNNING" || "FAILED" || "PARTIAL_SUCCEEDED" || "SUCCEEDED",
  },
  "input": {} || null,
  "error": {} || null,
  "results": [] || null
}

​
Available Endpoints for Runs

You can manage and monitor your runs using the following endpoints:

ActionMethodEndpointDescription
List all runsGET/v4/api/runs/listRetrieve a list of all runs, with filtering and pagination options.
Get a runGET/v4/api/runs/getFetch detailed information and status for a specific run using its unique identifier.
Resume a runPOST/v4/api/runs/manageResume a paused or stopped run. Provide the run UID and the desired action (e.g., resume).
Refer to the API Reference for request/response details and usage examples for each endpoint.

​
Schedule Mode

  • When you run an action in schedule mode, a CRON-job is created.
  • The job will execute at the defined schedule e.g., daily, weekly, custom CRON expression.
  • You can monitor and manage scheduled jobs using the List all Schedules endpoint.
  • Each scheduled run will also follow the status lifecycle described above.

​
Understanding 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.

​
Available Endpoints for Schedules

You can manage and monitor your schedules using the following endpoints:

ActionMethodEndpointDescription
List all schedulesGET/v4/api/schedules/listRetrieve a list of all schedules, with filtering and pagination options.
Get a scheduleGET/v4/api/schedules/getFetch detailed information and status for a specific schedule using its unique identifier.
Manage a schedulePOST/v4/api/schedules/manageUpdate, pause, resume, or delete a schedule. Provide the schedule UID and the desired action.
Refer to the API Reference for request/response details and usage examples for each endpoint.