Concepts

Veille (monitoring)

A recurring scrap that diffs each run against the previous one and surfaces reputation signals.

A veille (French for "watch") is a scheduled re-run of an existing job or pipeline. Each run is diffed against the previous one, and differences are exposed as signals.

A veille is created from an existing scrap job (the source). Its query + zones + parameters become the template, cloned at each scheduled run.

   source job (one-off scrap)
        │  registered as veille, frequency = 7 days
        ▼
   run 1   ──►   poi_list_v1
        │  7 days later
        ▼
   run 2   ──►   poi_list_v2
        │  diff(v1, v2)
        ▼
   change report:
     - new POIs (opened)
     - closed POIs (no longer found)
     - modified POIs (ratings dropped, contact changed, ...)

Frequency

Days, 1–365. Hourly is intentionally disallowed: prospect data doesn't move that fast, and source rate limits would not survive it. Typical: 7 (weekly), 30 (monthly), 90 (quarterly).

Signals

Three categories extracted from each diff:

new — in the new run, absent before (newly opened competitors, partners, acquisition targets)
closed — absent from the new run, present before (outreach cleanup; early shutdown signal)
modified — present in both, changed:
Rating delta — Google rating drop = strong "client in trouble" signal
Review count delta — surging or stalling activity
Contact delta — phone or website changed (often a relaunch)

Modified rows are scored; the signals endpoint returns them ranked.

Endpoints

GET    /api/veille                              # list user's veilles
POST   /api/veille                              # create
PATCH  /api/veille/{id}                         # update name, frequency, status
DELETE /api/veille/{id}                         # soft-delete
GET    /api/veille/{id}/runs                    # historical runs
GET    /api/veille/{id}/runs/{run_id}           # one run + diff
GET    /api/veille/{id}/runs/{run_id}/signals   # filtered, scored signals

Signals endpoint supports CSV / JSON / XLSX via ?format=….

States

State	Meaning
`active`	Will run on schedule
`paused`	Schedule suspended; existing runs remain available
`deleted`	Soft-deleted; data retained

A veille run is a normal job — same workers, same quotas. Counts against the running-jobs ceiling only at run time.