Skip to main content
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

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

{
  "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: 
{
  "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.
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.

​
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

StatusMeaning
200Setup progress returned
404Context not found