> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Start dependency update runs on demand and poll their status through the REST API without enabling a schedule.

# Dependency Updates

Use the Dependency Updates API to start a run for a connected repository and
poll its status. An on-demand run uses the same update generation, package risk
policy, and publication safeguards as scheduled
[Secure Dependency Updates](https://www.superagent.sh/docs/security-workers/secure-dependency-updates).

All requests require an organization API key sent as a bearer token in the
`Authorization` header, as described in the [REST API](https://www.superagent.sh/docs/api).
Repositories and runs are scoped to the API key's organization.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/repositories/{repositoryId}/dependency-updates` | Start an asynchronous dependency update run |
| `GET` | `/dependency-updates/{runId}` | Retrieve an organization-scoped run and its status |

`repositoryId` is the positive integer ID of a connected GitHub repository. `runId` is
the UUID returned when a run is accepted.

## Start a run

`POST /api/v1/repositories/{repositoryId}/dependency-updates` starts one run.
The repository must belong to the API key's organization and have an active
Superagent Security GitHub App installation. A live private run costs **5 credits**
when it starts, even if it fails or finds no updates. Public repositories and
`dryRun: true` cost no credits.

You can start a run while the repository schedule is **Off**. Starting a run
does not enable or change the schedule.

### Request

The optional JSON body accepts `scope` and `dryRun`:

| Field | Type | Description |
| --- | --- | --- |
| `scope` | string | Optional: `vulnerabilities`, `versions`, or `all`. Defaults to the repository's saved dependency update scope |
| `dryRun` | boolean | Set `true` to resolve updates without writing GitHub branches or pull requests. Defaults to `false` |

- `vulnerabilities` targets known vulnerable dependencies.
- `versions` checks direct dependencies for available versions.
- `all` checks vulnerability remediation and regular version updates in one Renovate run.

Use `{"scope":"versions","dryRun":true}` to test ordinary updates separately
from `{"scope":"vulnerabilities","dryRun":true}`. Neither request changes the
saved scope or publishes pull requests.

An explicit scope applies to this run without changing the repository's saved
scope. Omit the body, or send `{}`, to use the saved scope. Requests reject
unsupported JSON fields.

```bash
curl https://superagent.sh/api/v1/repositories/1095278383/dependency-updates \
  -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"vulnerabilities"}'
```

### Response

`202 Accepted`

```json
{
  "data": {
    "id": "7b6e70c5-8cd2-4f9e-95dd-4a24e3c8a019",
    "object": "dependency_update_run",
    "repository_id": 1095278383,
    "scope": "vulnerabilities",
    "mode": "manual",
    "status": "queued",
    "dry_run": false,
    "summary": null,
    "proposal_count": 0,
    "skipped_count": 0,
    "published_count": 0,
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-10-01T12:00:00.000Z",
    "updated_at": "2026-10-01T12:00:00.000Z"
  }
}
```

Accepted means the run has been queued, not that a pull request has been
published. If a run is already `queued` or `in_progress` for the repository,
the request returns `409 conflict` rather than starting another run.
An unavailable or inactive repository or GitHub App installation returns
`404 not_found`. A live private run that would exceed the free-plan credit
allocation returns `402` before it is queued. The worker rechecks capacity
when the run begins; intervening usage can cause an accepted run to fail.

## Retrieve run status

`GET /api/v1/dependency-updates/{runId}` returns `200 OK` with the run under
`data`, using the same object shape as the start response.

```bash
curl https://superagent.sh/api/v1/dependency-updates/7b6e70c5-8cd2-4f9e-95dd-4a24e3c8a019 \
  -H "Authorization: Bearer sk_live_..."
```

### Run fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Run UUID |
| `object` | string | Always `dependency_update_run` |
| `repository_id` | number | Connected GitHub repository ID |
| `scope` | string | Effective scope: `vulnerabilities`, `versions`, or `all` |
| `mode` | string | `manual` for on demand runs; `daily`, `weekly`, or `monthly` for scheduled runs |
| `status` | string | `queued`, `in_progress`, `completed`, or `failed` |
| `dry_run` | boolean | Whether publication is disabled for this run |
| `summary` | object or null | Versioned, validated Renovate evidence for extraction, update candidates, skips, resolution failures, and proposed branches; independent of truncated diagnostic logs |
| `proposal_count` | number | Recorded native proposed branch count for runs with summaries; use `summary` to distinguish missing evidence from zero |
| `skipped_count` | number | Recorded native skipped dependency count for runs with summaries; detailed reasons are in `summary` |
| `published_count` | number | GitHub pull requests observed during a completed live run; always `0` in dry-runs |
| `error_message` | string or null | Run failure information, or `null` when no error is recorded |
| `started_at` | string or null | Time execution started, or `null` before execution |
| `completed_at` | string or null | Time execution reached a terminal status, or `null` while active |
| `created_at` | string | Time the run was created |
| `updated_at` | string | Time the run was last updated |

Check `summary.outcome`, not status alone. `no_supported_dependencies` means
no manifests were extracted, not that the repository is vulnerability-free.
`summary_incomplete` and null counts mean evidence is missing, not zero updates.
`updates_proposed` records native candidates, including non-publishing dry-runs;
it is not proof of vulnerability removal or policy approval. Older runs and
runs without validated evidence return `summary: null`.

### Dry-run publication and dependency availability

New summaries include `publication`, an optional v1 extension. Use
`publication.wouldCreatePR` for distinct branches whose new-PR eligibility was
established after resolution and verification, and `wouldUpdatePR` for existing
pull requests. Do not use raw candidates or proposed branch counts as PR counts.
`unknownEligibility` is explicit when native publication gates cannot be proven
without a real branch or status checks; the counts do not guarantee future CI,
GitHub acceptance, or merge approval. Inspect `complete` and `blockedReasons`.
Samples can be truncated without truncating aggregate counts.

`lookups` separates unavailable dependency identities from their affected
occurrences. Many files referencing one private module count as one unavailable
dependency, not many distinct failures. An explicit access error is reported
separately from a generic no-result, which could also mean missing tags or an
unavailable package. Unsupported dynamic references and artifact resolution
failures are separate categories. These fields do not broaden repository access.

Older runs omit these extensions or return null. Rerun with `dryRun: true`
after deployment to collect the new evidence.

Timestamps use ISO 8601 strings in UTC. Poll while the status is `queued` or
`in_progress`, and stop when it is `completed` or `failed`. Back off between
requests and respect API rate limits rather than polling continuously.
Unknown runs and runs belonging to another organization return `404 not_found`.

## Publication is asynchronous

A `completed` run does not guarantee that a pull request exists. A run can
finish without eligible updates, or proposals can be skipped by policy,
pre-publication Kernel checks, or publication safeguards. Publication happens asynchronously after update
generation and evaluation.

To trigger automation only when an approved update reaches GitHub, subscribe
to the existing `dependency_update.published` organization webhook. It includes
the repository, persisted Renovate pull request observation ID, title, and
pull request URL. The run ID is `null` if no matching run was found. It is a
publication event, not a run-completion event. See
[Webhooks](https://www.superagent.sh/docs/webhooks) for the payload, signatures, and retries.

## MCP tools

The same operations are available through the [Superagent MCP server](https://www.superagent.sh/docs/mcp):

| REST operation | MCP tool | Arguments |
| --- | --- | --- |
| Start a run | `trigger_dependency_updates` | `repository_id` (number), optional `scope` (`vulnerabilities`, `versions`, or `all`) |
| Retrieve run status | `get_dependency_update` | `run_id` (UUID string) |

Omitting MCP `scope` uses the repository's saved scope. MCP has the same
organization scoping, active-run conflicts, and asynchronous publication
behavior as REST.

## Errors

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Invalid repository ID, run UUID, JSON body, or scope |
| `401` | `unauthorized` | Missing or invalid organization API key |
| `404` | `not_found` | Repository or run is missing or belongs to another organization, or the repository or GitHub App installation is inactive |
| `409` | `conflict` | A repository run is already active |
| `500` | `internal_error` | Unexpected server failure |

## Next steps

- [Configure Secure Dependency Updates](https://www.superagent.sh/docs/security-workers/secure-dependency-updates)
- [Subscribe to published updates with Webhooks](https://www.superagent.sh/docs/webhooks)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)

---
Source: https://www.superagent.sh/docs/api/dependency-updates
Index: https://www.superagent.sh/llms.txt