Progress Monitoring

FutureSearch operations typically take 1–10+ minutes depending on dataset size and operation type. Both the Python SDK and the MCP tools provide progress monitoring so you can follow an operation as it runs.

What to Expect

Python SDK

To see progress updates while a task is running, use the print_progress callback:

from futuresearch import print_progress

result = await task.await_result(on_progress=print_progress)

Output:

 0/10   0% | 10 running
 2/10  20% |  8 running
 4/10  40% |  6 running
 6/10  60% |  4 running
 8/10  80% |  2 running
10/10 100%

You can also provide a custom on_progress callback for programmatic progress handling (see below).

MCP Tools

When you run a FutureSearch operation via MCP:

1. The tool returns immediately with a task_id
2. Progress updates appear every few seconds during execution
3. Results are saved as a CSV file when the operation completes
4. If you've installed the plugin, a desktop notification (macOS and Linux) tells you when it's done

The workflow:

futuresearch_forecast     →  start the operation, get a task_id
futuresearch_progress     →  check status (blocks for a few seconds, then returns progress)
futuresearch_progress     →  check again (the agent loops automatically)
futuresearch_results      →  download results when complete

The agents handle the polling loop automatically. You'll see progress in the conversation like:

Running: 20/50 complete, 30 running (45s elapsed)

And when it finishes:

Completed: 50/50 (0 failed) in 100s
...
Saved 50 rows to /path/to/output.csv

Python SDK Progress

For printing progress updates as a task runs, use the provided print_progress callback. For example, start a batch of date forecasts in the background, then follow it:

from pandas import DataFrame
from futuresearch import create_session, print_progress
from futuresearch.ops import forecast_async

async with create_session(name="IPO Dates") as session:
    task = await forecast_async(
        session=session,
        task="Forecast when each company will IPO.",
        input=DataFrame([
            {"question": "When will OpenAI IPO?"},
            {"question": "When will Anthropic IPO?"},
        ]),
        forecast_type="date",
        output_field="ipo_date",
    )
    result = await task.await_result(on_progress=print_progress)

Or provide a custom callback:

from futuresearch.generated.models import TaskProgressInfo

def my_progress_handler(progress: TaskProgressInfo):
    print(f"{progress.completed}/{progress.total} done, {progress.failed} failed")

result = await task.await_result(on_progress=my_progress_handler)

The callback receives a TaskProgressInfo object and only fires when the progress snapshot changes.