spoken-alpha 0.1.0

Python SDK for the Spoken Alpha API — structured earnings-call data for AI agents.

spoken-alpha · Python SDK

Structured earnings-call data for AI agents.

Full API reference: https://api.spokenalpha.com/v1/docs

Note: The PyPI package is spoken-alpha (hyphen). The npm scope uses an underscore (@spoken_alpha/sdk) — see sdks/README.md for the reason.

Install

pip install spoken-alpha

Quick start

from spoken_alpha import Client

with Client(api_key="sa-...") as client:
    ir = client.companies.get_ir_page("AAPL")
    print(ir.ir_page.confidence)

    for call in client.companies.list_earnings_calls("AAPL").iterate_all():
        print(call.call_date, call.fiscal_quarter)

    summary = client.calls.get_summary("call_AAPL_2026Q2_earnings")
    print(summary.summary)

The API key can also be set via the SPOKEN_ALPHA_API_KEY environment variable — Client() picks it up automatically.

Async

from spoken_alpha import AsyncClient

async with AsyncClient() as client:
    results = await client.language_patterns.search("supply chain normalization")
    for r in results.results:
        print(r.ticker, r.snippet)

Error handling

from spoken_alpha import Client, SpokenAlphaNotFoundError, SpokenAlphaRateLimitError

with Client() as client:
    try:
        ir = client.companies.get_ir_page("ZZZZ")
    except SpokenAlphaNotFoundError:
        print("ticker not found")
    except SpokenAlphaRateLimitError as e:
        print(f"rate limited; resets at {e.reset_at}")

All exceptions inherit from SpokenAlphaAPIError. Subclasses:

Class	HTTP
SpokenAlphaAuthError	401
SpokenAlphaForbiddenError	403
SpokenAlphaNotFoundError	404
SpokenAlphaValidationError	422
SpokenAlphaRateLimitError	429
SpokenAlphaScaffoldedError	503 (planned endpoint)
SpokenAlphaServerError	5xx
SpokenAlphaTimeoutError	timeout
SpokenAlphaNetworkError	network

Configuration

Client(
    api_key="sa-...",          # default: SPOKEN_ALPHA_API_KEY env var
    base_url="https://...",    # default: https://api.spokenalpha.com/v1
    timeout=30.0,              # seconds, default 30
    max_retries=2,             # auto-retry on 5xx, default 2
)

License

MIT