# Inflecto.ai — Full API Reference

> Infrastructure intelligence platform that detects large-scale infrastructure siting inflection points — data centers, manufacturing, energy, logistics, semiconductor, healthcare, water, and transportation — 2-4 years early via cross-signal convergence across 26+ data collectors and 75+ pipelines.

All endpoints are REST/JSON over HTTPS at base URL https://inflecto.ai. Authenticate every request with a bearer token in the Authorization header: `Authorization: Bearer <key>`. The authoritative, always-current reference is https://inflecto.ai/developers.

# REST API (18 endpoints)

## Parcel Lookup

`POST /api/land/lookup` — Customer API for parcel coordinates that resolves geography, returns signal context, and classifies buyer patterns when an owner entity is provided.

Parameters:
- `lat` (body, number, required) — Latitude in decimal degrees.
- `lng` (body, number, required) — Longitude in decimal degrees.
- `owner_entity` (body, string) — Entity name; triggers buyer pattern classification when provided.

Example request:
```
POST /api/land/lookup
Authorization: Bearer <key>
Content-Type: application/json

{
  "lat": 33.4484,
  "lng": -112.0740,
  "owner_entity": "MOXIAN INC"
}
```

Example response:
```json
{
  "success": true,
  "location": {
    "lat": 33.4484,
    "lng": -112.0740,
    "cbsa_code": 38060,
    "cbsa_name": "Phoenix-Mesa-Chandler, AZ",
    "resolution": "cbsa"
  },
  "signals": { "count": 12, "data": [] },
  "hold_signals": { "recommendation": "HOLD", "score": 72 },
  "buyer_pattern": {
    "classification": "hyperscaler_shell",
    "likely_parent": "Microsoft",
    "confidence": 0.87,
    "evidence": []
  }
}
```

## Convergence

`GET /api/convergence` — Infrastructure convergence scores for all metros.

Parameters:
- `tier` (query, string) — Filter by ALERT, WATCH, MONITOR, or BASELINE.
- `limit` (query, integer) — Maximum rows to return. Default 100, max 1000.
- `offset` (query, integer) — Pagination offset.

Example request:
```
GET /api/convergence?tier=ALERT&limit=50
Authorization: Bearer <key>
```

Example response:
```json
{
  "data": [
    {
      "cbsa_code": 29700,
      "cbsa_name": "Laredo, TX",
      "tier": "ALERT",
      "convergence_score": 94.3,
      "tier_basis": "relative_percentile",
      "tier_note": "ALERT is top 10% of metros for this scoring period; convergence_score is absolute.",
      "signal_count": 47,
      "distinct_signal_types": 6,
      "newest_signal_date": "2026-04-28"
    }
  ],
  "meta": { "total": 156, "limit": 50, "offset": 0 }
}
```

## Opportunities

`GET /api/opportunities` — Ranked investment opportunities by opportunity score.

Parameters:
- `label` (query, string) — Filter by Strong Buy, Buy, Hold, Watch, or Sell.
- `min_yield` (query, number) — Minimum gross yield percentage.
- `state` (query, string) — Filter by 2-letter state code, such as AZ or TX.
- `min_signals` (query, integer) — Minimum number of signal categories.
- `limit` (query, integer) — Default 100, max 500.

Example request:
```
GET /api/opportunities?label=Strong%20Buy&limit=25
Authorization: Bearer <key>
```

Example response:
```json
{
  "data": [
    {
      "cbsa_code": 29700,
      "cbsa_name": "Laredo, TX",
      "opportunity_score": 4.4,
      "opportunity_label": "Strong Buy",
      "convergence_tier": "ALERT",
      "median_home_price": 142000,
      "median_rent": 1180
    }
  ]
}
```

## Metro Detail

