Python SDK Guide

# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install valuein-sdk

# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install valuein-sdk

# optional — sample tier works without a key
echo 'VALUEIN_API_KEY="your_api_key"' >> .env

from valuein_sdk import ValueinClient, ValueinError

sql = """
SELECT
    r.symbol,
    r.name,
    f.fiscal_year,
    MAX(CASE WHEN standard_concept = 'Revenues'      THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'NetIncomeLoss' THEN numeric_value END) AS net_income,
    MAX(CASE WHEN standard_concept = 'EarningsPerShareDiluted' THEN numeric_value END) AS eps_diluted
FROM fact f
JOIN references r ON f.entity_id = r.cik
WHERE f.form_type = '10-K'
  AND r.symbol = 'AAPL'
GROUP BY r.symbol, r.name, f.fiscal_year
ORDER BY f.fiscal_year DESC
LIMIT 10
"""

try:
    with ValueinClient() as client:
        df = client.run_query(sql)
        print(df)
except ValueinError as e:
    print(f"Valuein error: {e}")

from valuein_sdk import ValueinClient, ValueinError

try:
    with ValueinClient() as client:
        # Connection check — no API key required
        print(client.health())     # {"ok": true, "latency_ms": 42}

        # Your account details
        print(client.me())         # {"plan": "growth", "status": "active", "email": "...", "createdAt": "..."}

        # Dataset snapshot metadata
        print(client.manifest())   # {"snapshot": "2026-03-26", "last_updated": "...", "tables": [...]}

        # List available table names
        print(client.tables())     # ["entity", "security", "filing", "fact", "valuation", "references", ...]

        # Download a full table as a DataFrame (no SQL needed)
        filing_df = client.get(table="filing")
        print(filing_df.head())

        # Run a named SQL template — kwargs only, raw values (the SDK quotes them safely)
        df = client.run_template("fundamentals_by_ticker", ticker="AAPL")
        print(df)
except ValueinError as e:
    print(f"Valuein error: {e}")

from valuein_sdk import ValueinClient, ValueinError

# What did investors KNOW about AAPL's FY2022 revenue as of Jan 1, 2023?
# Excludes any restatements or 10-K/A amendments filed after that date.
sql = """
SELECT
    r.symbol,
    f.fiscal_year,
    f.period_end,
    f.accepted_at,
    MAX(CASE WHEN standard_concept = 'Revenues'      THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'NetIncomeLoss' THEN numeric_value END) AS net_income
FROM fact f
JOIN references r ON f.entity_id = r.cik
WHERE f.form_type = '10-K'
  AND r.symbol = 'AAPL'
  AND f.accepted_at <= '2023-01-01'   -- Only facts known by this date
GROUP BY r.symbol, f.fiscal_year, f.period_end, f.accepted_at
ORDER BY f.fiscal_year DESC
LIMIT 10
"""

try:
    with ValueinClient() as client:
        df = client.run_query(sql)
        print(df[["fiscal_year", "period_end", "accepted_at", "revenue", "net_income"]])
except ValueinError as e:
    print(f"Valuein error: {e}")

from valuein_sdk import ValueinClient, ValueinError

# S&P500 companies with ROE > 20% and Debt/Equity < 1.0 in the latest fiscal year.
# Membership is resolved via index_membership (the references table has no
# is_sp500 flag — that snapshot column was dropped 2026-05-02).
sql = """
SELECT
    r.symbol,
    r.name,
    r.sector,
    ROUND(
        MAX(CASE WHEN standard_concept = 'NetIncomeLoss'        THEN numeric_value END) /
        NULLIF(MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END), 0),
        3
    ) AS roe,
    ROUND(
        MAX(CASE WHEN standard_concept = 'LongTermDebt'         THEN numeric_value END) /
        NULLIF(MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END), 0),
        3
    ) AS debt_to_equity,
    MAX(CASE WHEN standard_concept = 'EarningsPerShareDiluted' THEN numeric_value END) AS eps_diluted
FROM fact f
JOIN references r ON f.entity_id = r.cik
JOIN index_membership im ON im.cik = r.cik
WHERE f.form_type = '10-K'
  AND f.fiscal_year = 2024
  AND im.index_name = 'SP500'
  AND im.removal_date IS NULL
  AND r.is_active = TRUE
GROUP BY r.symbol, r.name, r.sector
HAVING roe > 0.20 AND debt_to_equity < 1.0
ORDER BY roe DESC
LIMIT 20
"""

try:
    with ValueinClient() as client:
        df = client.run_query(sql)
        print(df)
except ValueinError as e:
    print(f"Valuein error: {e}")

from valuein_sdk import ValueinClient, ValueinError

sql = "SELECT COUNT(*) AS total_facts FROM fact"

try:
    with ValueinClient() as client:
        df = client.run_query(sql)
        print(df)
except ValueinError as e:
    # ValueinError covers all SDK exceptions:
    #   - missing or invalid VALUEIN_API_KEY
    #   - rate limit exceeded for your plan tier
    #   - network or connection failures
    #   - malformed SQL or query execution errors
    print(f"Valuein error: {e}")