This guide explains how to launch, monitor, filter, sort, and retrieve results from your runs using the Captain Data API.

​
Launching a Run

  • Use the API to start a new run by calling the appropriate action endpoint (e.g., /v4/api/actions/{action-name}/async) with your desired parameters.
  • Choose between execution modes: live (synchronous), async (asynchronous), or schedule (scheduled/CRON).

Implementation differences:

  • In live mode, use the input field to send a single input at a time (one by one).
  • In async and schedule modes, use the inputs field to send up to 100,000 inputs in a single request.

​
Monitoring and Managing Runs

As of July 2025, there is no dashboard to view runs—you must use the API for all management tasks.

​
Listing Runs

  • Use GET /v4/api/runs/list to retrieve a list of runs.
  • You can filter runs by:
    • status (e.g., SUCCEEDED, FAILED, etc.)
    • action_name (filter by specific action)
    • execution_mode (LIVE or ASYNC)
    • uid, user_uid (workspace member that triggered the Run), workspace_uid (filter by unique identifiers)
  • Pagination is supported via limit (default: 10, max: 100) and offset (default: 0).
  • Sorting is available using the sort parameter. Prefix a field with - for descending order (e.g., -created_at). You can sort by fields like created_at, status, or updated_at.

​
Example: List all async runs that succeeded

curl -X GET "https://api.captaindata.co/v4/api/runs/list?execution_mode=ASYNC&status=SUCCEEDED" \
  -H "X-API-Key: <YOUR_API_KEY>"

​
Example: List the 20 most recent runs (sorted by creation date, descending)

curl -X GET "https://api.captaindata.co/v4/api/runs/list?limit=20&sort=-created_at" \
  -H "X-API-Key: <YOUR_API_KEY>"

​
Getting a Specific Run

  • Use GET /v4/api/runs/get with the run UID to fetch detailed information about a specific run, including its status, execution mode, timestamps, and any errors.
curl -X GET "https://api.captaindata.co/v4/api/runs/get?uid={run_uid}" \
  -H "X-API-Key: <YOUR_API_KEY>"

​
Resuming a Run

curl -X POST "https://api.captaindata.co/v4/api/runs/{run_uid}/resume" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    // any required parameters
  }'

​
Status Lifecycle

Async and scheduled runs progress through a series of statuses, see below for details:

  • 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.

Monitoring these statuses helps you track the state of your jobs.

  • For async runs, monitor status via the API or receive updates via your webhook.
  • For scheduled runs, use the schedules list endpoint to track and manage jobs.

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