`GET /api/metro` — Complete metro deep-dive with signals, market data, scores, projected_impact, signal_sequence (lifecycle stage), playbook (which step of the land to power to regulatory to construction to market siting playbook the market is currently on), and baseline_returns (the area's typical buy-box cash-on-cash, cap rate, 1%-rule and monthly cash flow with LOCALIZED property tax + insurance — the cash-flow floor before any infrastructure catalyst).

Parameters:
- `cbsa` (query, integer, required) — CBSA code, such as 29700 for Laredo, TX.

Example request:
```
GET /api/metro?cbsa=29700
Authorization: Bearer <key>
```

Example response:
```json
{
  "cbsa_code": 29700,
  "cbsa_name": "Laredo, TX",
  "convergence": { "tier": "ALERT", "score": 94.3, "signal_count": 47 },
  "tier_context": {
    "tier_basis": "relative_percentile",
    "explanation": "ALERT = top 10%, WATCH = top 25%, MONITOR = top 50%; convergence score is absolute."
  },
  "tier_history": [
    { "scoring_period": "2026-04", "previous_tier": "WATCH", "new_tier": "ALERT" }
  ],
  "projected_impact": {
    "rent_growth_range": [8, 14],
    "hpi_growth_range": [12, 18],
    "horizon_months": 24
  },
  "signal_sequence": { "current_stage": "permitting", "next_stage": "construction" },
  "playbook": {
    "current_step": "power",
    "next_step": "regulatory",
    "progress_pct": 40,
    "sequence_intact": true,
    "narrative": "Land Control, Power Procurement steps are active; currently at Power Procurement. Next expected: Regulatory & Permitting."
  },
  "market": { "opportunity_score": 4.4, "opportunity_label": "Strong Buy" },
  "signals": []
}
```

## Supply Monitor

`GET /api/supply-monitor` — Target-scoped new-construction oversupply monitor: a green/yellow/red light on the supply-pressure signal (trailing-24mo multifamily permits vs. ACS renter stock), plus a single-family permit trend (trailing 24mo vs. prior 24mo) and a forward rent-softening projection. Set up an alert on a specific metro or ZIP to catch overbuilding risk before it shows up in rents.

Parameters:
- `cbsa` (query, integer) — CBSA code. Required unless zip is provided.
- `zip` (query, string) — 5-digit ZIP code, resolved to its CBSA. Required unless cbsa is provided. Inherits the metro's light/tier and projection when the ZIP has no rent history of its own.

Example request:
```
GET /api/supply-monitor?cbsa=33740
Authorization: Bearer <key>

GET /api/supply-monitor?zip=71203
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "cbsa_code": 33740,
  "cbsa_name": "Monroe, LA",
  "resolved_from_zip": "71203",
  "computed_through": "2026-04-01",
  "light": "green",
  "tier": "tight",
  "message": "Permit volume is low relative to renter demand — no oversupply risk detected.",
  "multifamily": { "trailing_mf_permits": 5, "renter_stock": 32254, "supply_pressure": 0.000155, "supply_percentile": 35 },
  "single_family": { "trailing_sf_permits": 878, "prior_sf_permits": 690, "sf_trend_pct": 27.2, "sf_trend_direction": "rising" },
  "projected_rel_rent_24mo_pct": 0.853,
  "zip": { "zip": "71203", "tier": "tight", "light": "green", "zip_rent_yoy_pct": null, "metro_rent_yoy_pct": 16.15, "projected_rel_rent_24mo_pct": 0.853 }
}
```

## Signal Timeline

`GET /api/timeline` — 48-month signal convergence timeline for a metro.

Parameters:
- `cbsa` (query, integer, required) — CBSA code.

Example request:
```
GET /api/timeline?cbsa=29700
Authorization: Bearer <key>
```

Example response:
```json
{
  "cbsa_code": 29700,
  "timeline": [
    { "month": "2026-04", "signal_count": 14, "signal_types": ["state_puc_cpcn"] }
  ]
}
```

## Scores

`GET /api/scores` — Composite and opportunity scores for all metros.

Parameters:
- `period` (query, string) — Scoring period, for example 2026-05. Defaults to latest.
- `limit` (query, integer) — Default 918, max 1000.

Example request:
```
GET /api/scores?limit=50
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "scoringPeriod": "2026-05",
  "data": [
    { "cbsa_code": 29700, "score": 4.1, "score_label": "Hot" }
  ]
}
```

## Signal Search

`GET /api/signals/search` — Unified signal search across the ingestion pipeline.

Parameters:
- `q` (query, string) — Full-text keyword.
- `cbsa` (query, integer) — Filter to a metro.
- `signal_type` (query, string) — Filter by signal type.
- `from` (query, date) — ISO 8601 start date.
- `to` (query, date) — ISO 8601 end date.
- `limit` (query, integer) — Default 50, max 200.

Example request:
```
GET /api/signals/search?q=substation&cbsa=29700
Authorization: Bearer <key>
```

Example response:
```json
{
  "data": [
    { "signal_type": "state_puc_cpcn", "title": "Transmission filing", "date": "2026-04-28" }
  ]
}
```

## Heatmap

`GET /api/heatmap` — GeoJSON-style convergence data for map visualization, with filtering by tier, score, and result count.

Parameters:
- `tier` (query, string) — Filter by ALERT, WATCH, MONITOR, or BASELINE.
- `min_score` (query, integer) — Minimum convergence score from 0 to 100.
- `limit` (query, integer) — Maximum number of results. Default 200.

Example request:
```
GET /api/heatmap?tier=ALERT&limit=100
Authorization: Bearer <key>
```

Example response:
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-99.5075, 27.5036] },
      "properties": {
        "cbsa_code": 29700,
        "cbsa_name": "Laredo, TX",
        "tier": "ALERT",
        "convergence_score": 94.3
      }
    }
  ]
}
```

## Impact

`GET /api/impact` — Projected real estate returns by infrastructure project type, plus a forward forecast — V0 compounded along a decomposed annual growth path (g_local) with supply, rates, catalyst proximity, and mean-reversion components. ZIP requests prefer ZIP-grain price/rent inputs (`zip_median_price`, `zip_zori`) and fall back to metro inputs when ZIP data is thin. Covered metros return a baseline forecast even without catalyst conviction; catalyst markets use catalyst basis.

Parameters:
- `cbsa` (query, integer) — CBSA code. Returns projected impact for a metro based on detected signals.
- `zip` (query, string) — 5-digit ZIP code, resolved to its CBSA. Returns the metro projection plus matched_appreciation for catalyst markets and a baseline forecast for covered baseline metros.
- `type` (query, string) — Project type, such as data_center_hyperscale. Returns multiplier data for that type.
- `v0` (query, number) — Anchor value (today's property/portfolio value) to compound in the forecast. Defaults to the metro's current median price when omitted.

Example request:
```
GET /api/impact?cbsa=29700
Authorization: Bearer <key>

