Overview of Execution Modes

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

Here is a quick overview of each mode to help you decide which one fits your needs:

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

For detailed pagination handling, see the Pagination Guide. To learn more about managing runs and schedules, see the following sections.

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 because the input is invalid (bad input). For example, certain URLs like https://www.linkedin.com/products/... do not correspond to a valid LinkedIn company page. The callback itself is processed correctly, but the input cannot be processed.
STOPPED: The run was stopped before completion (manually or by the system).
RUNNING: The run is currently in progress.
FAILED: The run has failed. This can occur when the input seems correct, but during processing in the callback, it returns a failed status with an error (e.g., 424 – No results). In this case, the callback itself was processed correctly, even if the page doesn’t exist or returns nothing.
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 cursor and response headers
Real-time processing - fastest time to first result
Rate limit handling - you implement retry logic for 429 Too Many Requests responses
Your pacing at scale - live calls hit LinkedIn directly without async/schedule orchestration; follow Live mode: safe practices for spacing, sequencing, and jitter

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
Automatic retries - transient errors are retried (see below)

Async and schedule runs automatically retry on transient errors. Each run may be attempted up to 11 times in total (initial attempt + 10 retries).

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.

Prefer polling over callbacks? You can retrieve outputs directly via GET /runs/{run_uid}/outputs without setting up a webhook endpoint. See Rate Limits for polling limits.

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

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

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.

To learn more about callbacks, please take a look at Managing Callbacks.

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.
Get run status	`GET`	`/v1/runs/{run_uid}/status`	Lightweight status check for a run without fetching full details.
Get run inputs	`GET`	`/v1/runs/{run_uid}/inputs`	Retrieve all inputs for a run with their status and errors. Includes failed inputs that aren’t available in outputs.
Get run outputs	`GET`	`/v1/runs/{run_uid}/outputs`	Poll for run outputs without using callbacks. Supports cursor-based pagination via `X-Pagination-Next`.
Resume a run	`POST`	`/v1/runs/{run_uid}/resume`	Resume a paused or stopped run.
Continue a run	`POST`	`/v1/runs/{run_uid}/continue`	Continue an `incremental` sync run to fetch new data since the last retrieval.
Cancel a run	`POST`	`/v1/runs/{run_uid}/cancel`	Stop an async/schedule run. Already processed results remain available.

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 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
Automatic retries - same retry behavior as async mode

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)

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
*/30 * * * * — Every 30 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:

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.

Incremental Sync Mode

Both Async and Schedule modes support an optional incremental sync mechanism. Instead of retrieving the full dataset on every run, you can set sync_mode: "incremental" inside the parameters object to fetch only new data since the last retrieval.

Incremental sync is only available on engagement-free actions and requires an Engagement Identity (type: "engagement"). Standard identities cannot use this feature.

How It Works

First run (initial full sync): When sync_mode is set to incremental and no previous data has been retrieved, the system performs a full sync limited by max_results (either the value you set or the action’s default).
Subsequent runs (incremental): Once a first retrieval has been completed, the next runs automatically switch to incremental mode and return only newly available data.

With each continue or scheduled iteration, the system fetches up to max_results new items. If more new items were created than the max_results limit between two iterations, items beyond that limit will be lost and cannot be recovered.This happens because data is always fetched from the most recent to the oldest.To minimize this risk, choose a max_results value and schedule frequency that match your expected data volume.

Using Incremental Sync with Async Mode

In async mode, you trigger incremental updates manually by continuing a completed run:

curl -X POST "https://api.edges.run/v1/runs/{run_uid}/continue" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Each call to POST /v1/runs/{run_uid}/continue resets the run and fetches up to max_results new items.

Example: Async Incremental Sync

# 1. Launch an async run with incremental sync
curl -X POST "https://api.edges.run/v1/actions/linkedin-extract-connections/run/async" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "linkedin_url": "https://linkedin.com/in/johndoe" }],
    "callback": { "url": "https://yourdomain.com/callback" },
    "parameters": {
      "sync_mode": "incremental"
    }
  }'

# Returned body
{
  "run_id":xxxxxxxx,
  "run_uid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx", (use this one)
...
  "action_name":"linkedin-extract-connections",
  "status":"SCHEDULED"
}

# 2. Once the run completes, continue it later to get new data
curl -X POST "https://api.edges.run/v1/runs/{run_uid}/continue" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

Using Incremental Sync with Schedule Mode

In schedule mode, incremental sync is automatic: each scheduled iteration fetches only the new data since the last execution. No manual continue call is needed.

In scheduled mode, if the previous run is still in progress when the next iteration is triggered, that iteration will be skipped. The following iteration will trigger the update instead.

Example: Scheduled Incremental Sync

# Schedule a recurring incremental sync every day at 9am
curl -X POST "https://api.edges.run/v1/actions/linkedin-extract-messages/run/schedule" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{ "conversation_id": "..." }],
    "callback": { "url": "https://yourdomain.com/callback" },
    "cron": "0 9 * * *",
    "timezone": "Europe/Paris",
    "parameters": {
      "sync_mode": "incremental"
    }
  }'

Supported Actions

The following actions currently support incremental sync:

Action	Description
`linkedin-extract-connections`	Extract LinkedIn connections
`linkedin-extract-messages`	Extract LinkedIn messages
`linkedin-extract-profile-viewers`	Extract profile viewers
`linkedin-extract-page-followers`	Extract LinkedIn page followers

Continuable Run Statuses

A run can only be continued if its status is one of:

BLOCKED
STOPPED
FAILED
PARTIAL_SUCCEEDED
SUCCEEDED

When continued, the run status and all related inputs are reset to SCHEDULED.

Limitations

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

Getting Started

Essentials

Build with Edges

Overview of Execution Modes

Execution Statuses

Live Mode

Async Mode

Callbacks Structure

Available Endpoints for Runs

Schedule Mode

Understanding CRON Expressions

Available Endpoints for Schedules

Incremental Sync Mode

How It Works

Using Incremental Sync with Async Mode

Example: Async Incremental Sync

Using Incremental Sync with Schedule Mode

Example: Scheduled Incremental Sync

Supported Actions

Continuable Run Statuses

Limitations

Quick Decision Guide

​Execution Statuses

​Live Mode

​Async Mode

​Callbacks Structure

​Available Endpoints for Runs

​Schedule Mode

​Understanding CRON Expressions

​Available Endpoints for Schedules

​Incremental Sync Mode

​How It Works

​Using Incremental Sync with Async Mode

​Example: Async Incremental Sync

​Using Incremental Sync with Schedule Mode

​Example: Scheduled Incremental Sync

​Supported Actions

​Continuable Run Statuses

​Limitations

​Quick Decision Guide

Execution Statuses

Live Mode

Async Mode

Callbacks Structure

Available Endpoints for Runs

Schedule Mode

Understanding CRON Expressions

Available Endpoints for Schedules

Incremental Sync Mode

How It Works

Using Incremental Sync with Async Mode

Example: Async Incremental Sync

Using Incremental Sync with Schedule Mode

Example: Scheduled Incremental Sync

Supported Actions

Continuable Run Statuses

Limitations

Quick Decision Guide