Python SDK

Use the Python SDK from scripts, services, or notebooks.

Install

Run these commands in a terminal.

Shell

mkdir polybridge-python-test
cd polybridge-python-test

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install polybridge httpx

Quick terminal test

This quick test uses the SDK for Search and REST for Forecast, so it works without an API key.

API key for higher usage

Without a key, the example uses anonymous limits. With a key, it uses higher API-key limits where supported. Do not put API keys in files you commit.

Shell

export POLYBRIDGE_API_KEY="your_api_key_here"

Create test_polybridge.py

This file runs Search first, then Forecast. Forecast can take longer than Search.

Python

import os
import httpx
from polybridge import PolyBridge

api_key = os.environ.get("POLYBRIDGE_API_KEY")

client_options = {
    "timeout": 10,
    "client_name": "python-quick-test",
}

if api_key:
    client_options["api_key"] = api_key

client = PolyBridge(**client_options)

print("Running Search...")

search_results = client.search(
    "Fed rate cut before September 2026",
    dimensions=["direct", "correlated"],
    top_k_per_dimension=3,
    filters={"status": "active"},
)

print({
    "request_id": search_results.request_id,
    "query": search_results.query,
    "total_markets": search_results.total_markets,
    "latency_ms": search_results.latency_ms,
})

for dimension, markets in search_results.results.items():
    print(f"\n{dimension}:")

    for market in markets[:3]:
        print(f"- {market.question}")

print("\nRunning Forecast...")
print("Forecast can take longer than Search.")

forecast_headers = {}
if api_key:
    forecast_headers["Authorization"] = f"Bearer {api_key}"

response = httpx.post(
    "https://api.polybridge.ai/v1/forecast",
    json={
        "question": "Will the Fed cut interest rates before September 2026?",
        "include_graph": False,
    },
    headers=forecast_headers,
    timeout=90,
)

response.raise_for_status()
forecast = response.json()

print({
    "request_id": forecast.get("request_id"),
    "question": forecast.get("question"),
    "probability": forecast.get("probability"),
    "confidence": forecast.get("confidence"),
    "confidence_interval": forecast.get("confidence_interval"),
    "latency_ms": forecast.get("latency_ms"),
    "error": forecast.get("error"),
})

print("\nReasoning:")
print(forecast.get("reasoning"))

print("\nMarkets used:")
for market in forecast.get("markets_used", []):
    print(f"- {market.get('question')}")

Run it

You should see Search results first, then a Forecast response. The example uses SDK Search and REST Forecast with a 90-second Forecast timeout.

Shell

python test_polybridge.py

Use in your code

Once the terminal test works, use the same client setup in your script, service, or notebook. Keep the API key in an environment variable. Do not hardcode it in source files.

If something fails

Check the error and fix the simplest cause first.

401: API key is invalid. Remove the key to use anonymous mode, or replace it with a valid key.
403: key does not have access for that operation.
429: wait before retrying or use an API key for higher usage.
Timeout: Forecast can take longer than Search.