- 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.
Execution Mode | Data Delivery | When to Use |
---|---|---|
Live | Immediate (synchronous) | Real-time workflows, single inputs, few results |
Async | Background (via callback stream) | Batch jobs, large datasets, automated pagination |
Schedule | Recurring (via cron) or postponed | Scheduled runs, regular syncs, postponed execution |
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. Key characteristics:- Synchronous execution - results returned in the API response
- Manual pagination - you handle pagination using page parameters and headers
- Real-time processing - fastest time to first result
- Rate limit handling - you implement retry logic for
429 Too Many Requests
responses
Live mode is ideal for real-time workflows where you need immediate results and can handle pagination manually.
See the Pagination Guide for detailed pagination handling.
Async Mode
When you run an action asynchronously, the execution happens in the background and results are delivered via callbacks. Key characteristics:- Background execution - non-blocking, your application continues running
- Automatic pagination - Edges handles pagination internally
- Progressive delivery - results streamed via callbacks as they become available
- Callback-based - results delivered to your webhook URL
- Batch processing - ideal for large datasets and long-running tasks
Async mode is ideal for long-running tasks, batch processing, or when you want to avoid blocking your application while waiting for results.
Results are delivered progressively via multiple callbacks, allowing you to start processing data as soon as it becomes available.
You can attach any metadata to each input using the
custom_data
object. This data is sent in every callback, allowing you to
correlate results with your backend.- Each callback relates to a single input, so
custom_data
is included at the root level of the callback payload - Avoid sending large or nested structures: most use cases are covered with a single internal ID
- Keep the payload reasonably small to avoid hitting webhook size limits
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
To track or tag your inputs, you can attach any custom metadata to each input via the
custom_data
field. It is especially useful
in async
and schedule
modes to help you get context on the results.
This applies even when running with multiple inputs: each input will produce one or more callbacks, each carrying its own custom_data
.This object is then injected as-is at the root of every callback, allowing you to correlate each result with your own data or internal references.Available Endpoints for Runs
You can manage and monitor your runs using the following endpoints:Action | Method | Endpoint | Description |
---|---|---|---|
List all runs | GET | /v1/runs | Retrieve a list of all runs, with filtering and pagination options. |
Get a run | GET | /v1/runs/{run_uid} | Fetch detailed information and status for a specific run using its unique identifier. |
Resume a run | POST | /v1/runs/{run_uid}/resume | Resume 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 inschedule
mode, a CRON-job is created that executes at defined intervals.
Key characteristics:
- Scheduled execution - runs at defined times (daily, weekly, custom CRON expressions)
- Postponed execution - can delay execution to a specific time
- Automatic pagination - same as Async mode
- Callback-based - results delivered via callbacks like Async mode
- Recurring tasks - ideal for regular data syncs and automated workflows
Schedule mode is ideal for recurring tasks, regular data syncs, or when you want to automate actions at specific intervals
without implementing your own scheduling system.Results are delivered progressively exactly like in Async mode, via callbacks on the URL set in the
callback.url
parameter.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:- Minute (0-59)
- Hour (0-23)
- Day of month (1-31)
- Month (1-12)
- Day of week (0-6, where 0 = Sunday)
0 9 * * 1-5
— Every weekday (Monday to Friday) at 9:00 AM30 2 * * *
— Every day at 2:30 AM0 0 1 * *
— On the first day of every month at midnight*/30 * * * *
— Every 30 minutes
Available Endpoints for Schedules
You can manage and monitor your schedules using the following endpoints:Action | Method | Endpoint | Description |
---|---|---|---|
List all schedules | GET | /v1/schedules | Retrieve a list of all schedules, with filtering and pagination options. |
Get a schedule | GET | /v1/schedules/{scheduled_run_uid} | Fetch detailed information and status for a specific schedule using its unique identifier. |
Manage a schedule | POST | /v1/schedules/{scheduled_run_uid}/{action} | Update, 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.
Quick Decision Guide
- Live ⚡️ - Need results immediately and can handle pagination manually
- Async 📦 - Running batch jobs with automated pagination and callback delivery
- Schedule 🕒 - Need recurring or postponed execution with the same benefits as Async