GET /api/impact?zip=71203
Authorization: Bearer <key>

GET /api/impact?type=data_center_hyperscale
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "cbsa_code": 33740,
  "resolved_from_zip": "71203",
  "matched_appreciation": {
    "annual_hpi_rate": 0.12,
    "hpi_growth_range": [18, 30],
    "horizon_months": 24,
    "confidence": "moderate",
    "tier": "ALERT",
    "matched_project_types": [{ "project_type": "data_center_hyperscale" }]
  },
  "market": {
    "grain": "zip",
    "inputs": {
      "grain": "zip",
      "price_source": "zip_median_price",
      "rent_source": "zip_zori",
      "price_zip": "71203",
      "rent_zip": "71203",
      "zip_price_n_sales": 14,
      "zip_price_window": { "start": "2024-05-31", "end": "2026-05-31" },
      "zip_rent_observation_date": "2026-05-31"
    },
    "current_price": 184500,
    "current_rent": 1512,
    "current_yield": 9.83
  },
  "forecast": {
    "basis": "catalyst",
    "v0": 312000,
    "v0_source": "market_price",
    "horizon_years": 5,
    "baseline_annual_rate": 0.011,
    "longrun_annual_rate": 0.032,
    "catalyst_proximity": {
      "subject_zip": "71203",
      "subject_grain": "zip",
      "nearest_catalyst": { "source": "interconnection_queue:county", "lat": 32.41316, "lng": -91.74835 },
      "distance_km": 31.5,
      "multiplier": 0.498
    },
    "path": [
      { "year": 1, "g_local": 0.142, "components": { "baseline": 0.011, "catalyst": 0.143, "rates": -0.014, "supply": 0.002, "meanReversion": 0 }, "value_mid": 356304, "value_low": 317111, "value_high": 395497, "confidence": "high" }
      /* ... one entry per year; band widens and confidence decays with horizon ... */
    ]
  },
  "forecast_null_reason": null,
  "baseline_returns": {
    "cash_on_cash_pct": 0.62,
    "monthly_cash_flow": 112,
    "localized_costs": {
      "grain": "county",
      "geo_id": "22073",
      "source": "census_acs_B25103_B25077; state_investment_factors",
      "taxRatePct": 0.5552,
      "insuranceBase": 2800
    }
  },
  "appreciation": {
    "basis": "catalyst",
    "annual_rate_yr1": 0.142,
    "baseline_annual_rate": 0.011,
    "catalyst_annual_rate_yr1": 0.143,
    "longrun_annual_rate": 0.032
  },
  "projections": [ /* per project_type: projected_price_yr1, price_increase_3yr_total_pct, ... */ ]
}
```

## Forecast History

`GET /api/forecast/history` — Actual-vs-estimated forecast history for a metro: realized HPI rebased to the forecast anchor, current forecast path, prior vintages, and matured-vintage accuracy metrics.

Parameters:
- `cbsa` (query, integer) — CBSA code. Required unless zip is provided.
- `zip` (query, string) — 5-digit ZIP code, resolved to its primary county and CBSA. Required unless cbsa is provided.

Example request:
```
GET /api/forecast/history?cbsa=33740
Authorization: Bearer <key>

