Callbacks

Overview

What callbacks are, streaming vs final delivery, and data completeness guarantees.

Payloads

Callback JSON structure, run vs callback statuses, custom_data, and examples.

Delivery

Idempotency, missed-callback detection, and replaying failed deliveries.

What are Callbacks?

Callbacks are the way Edges delivers results for async and schedule execution modes. Instead of waiting for the entire operation to complete, you receive results progressively as they become available.

When to use callbacks: Choose async or schedule mode when you need to process large datasets, want to consume data in parallel, or need to handle long-running operations without timeouts.

Callbacks are only useful if you can trust that all of them are received and processed. To ensure you never miss any data, see Managing Callbacks.

Understanding callback statuses is essential for handling callbacks correctly. Here are quick definitions:

PENDING: The callback is queued and waiting to be delivered to your webhook endpoint.
RUNNING: The callback has been sent to your endpoint and is being processed (or was successfully delivered).
FAILED: The callback delivery failed (e.g., network error, timeout, or your endpoint returned an error status code).
SUCCESS: The callback was successfully delivered to your endpoint and your endpoint returned a successful HTTP status code (2xx).

These are callback statuses that indicate the delivery status of the callback itself. They are different from run statuses (like BLOCKED, FAILED, SUCCEEDED) which indicate the execution state of the run. See Understanding Run Statuses vs Callback Statuses for more details.

Quick Start

1. Set up your webhook endpoint

Create an HTTPS endpoint that can receive POST requests with JSON payloads.

2. Configure your action call

Include a callback parameter with your webhook URL:

{
  "inputs": [...],
  "callback": {
    "url": "https://yourdomain.com/webhook",
    "headers": {
      "Authorization": "Bearer your_token"
    },
    "on": "all"
  }
}

Set "on": "final" instead of "all" if you only want to receive a single callback when the job completes. With "final" mode, the callback indicates the run status, and you then fetch results using GET /runs/{run_uid}/outputs. This is ideal for automation tools like n8n, Make, or Zapier. See Streaming vs Final Callbacks for details.

3. Handle incoming callbacks

For on: "all" mode: Process the JSON payloads as they arrive. Each callback contains results and metadata. Verify completeness by comparing the run output count with received results.
For on: "final" mode: Receive a single callback with run status, then fetch all results using GET /runs/{run_uid}/outputs.

For detailed setup and management, see the sections below.

Understanding Async and Schedule Modes

async and schedule execution modes are both async modes: the results are not sent immediately in the response payload but delivered during execution via callbacks.

schedule is built on top of async and only adds ways to postpone and schedule calls. Both modes share the same callback delivery mechanism. For a detailed comparison and guidance on when to use each mode, see When to use live, async or schedule modes..

Setting Up Callbacks

Every action call in async/schedule mode requires a callback parameter:

string

Your webhook URL that will receive the callback data. Must be HTTPS.

object

Optional headers for authentication or custom metadata (API keys, etc.).

string

default:"all"

Defines when you want to receive callbacks. See Streaming vs Final Callbacks below.

"all" (default): Stream callbacks progressively as results are processed
"final": Receive a single callback when all inputs are processed or an error occurs

Please refer to each async/schedule action in the API Reference for specific details.

Streaming vs Final Callbacks

By default, Edges sends callbacks progressively as results become available (callback.on: "all"). However, you can opt to receive only a single callback when the entire job completes by setting callback.on: "final".

When to Use Each Mode

Mode	`callback.on`	Behavior	Best For
Streaming	`"all"` (default)	Multiple callbacks as results are processed	Real-time processing, large datasets, progressive data consumption
Final	`"final"`	Single callback when job completes	Automation tools (n8n, Make, Zapier), simple integrations, cost optimization

Streaming Mode (`"all"`)

This is the default behavior. You receive callbacks progressively:

One callback per batch/page of results with run.status: RUNNING
One final callback with run.status: SUCCEEDED when complete

{
  "inputs": [...],
  "callback": {
    "url": "https://yourdomain.com/webhook",
    "on": "all"
  }
}

Advantages:

Start processing data immediately as it arrives
Better for large datasets (stream instead of waiting)
Real-time progress tracking

Considerations:

Your endpoint receives multiple requests per run
Requires handling multiple callbacks and aggregating results
Must verify completeness by comparing output count with received results

Verifying Completeness (All Callbacks Mode): After receiving the final callback with run.status: SUCCEEDED, verify that all callbacks were received:

