Captain Data offers three ways to execute actions or workflows via API.
Each suits a different use case:
🔹 1. Live Mode (Synchronous)
When to use it: You want results instantly, in real-time.
What to expect: You’ll receive paginated data immediately.
Heads up: You’ll need to handle rate limiting (429 errors) and pagination yourself.
🔹 2. Async Mode (Asynchronous)
When to use it: You don’t need instant results and prefer background processing.
What to expect: We’ll send a callback to your webhook when the run completes.
Bonus: We handle pagination for you. The results are included in the callback payload.
🔹 3. Schedule Mode (CRON)
When to use it: You want to automate recurring jobs (e.g., daily, weekly).
What to expect: Runs are triggered based on your CRON expression. Results are sent to your webhook just like async mode.
🌀 Run Lifecycle: What Happens After Launch
Runs (especially async and scheduled) go through different statuses:
CREATED → Not yet in queue
QUEUED → Waiting to run
RUNNING → In progress
SUCCEEDED → All good ✅
FAILED, BLOCKED, or STOPPED → Something went wrong 🚫
PARTIAL_SUCCEEDED → Mixed results; some data is available
Use this info to track progress and build custom logic.
🛠 Key Endpoints
Here are the most common endpoints you’ll use to manage runs:
Action | Method | Endpoint |
List all runs | GET | /v4/api/runs/list |
Get a run’s details | GET | /v4/api/runs/get?uid=... |
Resume a run | POST | /v4/api/runs/{run_uid}/resume |
For scheduled runs:
Action | Method | Endpoint |
List all schedules | GET | /v4/api/schedules/list |
Get a schedule | GET | /v4/api/schedules/get?uid=... |
Manage (pause/resume) | POST | /v4/api/schedules/manage |
📩 Callback Format (Async / Scheduled)
You’ll receive a callback like this when a run is done:
{
"run": {
"run_uid": "string",
"status": "SUCCEEDED" // or FAILED, etc.
},
"results": [],
"error": null
}Same format every time. Simple and predictable.
🧠 CRON Tips
Want to run something every day at 2:30 AM?
30 2 * * *
Use crontab.guru to build expressions.
📚 Need More Details?
Check out the full guide here: docs.captaindata.com/v4/runs/overview