GET /api/forecast/history?zip=71203
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "cbsa_code": 33740,
  "resolved_from_zip": "71203",
  "actual": [
    { "date": "2024-01-01", "value": 286420 },
    { "date": "2024-04-01", "value": 289110 }
  ],
  "current_forecast": [
    { "year": 1, "g_local": 0.261, "components": { "baseline": 0.011, "catalyst": 0.25, "rates": 0, "supply": 0, "meanReversion": 0 }, "value_mid": 393432, "value_low": 350154, "value_high": 436710, "confidence": "high" }
  ],
  "vintages": [
    { "as_of_date": "2024-06-01", "is_backtest": true, "path": [ /* ForecastYear[] */ ] }
  ],
  "accuracy": {
    "mape": 8.42,
    "hit_rate": 0.75,
    "matured_count": 12
  },
  "catalyst_rent_accuracy": {
    "accuracy_score": 0.82,
    "matured_count": 3,
    "outlier_count": 1,
    "latest": {
      "as_of_date": "2025-05-31",
      "target_date": "2026-05-31",
      "predicted_rent_lift_pct": 34.5,
      "realized_rent_change_pct": 18.2,
      "error_pct_points": 16.3,
      "candidate_cause": "location_too_coarse"
    },
    "outliers": [ /* reviewable catalyst-rent divergences */ ]
  }
}
```

## Catalyst Rent Accuracy Grading

`GET /api/forecast/catalyst-accuracy` — Cron/manual route that grades matured catalyst-rent vintages against realized Zillow ZORI and writes per-market scores plus open outlier findings.

Parameters:
- `cbsa` (query, integer list) — Optional comma-separated CBSA codes to grade. Omit for all catalyst markets.
- `dry_run` (query, boolean) — Use 1/true to compute without writing scores or findings.

Example request:
```
GET /api/forecast/catalyst-accuracy?cbsa=33740&dry_run=1
Authorization: Bearer <cron key>
```

Example response:
```json
{
  "success": true,
  "dry_run": true,
  "graded": 12,
  "score_written": 0,
  "findings_written": 0,
  "skipped": 41
}
```

## Property Search

`GET /api/properties/search` — Property records with owner cross-reference and LLC entity match detection. Useful for identifying hyperscaler land assembly and shell-company acquisition patterns.

Parameters:
- `cbsa_code` (query, integer) — Filter to a CBSA metro.
- `city` (query, string) — Case-insensitive partial match on city name.
- `state` (query, string) — 2-letter state code, such as TX or AZ.
- `property_type` (query, string) — Comma-separated list, e.g. 'Single Family,Land'.
- `lot_size_min` (query, integer) — Minimum lot size in square feet.
- `lot_size_max` (query, integer) — Maximum lot size in square feet.
- `sale_days_back` (query, integer) — Max age of last_sale_date in days. Default 180.
- `owner_type` (query, string) — LLC, Individual, or Corporate.
- `llc_match_only` (query, boolean) — 'true' to return only records with a detected LLC entity match.

Example request:
```
GET /api/properties/search?cbsa_code=18140&owner_type=LLC&llc_match_only=true
Authorization: Bearer <key>
```

Example response:
```json
{
  "results": [
    {
      "address": "4821 W Desert Cove Ave",
      "city": "Phoenix",
      "state": "AZ",
      "property_type": "Land",
      "lot_size": 217800,
      "last_sale_price": 3200000,
      "last_sale_date": "2025-11-14",
      "owner_names": ["APEX DIGITAL HOLDINGS LLC"],
      "owner_type": "LLC",
      "llc_match": "Apex Digital Holdings"
    }
  ],
  "count": 1
}
```

## Opportunity Feed

`GET /api/opportunities/feed` — Decision-first opportunity feed with lifecycle state, rent projections, and recent state transitions — the data behind the Today page delta feed.

Parameters:
- `state` (query, string) — Comma-separated lifecycle states, such as accelerating,confirmed_nda.
- `cbsa` (query, integer) — Filter to a metro.
- `limit` (query, integer) — Default 50, max 200.
- `transitions` (query, boolean) — '1' to include recent lifecycle-state transitions.

Example request:
```
GET /api/opportunities/feed?state=accelerating&limit=25&transitions=1
Authorization: Bearer <key>
```

Example response:
```json
{
  "opportunities": [
    { "id": "...", "slug": "monroe-la-millhaven", "name": "Millhaven", "cbsa_code": 33740, "lifecycle_state": "accelerating", "velocity_30d": 4.2 }
  ],
  "transitions": [ { "opportunity_id": "...", "from_state": "confirmed_nda", "to_state": "accelerating", "transitioned_at": "2026-05-20" } ],
  "counts": { "accelerating": 12, "confirmed_nda": 8 }
}
```

## Thesis

`GET /api/thesis` — Latest generated investment thesis document for a metro — structured evidence blocks plus a live convergence snapshot for drift comparison against the frozen thesis numbers.

Parameters:
- `cbsa` (query, integer, required) — CBSA code.
- `format` (query, string) — 'json' (default) for structured evidence blocks, or 'brief' for a markdown memo.

Example request:
```
GET /api/thesis?cbsa=26900&format=json
Authorization: Bearer <key>
```

Example response:
```json
{
  "id": "...",
  "status": "published",
  "generated_at": "2026-05-01T00:00:00Z",
  "document": { "summary": "...", "evidence": [] },
  "live": { "score": 94.3, "tier": "ALERT", "signalCount": 47, "categoryCount": 6, "scoringPeriod": "2026-05" }
}
```

## Macro / Market Data

`GET /api/macro` — Unified national economic series API (FRED, Freddie Mac PMMS, BLS) — a single authed, cached read surface. No params returns the full series catalog; ?series= returns a time series or as-of value; ?latest=true returns a snapshot of every series.

Parameters:
- `series` (query, string) — Series id, such as MORTGAGE30US. Returns its time series (newest-first).
- `asOf` (query, date) — With series: nearest prior observation on or before this date (YYYY-MM-DD).
- `from` (query, date) — With series: range start (YYYY-MM-DD).
- `to` (query, date) — With series: range end (YYYY-MM-DD).
- `latest` (query, boolean) — 'true' returns the latest value for every series (a macro snapshot).
- `limit` (query, integer) — With series: max observations returned.

Example request:
```
GET /api/macro?series=MORTGAGE30US&asOf=2021-06-15
Authorization: Bearer <key>

