---
title: "Run the analysis agent on a live question"
method: POST
path: "/agent/analyze"
tags: ["Agents"]
---

# Run the analysis agent on a live question

`POST /agent/analyze`

## Request

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

Orchestrate an end-to-end analysis of a live market question.

Pipeline: resolve the market (fetch a live Polymarket/Kalshi price when an
identifier is given) → gather evidence and forecast → compute the model-vs-market
edge → run any custom **skills** → recommend. Returns one structured report.

## Request body

- AgentAnalyzeRequest: Ask the analysis agent to work a live question end-to-end.
  - `question` string, nullable: Market question. Optional if a market identifier is given.
  - `platform` string, nullable: 'polymarket' or 'kalshi' to fetch a live price.
  - `market_platform` string, nullable: Prediction-market venue supplied by the forecasting UI.
  - `market_ident` string, nullable: Polymarket slug or Kalshi ticker supplied by the forecasting UI.
  - `market_url` string, nullable
  - `slug` string, nullable: Polymarket market slug.
  - `market_id` string, nullable: Polymarket numeric market id.
  - `ticker` string, nullable: Kalshi market ticker.
  - `description` string
  - `resolution_criteria` string
  - `categories` string[]
  - `news_articles` NewsArticle[]
    - `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.
  - `market_probability` number, nullable: Override market price (0..1 or 0..100) when not fetching.
  - `market_bid` number, nullable
  - `market_ask` number, nullable
  - `market_volume` number, nullable
  - `market_liquidity` number, nullable
  - `resolve_time` string, nullable
  - `variant` string
  - `evidence_top_k` integer
  - `skills` AgentSkill[]: Up to 5 custom skills to run.
    - `name` string, required: Short skill name, e.g. 'Base rate check'.
    - `instruction` string, required: What this skill should analyse.
  - `builtin_skills` boolean: Also run the built-in forecasting toolkit (base rate, scenario decomposition, red team, key drivers).
  - `ground_in_record` boolean: Condition the forecast on the model's own live track-record calibration.
  - `tool_loop` boolean: Use a ReAct tool-using loop (model plans + calls tools) instead of the fixed pipeline.
  - `benchmark_tools` boolean: When tool_loop=true, expose Foresea's market-research toolkit. place_trade and manage_notes are reserved for Foresea's scheduled trading agents and are not available over the API.
  - `benchmark_tool_names` string[], nullable: When benchmark_tools=true, restrict the exposed tool set to named Foresea tools -- e.g. a research-only call passes ['web_search', 'orderbook'], a pure-reasoning call passes [] (no tools, so the model must answer on its first turn). Unset exposes every tool available to the caller. Naming place_trade or manage_notes over the API is refused with 403.
  - `max_tool_steps` integer: Max tool calls in the loop.
  - `effort_tier` 'simple' | 'standard' | 'deep', nullable: How much analysis effort this question gets (evidence fetch depth, which built-in skills run, tool-loop step budget). Set explicitly to override; left unset, the server estimates it from the question.
  - `history` object[]: Prior conversation turns for follow-up context.
  - `conversation_steer` string: Optional per-conversation steering instruction.
  - `openrouter_api_key` string, nullable
  - `openrouter_model` string, nullable
  - `model` string, nullable
  - `provider_base_url` string, nullable
  - `ollama_base_url` string, nullable
  - `agent_profile_id` string, nullable: Private copied-agent recipe. Its research model and instructions are server-resolved.
  - `client_run_key` string, nullable: Caller-supplied idempotency key, stored on the durable AgentRun this request creates. If your own request times out waiting for a response, the run may still be progressing server-side -- look it up with GET /agent/runs?client_run_key=... instead of restarting.
  - `max_tokens` integer, nullable: Max output tokens for the agent tool loop and skills.

## Response `200`

Successful Response

- AgentReport: End-to-end analysis of a live question produced by the agent.
  - `question` string, required
  - `served_model_name` string, nullable: Exact upstream model that served the final agent response, when reported by the provider.
  - `pipeline` string[]: Ordered steps the agent ran.
  - `platform` string, nullable
  - `market_url` string, nullable
  - `outcome` string, nullable
  - `market_probability` number, nullable
  - `model_probability` number, nullable
  - `edge` number, nullable
  - `stance` string, nullable
  - `recommendation` string, required: `buy_yes`, `buy_no`, `hold`, or `no_market_price`.
  - `recommendation_detail` string
  - `confidence` number, nullable
  - `question_type` string
  - `thesis` string
  - `evidence_sources` EvidenceSource[]
    - `source` string, required: Publisher name.
    - `title` string, nullable: Article headline.
    - `url` string, nullable: Article URL.
    - `publish_date` string, nullable: ISO 8601 publish date.
    - `relevance_score` number, nullable: Relevance to the question (0–1).
  - `evidence_error` string, nullable
  - `skills` AgentSkillResult[]
    - `name` string, required
    - `output` string, required
    - `verdict` RedTeamVerdict: Structured classification of a Red team skill's own argument, from a separate follow-up call. Observational only -- nothing in the pipeline reads this to gate or adjust the forecast.
      - `credible` boolean, required: Whether the argument is well-supported by a real mechanism or evidence, not just contrarian restating.
      - `severity` 'low' | 'medium' | 'high', required: How much this argument should weigh against the forecast if credible.
  - `grounding` string, nullable: Track-record self-calibration note applied to the forecast.
  - `effort_tier` string, nullable: How much analysis effort this question got: simple, standard, or deep.
  - `tool_transcript` object[]: Tool calls + observations when the tool loop ran.
  - `tool_loop_steps` integer, nullable: Tool-call steps the loop actually ran, when tool_loop=true.
  - `tool_loop_truncated` boolean, nullable: True if the loop hit max_tool_steps without the model giving a final answer.
  - `tool_loop_tokens_used` integer, nullable: Total estimated tokens consumed across turns.
  - `tool_loop_output_tokens_used` integer, nullable: Estimated completion/output tokens consumed in the tool loop.
  - `agent_profile` AgentProfileReference: The profile snapshot that shaped one agent report, without private context.
    - `id` string, required
    - `source_agent_id` string, required
    - `model` string, required
    - `version` integer, required
    - `execution_mode` 'research_only', required
  - `live_trade_intent` LiveTradeIntent: A chat-to-terminal handoff for a human-reviewed live order. This is deliberately not an executable order: it contains no size or limit price, and the trading terminal must still fetch a fresh venue quote, create a durable `/trading/runs` record, and receive an explicit user confirmation before an exchange order can be submitted.
    - `platform` string, required
    - `ident` string, required
    - `action` string
    - `outcome` string, required
    - `market_url` string, nullable
    - `model_probability` number, required
    - `market_probability` number, required
    - `edge` number, required
    - `recommendation` string, required
  - `agent_run` AgentRunReference: The durable, private research run that produced an agent report.
    - `id` string, required
    - `status` 'running' | 'completed' | 'failed' | 'interrupted', required
    - `created_at` string, required
    - `updated_at` string, required

## 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)