> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edges.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Runs

> Learn how to launch, monitor, filter, and manage your runs using the Edges API.

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

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

### Listing Runs

* Use [`GET /v1/runs`](/v1/api/runs/list) 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) for listing runs. For run outputs and inputs, use cursor-based pagination via the `X-Pagination-Next` header (see [Pagination Guide](/v1/runs/pagination#paginating-run-outputs--inputs)).
* 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

```bash theme={null}
curl -X GET "https://api.edges.run/v1/runs?execution_mode=ASYNC&status=SUCCEEDED" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>"
```

#### Example: List the 20 most recent runs (sorted by creation date, descending)

```bash theme={null}
curl -X GET "https://api.edges.run/v1/runs?limit=20&sort=-created_at" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>"
```

### Getting a Specific Run

* Use [`GET /v1/runs/{run_uid}`](/v1/api/runs/get) with the run UID to fetch detailed information about a specific run, including its status, execution mode, timestamps, and any errors.

```bash theme={null}
curl -X GET "https://api.edges.run/v1/runs/{run_uid}" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>"
```

### Resuming a Run

* If a run is paused or stopped, you can resume it using [`POST /v1/runs/{run_uid}/resume`](/v1/api/runs/manage).
* Provide the run UID and specify the action (e.g., `resume`).

```bash theme={null}
curl -X POST "https://api.edges.run/v1/runs/{run_uid}/resume" \
  -H "Accept: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    // any required parameters
  }'
```

### Continuing an Incremental Run

If a run was launched with `sync_mode: "incremental"` using an [Engagement Identity](/v1/identities/engagement), you can continue it to fetch only the new data since the last retrieval using [`POST /v1/runs/{run_uid}/continue`](/v1/api/runs/continue).

A run can only be continued if its status is one of: `BLOCKED`, `STOPPED`, `FAILED`, `PARTIAL_SUCCEEDED`, or `SUCCEEDED`.

When a run is continued, its status and all related inputs are reset to `SCHEDULED`.

```bash theme={null}
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"
```

<Info>
  For more information about incremental sync, see the [Incremental Sync guide](/v1/runs/overview#incremental-sync-mode).
</Info>

## 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

<Warning>
  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
</Warning>

<Warning>
  Outputs are **not available** for runs executed in `live` mode. It only works for runs executed in `async` or `schedule` mode. For live mode runs, results are returned directly in the API response.
</Warning>

### 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

<Info>
  Data retention is automated and runs daily. This helps maintain platform performance and ensures faster API responses for recent data.
</Info>

See the [API Reference](/v1/api/runs/list) for detailed endpoint usage and more examples.