Python SDK Guide

pip install valuein-sdk

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 USING (entity_id)
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.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 by name + parameters
        name, tickers = "01_fundamentals_by_ticker", "'AAPL','MSFT','GOOGL'"
        df = client.run_template(name, tickers)
        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.knowledge_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 USING (entity_id)
WHERE f.form_type = '10-K'
  AND r.symbol = 'AAPL'
  AND f.knowledge_at <= '2023-01-01'   -- Only facts known by this date
GROUP BY r.symbol, f.fiscal_year, f.period_end, f.knowledge_at
ORDER BY f.fiscal_year DESC
LIMIT 10
"""

try:
    with ValueinClient() as client:
        df = client.query(sql)
        print(df[["fiscal_year", "period_end", "knowledge_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
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 USING (entity_id)
WHERE f.form_type = '10-K'
  AND f.fiscal_year = 2024
  AND r.is_sp500  = TRUE
  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.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.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}")