// 1. Get the run details to retrieve output_count
const runResponse = await fetch(`https://api.edges.run/v1/runs/${run_uid}`, {
  headers: { 'X-API-Key': 'your_api_key' }
});
const run = await runResponse.json();
const expectedOutputCount = run.output_count;

// 2. Count all results received in callbacks
// (You should track this as callbacks arrive)
const receivedResultsCount = /* sum of all results.length from callbacks */;

// 3. Compare counts
if (receivedResultsCount === expectedOutputCount) {
  console.log('✅ All callbacks received - data is complete');
} else {
  console.warn(`Missing callbacks: Expected ${expectedOutputCount}, received ${receivedResultsCount}`);
  // Fetch missing results or replay callbacks
  const outputs = await fetch(`https://api.edges.run/v1/runs/${run_uid}/outputs`, {
    headers: { 'X-API-Key': 'your_api_key' }
  });
  // Process missing results
}

Final Mode (`"final"`)

You receive a single callback only when the job is complete:

One callback with run.status: SUCCEEDED or run.status: PARTIAL_SUCCEEDED indicating the run status
Or one callback with run.status: FAILED if an error occurred
Important: The callback indicates the run status but does not contain all results. You must fetch results using the GET /runs/{run_uid}/outputs API endpoint.

{
  "inputs": [...],
  "callback": {
    "url": "https://yourdomain.com/webhook",
    "on": "final"
  }
}

How it works:

Receive final callback with run status (SUCCEEDED, PARTIAL_SUCCEEDED, or FAILED)
Fetch all results using GET /runs/{run_uid}/outputs API endpoint
Process the complete result set

Advantages:

Dramatically reduces webhook executions (1 instead of N)
Simpler integration logic (no aggregation needed)
Lower costs for webhook-based automation platforms
Data completeness guaranteed by the GET Results API

Considerations:

Must wait for the entire job to complete before receiving status
Requires an additional API call to fetch results after the callback

Fetching Results (Final Callback Mode): After receiving the final callback, fetch all results:

// 1. Receive final callback with run.status
// Example callback payload:
// { "run": { "run_uid": "...", "status": "SUCCEEDED" }, ... }

// 2. Fetch all results using the GET API
const outputsResponse = await fetch(
  `https://api.edges.run/v1/runs/${run_uid}/outputs?limit=100&offset=0`,
  { headers: { 'X-API-Key': 'your_api_key' } }
);
const outputs = await outputsResponse.json();

// 3. Process the complete result set
// Note: Use pagination (limit/offset) if there are many results

For automation tools like n8n, Make, or Zapier: Use callback.on: "final" to avoid flooding your workflows with multiple webhook triggers. This can significantly reduce your automation platform costs, especially for jobs with many results.

Data Completeness Guarantees

Each callback mode ensures data completeness differently. Understanding these guarantees helps you build robust integrations that never miss data.

All Callbacks Mode (`on: "all"`)

Results are delivered progressively through multiple callbacks during the run execution. How completeness is ensured:

Each callback contains a subset of the run results
When the run finishes, verify completeness by:
- Retrieving the run output count using GET /runs/{run_uid} - the output_count field indicates the total number of outputs generated
- Comparing it with the number of results received via callbacks (count all results from callbacks with run.status: RUNNING and the final run.status: SUCCEEDED)

Outcome:

✅ Counts match → All callbacks were received, data is complete
Counts differ → One or more callbacks are missing
- Use the List Callbacks endpoint to identify missing callbacks
- Retry missing callbacks using the Replay Callback endpoint
- Or fetch missing results directly via GET /runs/{run_uid}/outputs
- To recover input-level errors (e.g., 404s) that aren’t in outputs, use GET /runs/{run_uid}/inputs

Guarantee: Data completeness is validated by a final comparison between received callbacks and the run output count.

Final Callback + GET Results Mode (`on: "final"`)

Results are delivered after the run is fully completed using a two-step process. How it works:

A single final callback indicates the run status (SUCCEEDED, PARTIAL_SUCCEEDED, or FAILED)
The client then retrieves all results using the GET /runs/{run_uid}/outputs API call

Outcome:

Results are fetched directly from the server via the API
No intermediate callbacks are involved
No callback verification needed

Guarantee: Data completeness is ensured by the GET Results API, not by callbacks.

Summary

Mode	Result Delivery	Completeness Check
All Callbacks (`on: "all"`)	Multiple callbacks during execution	Final comparison with run output count
Final Callback + GET (`on: "final"`)	One final callback + API retrieval	No callback verification needed

