Python SDK

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

Using the Python SDK gives you direct access to the utilities for directing 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 classify

companies = pd.DataFrame([
    {"company": "Airtable",}, {"company": "Vercel",}, {"company": "Notion",}
])

async def main():
    result = await classify(
        task="""Qualifies if: 1. Remote-friendly, 2. Senior, and 3. Discloses salary""",
        categories=["yes", "no"],
        input=companies,
    )
    print(result.data.head())

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:

from futuresearch import create_session
from futuresearch.ops import classify, rank

async with create_session(name="Lead Qualification") as session:
    # Get the URL to view this session in the dashboard
    print(f"View at: {session.get_url()}")

    # All operations share this session
    classified = await classify(
        session=session,
        task="Has a company email domain (not gmail, yahoo, etc.)",
        categories=["qualified", "unqualified"],
        input=leads,
    )

    ranked = await rank(
        session=session,
        task="Score by likelihood to convert",
        input=classified.data,
        field_name="conversion_score",
    )

The session URL lets you monitor progress and inspect results in the web UI while your script runs.

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}")
    print(f"  View: {s.get_url()}")

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:

from futuresearch import create_session
from futuresearch.ops import rank_async

async with create_session(name="Background Ranking") as session:
    task = await rank_async(
        session=session,
        task="Score by revenue potential",
        input=large_dataframe,
        field_name="score",
    )

    # 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