API Documentation

Base URL: https://api.bullrundata.com

Authentication

Include your API key in every request via the X-API-Key header:

# cURL
curl -H "X-API-Key: brd_your_key_here" https://api.bullrundata.com/api/v1/dashboard/summary
# Python
requests.get("https://api.bullrundata.com/api/v1/dashboard/summary", headers={"X-API-Key": "brd_..."})
# JavaScript
fetch("https://api.bullrundata.com/api/v1/dashboard/summary", { headers: { "X-API-Key": "brd_..." } })

Rate Limits

Limits reset daily at midnight UTC. Check response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 2026-03-30T00:00:00.000Z

Error Responses

All errors return JSON with an error field. Common status codes:

401Unauthorized
{ "error": "Missing API key", "hint": "Pass your key via Authorization: Bearer <key>, X-API-Key header, or ?api_key= query param", "signup": "https://bullrundata.com/dashboard" }
429Rate Limited
{ "error": "Daily rate limit exceeded", "limit": 100, "reset": "2026-03-31T00:00:00.000Z", "upgrade": "https://bullrundata.com/pricing" }
400Bad Request
{ "error": "purchasePrice and monthlyRent are required" }

Dashboard

GET
/api/v1/dashboard/summary

One-call market intelligence — recession probability, regime, Fed stance, key metrics

GET
/api/v1/dashboard/snapshot

All indicators grouped by category (lightweight, no model calc)

Recession Model

GET
/api/v1/model/probability

Live recession probability with 15-indicator model

GET
/api/v1/model/probability/history?range=1y (1m, 3m, 6m, 1y, 2y, 5y)

Historical probability snapshots

Economic Indicators

GET
/api/v1/indicators?category, limit, include_change

All 35 latest indicators with weekly change data

GET
/api/v1/indicators/:name

Single indicator by FRED series ID (e.g. UNRATE, DFF)

GET
/api/v1/indicators/:name/timeseries?range=1y

Full time-series from FRED with min/max/change stats

GET
/api/v1/indicators/:name/history

Historical values from our database

GET
/api/v1/categories

List of indicator categories

Sector Rotation

GET
/api/v1/sectors/rotation

All 11 S&P sector ETFs ranked by momentum — leaders, laggards, defensive vs cyclical

Institutional Positioning

GET
/api/v1/institutional/tic

Foreign holdings of US Treasuries (TIC data from FRED)

GET
/api/v1/institutional/cftc

CFTC Commitments of Traders — institutional futures positioning

Webhook Alerts

POST
/api/v1/alerts/configure

Set threshold-based webhook alerts (checked every 6h)

GET
/api/v1/alerts/configured

List your configured alerts

DELETE
/api/v1/alerts/:id

Remove a webhook alert

Example Response

GET /api/v1/dashboard/summary

{ "timestamp": "2026-04-11T09:29:09.557241", "recession": { "probability": 34.2, "risk_level": "MODERATE", "risk_color": "yellow", "recommendation": "Mixed signals require caution.", "high_risk_indicators": [], "leading_probability": 34.2 }, "regime": { "market_regime": "mid_cycle", "fed_stance": "neutral", "fed_funds_rate": 3.64 }, "key_metrics": { "UNRATE": { "label": "Unemployment Rate", "value": 4.3, "unit": "%" }, "DFF": { "label": "Fed Funds Rate", "value": 3.64, "unit": "%" }, "VIXCLS": { "label": "VIX", "value": 22.28, "unit": "index" } }, "indicators_count": 33, "data_freshness": "2026-04-11T04:53:25.131000" }

Calculator Request Schemas

These calculator endpoints are available through the MCP server (for AI agents like Claude), not the REST API directly. Install via: npx @bullrundata/market-intelligence-mcp

POST/v1/calculators/investment-property

All fields except purchasePrice and monthlyRent are optional with sensible defaults.

{ "purchasePrice": 450000, // Required "monthlyRent": 2800, // Required "downPaymentPct": 20, // Default: 20 "interestRate": 7.0, // Default: 7.0 "loanTermYears": 30, // Default: 30 "vacancyRatePct": 8, // Default: 8 "annualPropertyTax": 5400, // Default: 0 "annualInsurance": 1800, // Default: 0 "monthlyHoa": 0, // Default: 0 "maintenancePct": 1, // Default: 1 (% of purchase price/yr) "propertyMgmtPct": 0, // Default: 0 (% of rent) "closingCostsPct": 3 // Default: 3 }

POST/v1/calculators/brrrr

All fields except purchasePrice, arv, and monthlyRent are optional.

{ "purchasePrice": 200000, // Required — acquisition price "arv": 320000, // Required — after repair value "monthlyRent": 2200, // Required "rehabCosts": 45000, // Default: 0 "closingCostsBuyPct": 3, // Default: 3 "holdingCosts": 5000, // Default: 0 (total during rehab) "vacancyRatePct": 8, // Default: 8 "annualPropertyTax": 3600, // Default: 0 "annualInsurance": 1400, // Default: 0 "propertyMgmtPct": 0, // Default: 0 "maintenancePct": 1, // Default: 1 "monthlyHoa": 0, // Default: 0 "monthlyUtilities": 0, // Default: 0 "monthlyOtherExpenses": 0, // Default: 0 "refiLtvPct": 75, // Default: 75 "refiRate": 7.0, // Default: 7.0 "refiTermYears": 30, // Default: 30 "refiClosingCostsPct": 2, // Default: 2 "useInitialLoan": false, // Default: false (cash purchase) "initialLoanAmount": 0 // Default: 0 }