Agents

Run the analysis agent on a live question

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.

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

Request body

questionstring nullable

Market question. Optional if a market identifier is given.

platformstring nullable

'polymarket' or 'kalshi' to fetch a live price.

market_platformstring nullable

Prediction-market venue supplied by the forecasting UI.

market_identstring nullable

Polymarket slug or Kalshi ticker supplied by the forecasting UI.

market_urlstring nullable

slugstring nullable

Polymarket market slug.

market_idstring nullable

Polymarket numeric market id.

tickerstring nullable

Kalshi market ticker.

descriptionstring

resolution_criteriastring

categoriesstring[]

market_probabilitynumber nullable

Override market price (0..1 or 0..100) when not fetching.

market_bidnumber nullable

market_asknumber nullable

market_volumenumber nullable

market_liquiditynumber nullable

resolve_timestring nullable

variantstring

evidence_top_kinteger

builtin_skillsboolean

Also run the built-in forecasting toolkit (base rate, scenario decomposition, red team, key drivers).

ground_in_recordboolean

Condition the forecast on the model's own live track-record calibration.

tool_loopboolean

Use a ReAct tool-using loop (model plans + calls tools) instead of the fixed pipeline.

benchmark_toolsboolean

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_namesstring[] 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_stepsinteger

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.

historyobject[]

Prior conversation turns for follow-up context.

conversation_steerstring

Optional per-conversation steering instruction.

openrouter_api_keystring nullable

openrouter_modelstring nullable

modelstring nullable

provider_base_urlstring nullable

ollama_base_urlstring nullable

agent_profile_idstring nullable

Private copied-agent recipe. Its research model and instructions are server-resolved.

client_run_keystring 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_tokensinteger nullable

Max output tokens for the agent tool loop and skills.

Example request

{
  "news_articles": [
    {
      "publish_date": "2025-01-15T10:30:00Z",
      "relevance_score": 0.91,
      "source": "Reuters",
      "summary": "Federal Reserve officials signaled a more cautious approach to rate cuts...",
      "title": "Fed signals rate cuts may slow in 2025",
      "url": "https://reuters.com/example"
    }
  ]
}

Response

Successful Response

questionstring required

served_model_namestring nullable

Exact upstream model that served the final agent response, when reported by the provider.

pipelinestring[]

Ordered steps the agent ran.

platformstring nullable

market_urlstring nullable

outcomestring nullable

market_probabilitynumber nullable

model_probabilitynumber nullable

edgenumber nullable

stancestring nullable

recommendationstring required

buy_yes, buy_no, hold, or no_market_price.

recommendation_detailstring

confidencenumber nullable

question_typestring

thesisstring

evidence_errorstring nullable

groundingstring nullable

Track-record self-calibration note applied to the forecast.

effort_tierstring nullable

How much analysis effort this question got: simple, standard, or deep.

tool_transcriptobject[]

Tool calls + observations when the tool loop ran.

tool_loop_stepsinteger nullable

Tool-call steps the loop actually ran, when tool_loop=true.

tool_loop_truncatedboolean nullable

True if the loop hit max_tool_steps without the model giving a final answer.

tool_loop_tokens_usedinteger nullable

Total estimated tokens consumed across turns.

tool_loop_output_tokens_usedinteger nullable

Estimated completion/output tokens consumed in the tool loop.

Changes

No recorded changes to this operation across all 1 revision of this API.