GET /api/macro?latest=true
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "series_id": "MORTGAGE30US",
  "as_of": "2021-06-15",
  "data": { "series_id": "MORTGAGE30US", "series_name": "30-Year Fixed Mortgage Rate", "observation_date": "2021-06-10", "value": 2.96, "unit": "percent", "frequency": "weekly" }
}
```

## Distress List

`GET /api/distress/list` — Recent code-enforcement violations as lead candidates, scoped to ONE county or CBSA per request (never bulk — anti-extraction posture).

Parameters:
- `cbsa` (query, integer) — CBSA code. Required unless county+state is provided.
- `county` (query, string) — County name. Required with state unless cbsa is provided.
- `state` (query, string) — 2-letter state code. Required with county unless cbsa is provided.
- `category` (query, string) — Filter by violation category.
- `status` (query, string) — Filter by violation status.
- `days` (query, integer) — Lookback window in days. Default 90, max 365.
- `limit` (query, integer) — Default 200, max 500.

Example request:
```
GET /api/distress/list?cbsa=33740&days=180
Authorization: Bearer <key>
```

Example response:
```json
{
  "success": true,
  "scope": { "cbsa_code": 33740 },
  "since": "2025-11-30",
  "count": 14,
  "data": [ { "address": "123 Main St", "violation_category": "vacant_structure", "status": "open", "reported_date": "2026-04-10" } ]
}
```

## Status

`GET /api/status` — Platform health, pipeline run counts, freshness, and scoring timestamp.

Parameters:
_No parameters._

Example request:
```
GET /api/status
```

Example response:
```json
{
  "ok": true,
  "pipelines": { "healthy": 72, "degraded": 3 },
  "last_scoring_at": "2026-05-04T03:00:00Z"
}
```

# MCP Tools (9 tools)

AI agents can discover and call these tools over the Model Context Protocol at `https://inflecto.ai/api/mcp` — `GET` returns the tool list, `POST { tool, args }` executes a tool (bearer auth, same key as the REST API). Each tool proxies to the REST endpoints above.

