---
title: "Stream a conversational forecasting response"
method: POST
path: "/predict/stream"
tags: ["Inference"]
---

# Stream a conversational forecasting response

`POST /predict/stream`

## Request

- Base URL: `https://foresea.ink` (the document declares no server; this is the origin it was published from)
- URL: `https://foresea.ink/predict/stream`
- Auth: none declared

Stream model output as server-sent events, for all question types.

Delta events carry raw text chunks as they arrive so the UI can render the
rationale progressively. The final ``done`` event contains the same fully-
parsed ``PredictResponse`` shape that ``/predict`` returns, including
structured fields (``predicted_answer``, ``confidence``, etc.) for binary,
numeric, and multiple-choice questions.

## Request body

- PredictRequest: Input payload for a single forecasting prediction.
  - `question` string, required: The forecasting question to evaluate. It should ask about a future or otherwise resolvable event, option, quantity, or date.
  - `description` string: Extended background context that clarifies what the question is asking.
  - `resolution_criteria` string: Full venue conditions and measurement source used to resolve the forecast.
  - `categories` string[]: Topic tags (e.g. `['Economics', 'United States']`).
  - `news_articles` NewsArticle[]: Pre-fetched venue or caller news articles to preserve as evidence. When `attach_evidence` is true, fresh retrieved news is merged with them.
    - `title` string, nullable: Article headline.
    - `summary` string, nullable: Short human-written summary.
    - `summary_llm` string, nullable: LLM-generated summary.
    - `text` string, nullable: Full article body text.
    - `source` string, nullable: Publisher name (e.g. Reuters).
    - `credibility` object, nullable: Credibility score breakdown.
    - `frs` object, nullable: Future-Resolution Statement metadata.
    - `url` string, nullable: Canonical article URL.
    - `authors` unknown
    - `publish_date` string, nullable: ISO 8601 publish timestamp.
    - `keywords` unknown
    - `relevance_score` number, nullable: Cosine similarity to the question (0–1).
    - `search_query` string, nullable: Query used to retrieve this article.
  - `variant` string: Prompt variant that controls the reasoning instruction style. See the variant table in the Overview section.
  - `attach_evidence` boolean: If `true`, fetch live evidence and merge it with any supplied articles.
  - `evidence_top_k` integer: Maximum number of evidence articles to retrieve (1–100).
  - `evidence_detail` string: Evidence detail level in the model prompt. Use `summary` for scheduled multi-model runs to keep prompts bounded; default `full` preserves the interactive API behaviour.
  - `created_time` string, nullable: ISO 8601 question creation time.
  - `publish_time` string, nullable: ISO 8601 question publish time.
  - `resolve_time` string, nullable: ISO 8601 resolution deadline.
  - `days_open` integer, nullable: Days the question has been open.
  - `history` object[]: Prior conversation turns for multi-turn context, oldest first. Each item is `{"role": "user"|"assistant", "content": "..."}`.
  - `conversation_steer` string: Optional per-conversation steering instruction for tone, emphasis, or analytical stance. It cannot override safety rules or response contracts.
  - `question_type` string, nullable: Question type: `binary`, `multiple_choice`, `numeric`, or `date`. Set this explicitly for API clients; auto-detected from the question when omitted.
  - `options` string[]: Candidate answers for `multiple_choice` questions (optional; the model can infer them).
  - `market_platform` string, nullable: Prediction market venue, e.g. `Polymarket`, `Kalshi`, `Manifold`, or `Metaculus`.
  - `market_url` string, nullable: URL for the prediction market being analyzed. Must start with `http://` or `https://`.
  - `market_outcome` string, nullable: Outcome whose market-implied probability is provided. Defaults to `Yes` for binary markets; set this to `No` or to a multiple-choice option label when needed.
  - `market_ident` string, nullable: Venue market id (Polymarket slug / Kalshi ticker). Lets Foresea fetch live odds when `market_probability` is omitted.
  - `market_probability` number, nullable: Current market-implied probability for `market_outcome`. Use 0-1, or pass a percentage from 0-100 and Foresea will normalize it. When omitted but the market is identifiable (`market_url` or `market_platform`+`market_ident`), Foresea fetches the current live odds.
  - `market_volume` number, nullable: 24-hour trading volume in USD. Populated automatically from live odds when the market is identifiable.
  - `market_liquidity` number, nullable: Total open interest / liquidity in USD. Populated automatically from live odds.
  - `market_price_change_24h` number, nullable: Price change in the last 24 hours (in probability points, -1..1). Populated automatically from live odds.
  - `market_bid` number, nullable: Current best bid (YES) in probability units (0..1). Kalshi only; Polymarket uses the mid price.
  - `market_ask` number, nullable: Current best ask (YES) in probability units (0..1). Kalshi only.
  - `market_last_trade_price` number, nullable: Last actual trade price (0..1). More reliable than resting bid/ask in thin markets. Populated automatically.
  - `market_price_change_7d` number, nullable: 7-day price change in probability points (-1..1). Reveals slow drift that 24h misses. Populated automatically.
  - `market_resolution_source` string, nullable: Who resolves the market (e.g. UMA oracle, Kalshi team). Affects how much to trust the market price.
  - `market_no_sub_title` string, nullable: What the NO outcome represents (Kalshi). Useful when the question wording is ambiguous.
  - `market_expected_expiration_time` string, nullable: When the venue expects to settle (Kalshi). May differ from trading close date.
  - `market_floor_strike` unknown
  - `market_cap_strike` unknown
  - `market_price_history` object[], nullable: Recent price points for this market, newest first. Each entry: {ts: ISO timestamp, probability: float 0..1, volume?: float, liquidity?: float, bid?: float, ask?: float}. Up to 8 entries. Shown to the model as market-trajectory context so it can detect price and tradability changes that the current price alone would hide.
  - `forecast_history` object[], nullable: Prior Foresea forecast snapshots for the same market, newest first. Used by scheduled re-forecasts so repeat forecasts are stateful updates, not independent stateless calls.
  - `openrouter_api_key` string, nullable: User-supplied OpenRouter API key. When set, this request is routed through OpenRouter using `openrouter_model` instead of the server's default provider.
  - `openrouter_model` string, nullable: OpenRouter model ID (e.g. `openai/gpt-4o`, `anthropic/claude-3.5-sonnet`).
  - `model` string, nullable: Optional alternate server-hosted model to forecast with, from the SCADS allowlist (for example `gpt-oss-120b`, `scads-alias-reasoning`, `kimi-k2.7-code`). Uses the server's own key — no BYOK needed. Powers the multi-model paper-trading comparison.
  - `provider_base_url` string, nullable: Optional OpenAI-compatible chat-completions endpoint (e.g. `https://api.openai.com/v1/chat/completions`). When set with `openrouter_api_key` + `openrouter_model`, the request goes to your own endpoint instead of OpenRouter. Must be public HTTPS.
  - `chat_mode` boolean: When `true`, skips the forecast output template entirely. The model responds in plain natural language with no structured JSON.
  - `effort_tier` 'simple' | 'standard' | 'deep', nullable: How much reasoning effort the model call uses, when the provider supports it (best-effort; unsupported providers ignore it). Set explicitly to override; left unset, no reasoning-effort hint is sent.
  - `max_tokens` integer, nullable: Optional per-request generation cap. The server still clamps this to its configured model limit.
  - `ollama_base_url` string, nullable: Base URL of an Ollama instance, e.g. `http://localhost:11434`. No API key required. Cloud-metadata hosts are blocked; for foresea.ink the instance must be reachable from the server.

## Response `200`

Server-sent events containing model text deltas and a final PredictResponse payload.

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/foresea/apis/foresea-intelligence-api.md) · [All operations](https://skmtc.dev/foresea/apis/foresea-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/foresea/apis/foresea-intelligence-api/revisions/b03e49f4385d?raw)