Which Mode Should I Use?

All Callbacks → If you need real-time processing or progressive results
Final Callback + GET → If you prefer a simpler flow and can wait for completion

How Callbacks Work

Understanding how callbacks are processed and delivered helps you build robust integrations.

Parallel Processing & Pagination

Async actions are designed to scale efficiently by processing multiple pages concurrently:

Improved performance: Pages are processed in parallel
Manageable payloads: Each page generates a separate callback
Faster time-to-first-result: Start consuming data immediately

Callback Flow

The callback flow depends on the callback.on setting:

Streaming Mode (on: all)
Final Mode (on: final)

Trigger Action

Action is triggered in async mode with max_results: 100

Auto-Pagination

Backend automatically paginates results with page_size: 10

Receive Running Callbacks

You receive 10 callbacks with:

run.status: RUNNING (this is the run status, indicating the run is in progress)
Each containing ~10 results (may vary slightly as we filter out ads and other content)

Final Success Callback

Once the run completes, you receive one final callback with run.status: SUCCEEDED (indicating the run finished successfully)

Important: You may receive multiple callbacks for a single execution, and they may arrive out of order due to parallel processing. Always use the run_uid and batch_uid to track and organize your data.

Trigger Action

Action is triggered in async mode with max_results: 100

Processing

Backend processes all results. No callbacks are sent during execution.

Final Callback

Once all inputs are processed, you receive one single callback with:

run.status: SUCCEEDED or PARTIAL_SUCCEEDED (indicating the run completed)
Or run.status: FAILED if an error occurred
Note: The callback indicates status but does not contain all results

Fetch Results via API

After receiving the final callback, fetch all results using:

GET /runs/{run_uid}/outputs to retrieve the complete result set
Results are fetched directly from the server, ensuring data completeness

Two-step process: With final mode, you receive exactly one callback per run (status only), then fetch results via the API. This makes it ideal for automation workflows that trigger on webhook events and prefer fetching data on-demand.

Next Steps

Callback Payloads

The JSON structure, run vs callback statuses, and custom_data.

Callback Delivery

Idempotency, missed-callback detection, and replays.

List Callbacks

Endpoint reference — parameters, filters and responses.

Manage Runs

Read, stop, continue and resume a run.

Start here

Identities

Running actions

Limits

Troubleshooting

LinkedIn specifics

SDKs & integrations

Build with Edges

Overview

Payloads

Delivery

What are Callbacks?

Quick Start

1. Set up your webhook endpoint

2. Configure your action call

3. Handle incoming callbacks

Understanding Async and Schedule Modes

Setting Up Callbacks

Streaming vs Final Callbacks

When to Use Each Mode

Streaming Mode (`"all"`)

Final Mode (`"final"`)

Data Completeness Guarantees

All Callbacks Mode (`on: "all"`)

Final Callback + GET Results Mode (`on: "final"`)

Summary

Which Mode Should I Use?

How Callbacks Work

Callback Flow

Next Steps

Callback Payloads

Callback Delivery

List Callbacks

Manage Runs

Overview

Payloads

Delivery

​What are Callbacks?

​Quick Start

​1. Set up your webhook endpoint

​2. Configure your action call

​3. Handle incoming callbacks

​Understanding Async and Schedule Modes

​Setting Up Callbacks

​Streaming vs Final Callbacks

​When to Use Each Mode

​Streaming Mode ("all")

​Final Mode ("final")

​Data Completeness Guarantees

​All Callbacks Mode (on: "all")

​Final Callback + GET Results Mode (on: "final")

​Summary

​Which Mode Should I Use?

​How Callbacks Work

​Parallel Processing & Pagination

​Callback Flow

​Next Steps

Callback Payloads

Callback Delivery

List Callbacks

Manage Runs

What are Callbacks?

Quick Start

1. Set up your webhook endpoint

2. Configure your action call

3. Handle incoming callbacks

Understanding Async and Schedule Modes

Setting Up Callbacks

Streaming vs Final Callbacks

When to Use Each Mode

Streaming Mode (`"all"`)

Final Mode (`"final"`)

Data Completeness Guarantees

All Callbacks Mode (`on: "all"`)

Final Callback + GET Results Mode (`on: "final"`)

Summary

Which Mode Should I Use?

How Callbacks Work

Parallel Processing & Pagination

Callback Flow

Next Steps