### get_metro_intelligence

Returns comprehensive intelligence for a US metro area including signal score, opportunity score, convergence confidence, market data (rent, price, DOM), state investment factors, and recent signals from all pipelines. This is the primary tool for evaluating a market.

Input:
- `cbsa` (number, required) — 5-digit CBSA code for the metro area (e.g., 33740 for Monroe, LA)

### get_top_opportunities

Returns the top investment opportunities ranked by opportunity score. Combines signal strength with affordability and yield to identify markets where infrastructure signals + low entry cost = best ROI. Labels: Strong Buy, Buy, Hold, Watch, Sell, Strong Sell.

Input:
- `label` (string) [Strong Buy | Buy | Hold | Watch | Sell | Strong Sell] — Filter by label: Strong Buy, Buy, Hold, Watch, Sell
- `limit` (number) — Max results (default 25)

### get_signal_timeline

Shows where a metro sits in the 48-month infrastructure detection window. Maps detected signals to their typical lead time: interconnection queue (T-48), LLC formation (T-30), rezoning (T-18), building permits (T-6). Classifies phase: Early Detection, Optimal Window, or Late Stage.

Input:
- `cbsa` (number, required) — CBSA code

### search_signals

Search for infrastructure signals across all data pipelines. Find LLC formations, planning rezonings, building permits, energy filings, and more by state, metro, or signal type.

Input:
- `state` (string) — 2-letter state code
- `cbsa` (number) — CBSA code
- `type` (string) [llc | planning | data_center | energy | industrial] — Signal type filter
- `days` (number) — Lookback days (default 180)

### get_projected_impact

Returns projected property value and rent increases based on the type of infrastructure project being built. Uses calibrated multipliers from 82 case studies including Intel Ohio, TSMC Phoenix, Meta Hyperion, and 23 verified WFI properties.

Input:
- `cbsa` (number) — CBSA code — returns projections using current market data
- `type` (string) [data_center_hyperscale | semiconductor_fab | ev_battery_factory | fulfillment_center | hospital_expansion | corporate_hq] — Project type

### calculate_investment

Computes true investor returns: CoC ROI, cap rate, monthly cash flow, DSCR, and 5-year equity projection. Auto-fills market data from Rentcast and state-specific tax/insurance rates. Supports conventional, BRRR, and cash purchases.

Input:
- `cbsa` (number) — CBSA code (auto-fills market data)
- `purchase_price` (number) — Purchase price override
- `monthly_rent` (number) — Monthly rent override
- `down_payment_pct` (number) — Down payment percentage (default 20)
- `rehab_cost` (number) — Renovation budget for BRRR

### get_land_opportunities

Returns land investment opportunities derived from signal convergence: pre-announcement plays (power signals), annexations (municipal expansion), rezonings (ag to industrial), and adjacent land sales near announced projects.

Input:
- `state` (string) — 2-letter state code
- `type` (string) [pre_announcement | annexation | rezoning | adjacent] — Opportunity type
- `min_acres` (number) — Minimum acreage (default 10)

### get_convergence_alerts

Returns metros with highest infrastructure convergence confidence. ALERT tier (85%+) means multiple signal categories detected — high confidence that major infrastructure is coming.

Input:
- `tier` (string) [ALERT | WATCH | MONITOR] — Filter by tier
- `limit` (number) — Max results

### get_blind_spots

Returns metros ranked by the public-power / PUC blind-spot signal: blind_opportunity_score = convergence_breadth × puc_blind_share. State PUC dockets only regulate investor-owned utilities, so load served by municipal / co-op / public-utility-district / federal power is invisible to them. A high score means many distinct NON-PUC signal families (econ-dev sites, DOT capacity, interconnection queues, transmission projects, water, permits) are converging in a metro whose electric load is largely served by PUC-invisible public power — siting activity this platform sees but PUC-docket watchers structurally cannot. Each row carries per-family signal counts.

Input:
- `cbsa` (number) — Optional: restrict to a single metro by 5-digit CBSA code
- `min_breadth` (number) — Minimum distinct converging signal families (default 3)
- `min_blind_share` (number) — Minimum PUC-blind customer share, 0..1 (optional)
- `limit` (number) — Max results (default 50, cap 200)