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

# Setup progress

> Read a context's aggregated setup and activation-readiness state in a single request to drive an onboarding checklist or setup wizard.

The setup-progress endpoint returns configured-resource counts, the last-run state, and activation readiness for a context in a single aggregate — so a setup wizard or onboarding checklist derives its state from one request instead of many.

## Get setup progress

***

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/setup-progress" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "sources": { "total": 2, "left": 1, "right": 1 },
  "fieldMaps": { "mappedSources": 2 },
  "matchRules": { "total": 3 },
  "schedules": { "total": 1 },
  "lastRun": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "completedAt": "2025-01-15T10:30:00Z"
  },
  "readiness": {
    "ready": true,
    "missing": []
  }
}
```

## What it returns

***

* **`status`** — the context lifecycle status: `DRAFT` (being configured), `ACTIVE` (running), `PAUSED` (suspended), or `ARCHIVED` (retired).
* **`sources`** — source counts split by matching side: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`** — number of sources that have a field map configured.
* **`matchRules.total`** — match-rule count for the context.
* **`schedules.total`** — schedule count for the context.
* **`lastRun`** — the most recent match run (`id`, `status` of `PROCESSING`/`COMPLETED`/`FAILED`, and `completedAt`). It is `null` when the context has never run.
* **`readiness`** — activation-readiness summary (see below).

## Readiness and the checklist

***

The `readiness` block reports whether the context satisfies every activation requirement:

```json theme={null}
{
  "ready": false,
  "missing": ["sources_left", "match_rules"]
}
```

`missing` holds **stable slugs** you can map to per-requirement checklist items. The possible values are:

* `sources_left` — the context needs at least one LEFT-side source.
* `sources_right` — the context needs at least one RIGHT-side source.
* `field_maps` — the context's sources need field maps configured.
* `match_rules` — the context needs at least one match rule.

<Note>These slugs are an API contract shared with the activation flow. When a context is transitioned to `ACTIVE` before it is ready, the update is rejected with a `409` carrying the same slugs under a `context_not_ready` code and a `details.missing` array. Branch on those slugs to render the exact same guidance you show in the setup checklist.</Note>

## How to use it during setup

***

1. **Render the checklist.** On each step of the wizard, GET setup-progress and use the counts (`sources`, `fieldMaps`, `matchRules`, `schedules`) to tick off completed items.
2. **Gate the "Activate" button.** Enable activation only when `readiness.ready` is `true`; otherwise list `readiness.missing` as the remaining steps.
3. **Show run health.** Once `lastRun` is present, surface its `status` and `completedAt` so operators can confirm the context is producing results.

Because the whole state comes from one call, you can poll this endpoint to keep the wizard live without orchestrating separate source, rule, and run reads.

## Response codes

***

| Status | Meaning                 |
| ------ | ----------------------- |
| `200`  | Setup progress returned |
| `404`  | Context not found       |