The QA/QC service is the bulk-orchestration layer on top of the per-pole analyzers. It accepts a project (a SPIDA file, an O-Calc bundle, a PLS line, or an ESRI polygon pull), fans out clearance, loading, sag, classification, and guying across every pole, and rolls the results back up into a portfolio-level scorecard.

It’s how QA/QC firms and utility engineering teams put hundreds or thousands of poles through the platform in one job.

Endpoints

POST /batch/create

Create a batch from a source file or ESRI polygon.

curl https://$VERTICAL_AI_BASE_URL/batch/create \
  -H "Authorization: Bearer $VERTICAL_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "spida | ocalc | pls | esri-polygon",
    "payload": { ... }
  }'

Returns a batch_id.

POST /batch/{id}/run

Kick off the analyzer pass. Optionally restrict which analyzers run.

{ "analyzers": ["clearance", "loading", "sag", "guying", "classification"] }

GET /batch/{id}/status

Per-pole progress. Useful for streaming progress into a UI.

GET /batch/{id}/scorecard

The roll-up view: pass / fail / pending counts per analyzer, top failure modes, top contributing poles.

GET /batch/{id}/loading

Loading-tab roll-up: which poles are over capacity, which are within tolerance, which are missing inputs.

GET /batch/{id}/loading-summaries

Per-pole controlling-case summary for every pole in the batch — pass, tight, or fail. One row per pole with the full pole-loading response (controlling load case, percent capacity used, contributions, per-component safety factors), plus a pole_metadata block carrying species / class / height / set-depth.

POST /batch/{id}/loading-rerun

Re-runs the pole-loading analyzer for every pole in the batch. Refreshes the POLE_OVERLOADED finding bucket (≥ 90% capacity used) and rewrites the per-pole loading_summaries subcollection.

GET /batch/{id}/storm · POST /batch/{id}/storm-sweep

Storm-loading sweep: same poles re-evaluated against a 72-hour forecast (or longer). The proxy fans the request out to the sag service’s /weather-sweep endpoint. Sync mode for small batches; background-job mode (returns a job_id you poll) for large ones.

GET /batch/{id}/poles/{pole_id}

Drill into a single pole — full Universal Pole Model with all findings, proposals, and verdicts attached.

Bucketization and prioritization

After loading analysis runs, every pole lands in one of four buckets based on its controlling safety factor:

BucketCriterionTypical action
PassAll component SFs ≥ required minimumNo action needed
TightLowest SF is within 10% of its minimumFlag for next inspection cycle
FailAny component SF below its minimum (≥ 90% capacity used)Remediation required — upsize, re-frame, or re-depth
MissingRequired inputs absent (no species/class, no span data)Field data request — not an engineering failure

The Tight bucket is the primary predictive value: these poles pass today but are the most likely candidates for the next make-ready or reconductor to tip over. Sorting the Tight list by ascending SF gives the supervisor a ranked watch list without requiring a separate analysis pass.

The GET /batch/{id}/scorecard response carries bucket counts per analyzer, the top three failure modes by pole count (e.g. “foundation overturning — 12 poles”), and a list of the top contributing poles sorted by severity. The GET /batch/{id}/loading-summaries endpoint backs each bucket row with per-pole detail: controlling load case, percent capacity used, per-component safety factors, and a pole_metadata block for species / class / height / set-depth.

Using the scorecard to prioritize work

A typical project-lead workflow after a batch run:

  1. Triage Fail first — the GET /batch/{id}/loading endpoint returns the fail list sorted by descending capacity usage. The top entries are the most urgent remediation candidates.
  2. Check failure mode distribution — if foundation overturning dominates, the remediation is re-depth or deeper-set replacement, not upsize. The scorecard’s top-failure-modes list makes this visible before opening a single per-pole view.
  3. Separate Missing from Fail — Missing poles inflate apparent failure rate if not filtered. The scorecard counts them in their own bucket so they don’t distort the engineering picture.
  4. Export for client — the scorecard response is structured for direct consumption in a report template: counts, percentages, top failure modes, and the highest-severity poles are all first-class fields.
  5. Re-run after remediation — POST /batch/{id}/loading-rerun refreshes the Fail bucket and rewrites loading_summaries after field changes are uploaded. The scorecard delta between runs shows the remediation’s effect at the portfolio level.

Concurrency and rate limits

Batches run with a per-tenant concurrency cap. Large batches (>1,000 poles) are split into shards under the hood; the API surface is unchanged. Large batches over ~10,000 poles are split into shards automatically.

See also