Skip to main content
This guide explains how to launch, monitor, filter, sort, and retrieve results from your runs using the Edges API.

​
Launching a Run

  • Use the API to start a new run by calling the appropriate action endpoint (e.g., /v1/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

For now, there is no dashboard to view runs—you must use the API for all management tasks.

​
Listing Runs

  • Use GET /v1/runs 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.edges.run/v1/runs?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.edges.run/v1/runs?limit=20&sort=-created_at" \
  -H "X-API-Key: <YOUR_API_KEY>"

​
Getting a Specific Run

  • Use GET /v1/runs/{run_uid} 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.edges.run/v1/runs/{run_uid}" \
  -H "X-API-Key: <YOUR_API_KEY>"

​
Resuming a Run

curl -X POST "https://api.edges.run/v1/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 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.
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.

​
Data Retention

Edges automatically manages data retention to maintain optimal platform performance. Understanding retention periods helps you plan your data storage and retrieval strategies.

​
Run Data Retention

  • Runs and Flow Runs: Automatically archived after 90 days
    • Once archived, runs are no longer accessible via the API
    • Run outputs and statistics are also cleaned up after 90 days
    • This ensures faster queries and better overall system performance
  • Usage Records: Automatically cleaned up after 5 days
    • Integration account usage data is retained for 5 days
    • This data is used for rate limiting and quota management
If you need to keep run data longer than 90 days, make sure to:
  • Store run results in your own system via callbacks
  • Export important run data before the retention period expires
  • Use the callback system to receive and persist results as they’re generated

​
Best Practices

  • Use Callbacks: For long-term data storage, rely on callbacks to receive and store results in your own database
  • Export Important Data: Periodically export run metadata and results if you need historical records
  • Monitor Recent Activity: Focus on runs from the last 90 days when querying via the API
Data retention is automated and runs daily. This helps maintain platform performance and ensures faster API responses for recent data.
See the API Reference for detailed endpoint usage and more examples.