Forecast endpoint

Estimate the probability of a future event and review the market evidence.

Quick start

Call Forecast

Forecast works without a key at anonymous limits. Add an API key for higher usage. Forecast can take longer than Search. Use include_graph: false for a smaller quickstart response.

EndpointPOST /v1/forecast

Base URLhttps://api.polybridge.ai

AuthAnonymous or API key

Required accessNone for anonymous mode; forecast:read for API keys

OutputProbability, confidence, reasoning, and evidence

Anonymous Forecast (no key)

curl -sS -X POST "https://api.polybridge.ai/v1/forecast" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will the Fed cut interest rates before September 2026?",
    "include_graph": false
  }'

API-key Forecast (higher usage)

curl -sS -X POST "https://api.polybridge.ai/v1/forecast" \
  -H "Authorization: Bearer $POLYBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Will the Fed cut interest rates before September 2026?",
    "include_graph": false
  }'

A successful response includes probability, confidence, confidence_interval, reasoning, markets_used, latency_ms, and error.

Technical scope: forecast:read. Public endpoint: https://api.polybridge.ai/v1/forecast.

Request and response shape

Forecast returns probability, uncertainty, reasoning, and source-market traceability.

Request fields

questionrequired
Plain-language forecast question.
include_graphoptional
Set false to omit causal_graph and reduce response size. Request graph data only when you need the causal graph.

Response fields

probability
Forecast probability on a 0 to 1 scale. Always present; may be null when the question is rejected or cannot produce a forecast.
confidence
0 to 1 confidence score for the forecast output.
confidence_interval
Human-readable uncertainty range for the returned probability.
reasoning
Short explanation of the forecast and the supporting market evidence.
markets_used
Source-market traceability entries used to construct the forecast.
markets_used[].label
Evidence-role label inside the Forecast output, such as direct or proxy. This is not the Search dimensions request parameter.
markets_used[].question
Source market question or event label.
markets_used[].source
Source platform or market source label.
markets_used[].probability
Observed source-market probability when available.
markets_used[].url
Source market URL when available.
error
Error text when the request is rejected or no forecast can be produced.
metadata
Additional state details, including insufficient-data details when present.
causal_graph
Null when include_graph is false. Present only when requested and available.

Representative response

Values are illustrative. Exact probability and latency values change with market data and retrieval depth.

JSON response

{
  "request_id": "req_...",
  "question": "Will the Fed cut interest rates before September 2026?",
  "probability": 0.18,
  "confidence": 0.58,
  "confidence_interval": {
    "lower": 0.12,
    "upper": 0.24
  },
  "reasoning": "...",
  "causal_graph": null,
  "markets_used": [
    {
      "platform": "kalshi",
      "question": "Will the Federal Reserve cut rates before 2027?"
    }
  ],
  "latency_ms": 43867,
  "error": null
}

Forecast limits

Anonymous and API-key Forecast limits are separate. See Rate Limits for exact limits and retry header behavior. See the Production guide for timeouts, retries, errors, and request IDs.

View rate limits

Use markets_used for source evidence

Forecast returns markets_used so you can inspect the source markets behind the answer. These entries are supporting evidence, not trading instructions.

Labels inside markets_used, such as direct or proxy, describe evidence roles in the forecast output. They are not Search dimensions.

Endpoint behavior

Anonymous Forecast works when no Authorization header is sent.
Invalid auth returns an error. Remove the Authorization header to use anonymous mode where supported.
API keys need Forecast access.
Search-only keys cannot call Forecast with authentication.
probability is always present and may be null when the question is rejected or cannot produce a forecast.
Rejected questions can return 200 with probability: null, low confidence, an error, empty markets_used, and insufficient-data metadata.
Insufficient evidence can also return a fallback probability with metadata.
Set include_graph to false for a smaller response.
Set it to true only when you need the causal graph.
Forecast output is read-only information, not trading, orders, or financial advice.
Use Search first when you need to discover relevant markets before asking for a forecast.