API Reference

Forecast any question about the future, one at a time or a table at a time. Ask what will happen, or ask about an upcoming decision. Two research operations sit alongside.

Every operation is a coroutine. The snippets below are fragments showing the call shape; run them inside asyncio.run(), or await them directly in a Jupyter notebook. Each operation's reference page opens with a complete, runnable example.

Forecasting

# The outcomes of a decision
result = await decision(input=decisions_df, alternatives_field="grant", context=about_us)

# A question about the future
result = await forecast(input=questions_df, forecast_type="binary")

decision forecasts the outcomes of a decision: the same outcome under each option, for example "if we give this organization nothing, $250k or $1M, how many lawmakers back its campaign by 2028?". The decision can be yours or anyone else's, and the outcome can be a probability, a number or a date. The options are researched together, so their differences reflect what the decision would cause. Full reference →

forecast takes a DataFrame of questions and produces a forecast and a rationale for each row: binary (a probability), numeric and date (percentile ranges), categorical (one probability per outcome) and thresholded (one probability per threshold). For a premise nobody chooses, a forecast can be made conditional. Full reference →

Accuracy is measured in public: live tournament standings and the BTF-3 leaderboard are at evals.futuresearch.ai, with datasets on Hugging Face (BTF-2, BTF-3). Every forecast draws on a shared world model.

Blog posts: Automating Forecasting Questions, arXiv paper

multi_agent

result = await multi_agent(
    task="Research the current state of formal verification for AI systems",
    input=pd.DataFrame(),
)

multi_agent answers one question with a team of web research agents. Each agent takes a different angle, then their findings are synthesized into one structured result. Pass an empty DataFrame for a standalone question. effort_level sets the research agents (low 3, medium 4, default medium); high runs 2 frontier agents for deeper but slower research. Or pass explicit directions to set the angles yourself. Set return_list=True to generate a list, with one output row per item.

Full reference → Guides: Research a Question with a Team of Agents Case Studies: Find Startups Selling to AI Labs

agent_map

result = await agent_map(task=..., input=df)

agent_map runs one web research agent on every row of a DataFrame in parallel. Each agent searches the web, reads pages, and returns structured results. The transform is live web research: agents fetch and synthesize external information to populate new columns. For a single question rather than a table, use multi_agent.

Full reference → Guides: Add a Column with Web Lookup

Deprecated operations

rank, classify, merge and dedupe are deprecated and will be removed from the SDK and the API. Existing calls keep working for now. For a label or a score per row, use agent_map with a response_model; there is no drop-in replacement for merging or deduplicating tables. For anything about the future, use forecast.