Python SDK

Just want to use FutureSearch? Go to FutureSearch, add it to Claude.ai or Claude Code. This guide is for developers using the Python SDK.

The Python SDK runs the same forecasts as the app, from your own scripts. Ask what will happen, including the outcomes of your decisions, and control effort and batching yourself. Every method is in the API Reference.

Python SDK with pip

pip install futuresearch

Requires Python 3.12+.

Important: be sure to supply your API key when running scripts:

export FUTURESEARCH_API_KEY=sk-cho...
python3 example_script.py

Quick example: a decision. One outcome, forecast under each option:

import asyncio
from pandas import DataFrame
from futuresearch.ops import decision

decisions = DataFrame([
    {
        "question": "How many sitting parliamentarians will be listed on ControlAI's campaign statement on December 31, 2028?",
        "grant": ["$0 (no grant)", "$250k", "$1M"],
    },
])

ABOUT_US = (
    "We are a family foundation deciding this quarter how much to give ControlAI. "
    "The gift would be unrestricted and announced publicly, and no other funder is "
    "waiting on our decision."
)


async def main():
    result = await decision(
        input=decisions,
        context=ABOUT_US,
        alternatives_field="grant",
        forecast_type="numeric",
        output_field="parliamentarians",
        units="parliamentarians",
    )
    print(result.data[["question", "percentiles", "rationale"]])


asyncio.run(main())

Doing nothing is usually one of the options, and the decision does not have to be yours. context carries what the forecaster cannot look up, including facts about you.

A question about the world works the same way, with forecast():

import asyncio
import pandas as pd
from futuresearch.ops import forecast

questions = pd.DataFrame([
    {
        "question": "Will the US Federal Reserve cut rates by at least 25bp before July 1, 2027?",
        "resolution_criteria": "Resolves YES if the Fed announces a cut of 25bp or more at any FOMC meeting between now and June 30, 2027.",
    },
])

async def main():
    result = await forecast(input=questions, forecast_type="binary")
    print(result.data[["question", "probability", "rationale"]])

asyncio.run(main())

Dependencies

The MCP server requires uv (if using uvx) or pip (if installed directly). The Python SDK requires Python 3.12+.

Sessions

Every operation runs within a session. Sessions group related operations together and appear in your FutureSearch session list.

When you call an operation without an explicit session, one is created automatically. For multiple related operations, create an explicit session:

import pandas as pd
from futuresearch import create_session
from futuresearch.ops import forecast

async with create_session(name="AI Lab Milestones") as session:
    # All operations share this session
    ipo_dates = await forecast(
        session=session,
        input=pd.DataFrame([
            {"question": "When will Anthropic IPO?"},
            {"question": "When will OpenAI IPO?"},
        ]),
        forecast_type="date",
        output_field="ipo_date",
    )

    valuations = await forecast(
        session=session,
        input=pd.DataFrame([
            {"question": "What will Anthropic's valuation be at IPO?"},
            {"question": "What will OpenAI's valuation be at IPO?"},
        ]),
        forecast_type="numeric",
        output_field="valuation",
        units="billions USD",
    )

Grouping operations in one session keeps their tasks tracked together.

Listing Sessions

Retrieve all your sessions programmatically with list_sessions:

from futuresearch import list_sessions

sessions = await list_sessions()
for s in sessions:
    print(f"{s.name} ({s.session_id}), created {s.created_at:%Y-%m-%d}")

Each item is a SessionInfo with session_id, name, created_at, and updated_at fields.

Async Operations

For long-running jobs, use the _async variants to submit work and continue without blocking:

import pandas as pd
from futuresearch import create_session
from futuresearch.ops import forecast_async

questions = pd.DataFrame([
    {"question": "Will Anthropic IPO before OpenAI?"},
])

async with create_session(name="Background Forecast") as session:
    task = await forecast_async(
        session=session,
        task="Forecast the listed AI lab milestone questions.",
        input=questions,
        forecast_type="binary",
    )

    # Task is now running server-side
    print(f"Task ID: {task.task_id}")

    # Do other work...

    # Wait for result when ready
    result = await task.await_result()

    # Or cancel if no longer needed
    await task.cancel()

Print the task ID. If your script crashes, recover the result later:

from futuresearch import fetch_task_data

df = await fetch_task_data("12345678-1234-1234-1234-123456789abc")

Operations

See Also

• Guides: step-by-step tutorials
• Case Studies: worked examples
• Skills vs MCP: integration options