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.

Using the Python SDK gives you direct access to your team of researchers. You can use all the methods documented in the API Reference and control the parameters such as effort level, which LLM to use, etc.

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:

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