Product Matcher

Schedule and history

Matching can run by itself, for example after each new scrape or every Monday at 06:00. Every run, by hand or by schedule, is in History with its status and its cost. Each scheduled run holds money in your wallet like a run you start by hand.

In the portalVia APIVia MCP

1. Open your group, pick Matching, then Match the data. Open the 3-dots menu next to Run match and pick Run configuration.
2. In Match settings, press Change next to Schedule. The Matching schedule dialog opens.
3. Pick an Automation: Run once (no schedule), After each scrape, Daily, Every N days (set Run every (days)) or Weekly (pick days) (pick the days).
4. For a calendar choice, set Time and Timezone.
5. Read the cost line: each scheduled run reserves up to an amount, charged to the group owner’s wallet. When the balance is too low, that run is skipped.
6. Press Save. With Run once, the button is Save and run and also starts a run now. Close leaves without saving.
7. Open History to see every run, newest first, under “Runs (last 10 kept)”. The run whose results you see has the Active chip. A waiting or running row has Stop.
8. A queued run is the top row: “Queued, next in line” or “Queued, N ahead”. Its Cancel opens Stop this matching run?.
9. Read the columns: Run, Status, Sources compared, Items in scope, Matched, Your products matched, Waiting for review, Match rate, Pictures and Cost, plus “Kept / new” (for example “9,820 / 412”: matches kept from before and new ones) and “Decisions”.
10. Press the lime ”+” square at the start of a row to open the run’s details. It shows the status reason, what to do, warnings, “Steps”, “Setup” and the run’s choices. Press ”-” to close it.
11. In the details, press “View matches” to see the pairs this run matched. “Hide matches” closes the list. If the run used “Start fresh”, “Undo start fresh” is there too, see Undo start fresh.
12. Tick two rows and press Compare 2 runs to compare them. Show deleted runs also lists runs you deleted.
13. The Danger zone below the table deletes matching data, or undoes all your review decisions with Unmatch all reviewed….

The Status column is one short word: Completed, Failed, Stopped, Running, Queued, Draft or Held. The reason is in the run’s details (”+”). “Held” means the result looked wrong in size, so it was not delivered and the previous results are kept. A run skipped for a low wallet shows “Not started: balance too low” in Cost.

Rounds and kept pairs

Each run that finishes is one round in History. It records the choices you made at Run (see Your current matches) and what happened:

The kept and dropped counts are not shown for a run that failed, was cancelled, stopped or replaced.

The pairs of a past run. Each finished run keeps its own list of pairs, so you can still read an old run’s matches after a newer run replaced them. In the portal, press “View matches” in the run details. The list “Matches of this run” shows “Product”, “Matched with”, “Score” and “How”: “You approved”, “Kept from before” or “Automatic”.

• API. GET /api/scraper/group/{id}/match/runs/{runId}/pairs (Read or Full). Query kind is MATCH (default) or REVIEW, page starts at 0, size is 1 to 500 (default 100).
• MCP. scrapewise_get_matcher_run_pairs (Read) with id, runId, and if you want kind, page and size.
• The answer. {runId, kind, ledgerStatus, content, totalElements, page, size}. Each pair has sourceScraperId, sourceIdentity, masterRef, decision, score, matchOrigin, sourceTitle and masterTitle.

curl -H "Authorization: Bearer $SCRAPEWISE_READ_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper/group/[GROUP ID]/match/runs/[RUN ID]/pairs?kind=MATCH&page=0&size=100"

How many runs keep their pairs

By default the newest 10 runs keep their list of pairs. You can set a number from 1 to 10. Older runs stay in History with their counts; only their list of pairs goes. Matches you approved are never removed.

Set runsKept with the API or MCP.

• API. PATCH /api/scraper/group/{id}/match/history-settings (Full) with the body {"runsKept": 5} and a new Idempotency-Key header. The answer is {"runsKept": 5}. Read the value back in runsKept of GET .../match/config-status.
• MCP. scrapewise_update_matcher_history_settings (Full) with id, a new idempotency_key and the body {"runsKept": 5}.
• Errors. A number outside 1 to 10, or no number: 400 FIELD_INVALID “runsKept must be a whole number from 1 to 10. Nothing was changed.” A Read key gets 403. An unknown group gets 404.

scrapewise_update_matcher_history_settings
{
  "id": "[GROUP ID]",
  "idempotency_key": "[NEW UUID]",
  "body": { "runsKept": 5 }
}

Undo start fresh

“Start fresh” sets your earlier decisions aside from that run on. It does not delete them. You can undo the newest start fresh.

• Portal. In History, open the run that started fresh with ”+” and press “Undo start fresh”. Decided pairs leave Review now. Your approved matches come back with the next run. The portal says “Start fresh is undone. Decided pairs left Review.”
• API. POST /api/scraper/group/{id}/match/runs/{runId}/undo-fresh (Full), no body, with a new Idempotency-Key header. The answer is {runId, configId, cutoffAt, undone: true, undoneAt}. Sending it again gives the same answer.
• MCP. scrapewise_update_matcher_fresh_undo (Full) with id, runId and a new idempotency_key.

curl -X POST "https://portal.scrapewise.ai/api/scraper-api/api/scraper/group/[GROUP ID]/match/runs/[RUN ID]/undo-fresh" \
  -H "Authorization: Bearer $SCRAPEWISE_FULL_KEY" \
  -H "Idempotency-Key: [NEW UUID]"

Only the newest start fresh can be undone.

Daily matched file

One fixed address per group always gives the newest file of all matched rows, as gzip JSON Lines or CSV. Use it for a daily import. Read and Full keys both work.

curl -H "Authorization: Bearer $SCRAPEWISE_READ_KEY" -o matched.jsonl.gz \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper/group/[GROUP ID]/match/export/latest?format=jsonl&bucket=matched"

• Is it ready? GET .../match/export/latest/status (Read, free) or the MCP tool scrapewise_get_matched_export_latest_status (Read). ready: true means the file at url is complete.
• Keep it ready. PUT .../match/export/auto (Full) with {"enabled":true,"formats":["jsonl"],"bucket":"matched"} builds a new file after each run and after review decisions. GET .../match/export/auto (Read) reads the setting.
• A one-off file with your own filters: see Exports and delivery.

Errors you may see

Questions

Last updated 10 November 2026