valuein-sdk

Point-in-time, survivorship-free SEC EDGAR fundamentals for Python.

valuein-sdk gives you standardized financial statements from SEC filings back to 1993, queried with SQL in an in-process DuckDB. Every query sees only what was public at your as_of date: rows are filtered on accepted_at, the moment the SEC accepted the filing. Delisted, acquired and bankrupt companies stay in the data, and index membership is stored as historical spells, so a universe on a past date is the one that existed then. Every fact carries a fact_id and the accession number of the filing it came from, so any number can be traced back to its source document.

Documentation · Examples · SQL cookbook · Schema · Pricing

Install

pip install valuein-sdk

Python 3.10 or newer. Optional extras:

Quickstart: 30 seconds, no token

With no API key the client runs on the free sample tier: S&P 500 constituents over the last five years. There is nothing to sign up for.

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # no token: free sample tier
    print(client.resolve("AAPL"))  # ticker -> CIK, name, active flag

    revenue = client.run_template(
        "fundamentals_by_ticker",
        ticker="AAPL",
        form_types=["10-K"],
        metrics=["TotalRevenue", "NetIncome"],
    )
    print(revenue.head())

resolve returns one row per identifier with cik, symbol, name, is_active, valid_from, valid_to and matched_by. The template returns one row per fact: filing_date, report_date, period_end, fiscal_period, standard_concept, numeric_value, unit. A 10-K also carries prior-year comparatives, so use period_end, not report_date, to tell which year a number belongs to.

The same data from the shell:

valuein query 'SELECT symbol, name, sector FROM "references" WHERE is_active LIMIT 5'
valuein doctor   # plan, snapshot, tables and cache, with no secrets

To use your plan, set a token and run the same code:

export VALUEIN_API_KEY="your_token"   # or put it in a .env file

Three lines to a sourced income statement

from valuein_sdk import ValueinClient

client = ValueinClient()  # no token: free sample tier, as_of = now (UTC)
client.financials("AAPL").income  # fiscal years; .lineage traces every cell to its filing

financials() returns .income, .balance and .cash_flow (one row per standardized concept, one column per period end; freq="Q" for standalone quarters, "TTM" for trailing twelve months) and .lineage: one row per number with its fact_id, accession, form type, acceptance time, and when (if ever) a later filing changed it. .as_filed() shows each period as first reported, before any restatement; .explain("TotalRevenue", "2024-09-28") lists the facts behind one cell with EDGAR links.

Five lines to a factor tear sheet (Pro or Institutional)

from valuein_sdk import ValueinClient

client = ValueinClient()  # Pro or Institutional: the study reads daily prices
result = client.factor_backtest("gpoa", start="2015-01-01", end="2025-06-30", freq="QE")
report = result.tearsheet()  # IC decay, quantile curves, turnover, exclusions
report  # renders in a notebook; print(report.summary()) elsewhere

gpoa (gross profit over assets) is one of the library factors computed point in time from the filings (valuein_sdk.quant.describe_library() lists every formula). The backtest ranks the S&P 500 members of each quarter-end, trades one day later and pays 10 bps per unit traded; the tear sheet adds the information coefficient at one, two and four quarters, the return of each quantile, turnover and every exclusion.

Core ideas

Recipes

Every recipe runs on the free sample tier unless its heading says otherwise.

Get fundamentals for a ticker as of a date

from datetime import datetime, timezone

from valuein_sdk import ValueinClient

as_of = datetime(2024, 6, 30, tzinfo=timezone.utc)

with ValueinClient(as_of=as_of) as client:
    facts = client.read_table("fact", tickers="AAPL")

assert (facts["accepted_at"] <= as_of).all()  # nothing from after the cutoff

annual_revenue = (
    facts[(facts["standard_concept"] == "TotalRevenue") & (facts["fiscal_period"] == "FY")]
    .sort_values("accepted_at")
    .drop_duplicates("period_end", keep="last")  # latest value known on as_of
    .sort_values("period_end")
)
print(annual_revenue[["period_end", "numeric_value", "unit", "accepted_at", "fact_id"]])

read_table(table, tickers=...) fetches only that company's partition where the gateway serves one, and applies the same as_of filter. For backtests use numeric_value. With an explicit as_of (or a bundle), value_current, restated and restatement_count are recomputed from the filings accepted by the cutoff; value_as_filed is as exported. Without an explicit as_of they are the latest export's values.

Screen a universe without survivorship bias

from datetime import datetime, timezone

from valuein_sdk import ValueinClient

as_of = datetime(2023, 6, 30, tzinfo=timezone.utc)

with ValueinClient(as_of=as_of) as client:
    members = client.pit_universe("2023-06-30")  # S&P 500 on that date
    roe = client.run_query(
        """
        SELECT entity_id AS cik, value AS roe, period_end
        FROM ratio
        WHERE ratio_name = 'return_on_equity'
          AND fiscal_period = 'FY'
          AND period_end >= DATE '2022-06-30'  -- skip stale fiscal years
        QUALIFY row_number() OVER (PARTITION BY entity_id ORDER BY period_end DESC) = 1
        """
    )

screen = members.merge(roe, on="cik").nlargest(10, "roe")
print(screen[["cik", "ticker_at_date", "company_name", "roe", "period_end", "removal_date"]])
print("members later removed from the index:", members["removal_date"].notna().sum())

pit_universe returns one row per member with cik, company_name, ticker_at_date, sector, industry, effective_date and removal_date. Companies that left the index after the date are still members on it. The ratio table holds annual (fiscal_period = 'FY') and trailing-twelve-month ('TTM') rows: always filter on fiscal_period, or each company appears twice.

Backtest a factor (Pro or Institutional)

The quant layer needs daily prices (stock_price_daily), which only the Pro and Institutional plans carry.

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # reads VALUEIN_API_KEY
    result = client.factor_backtest(
        "return_on_equity",  # a ratio_name, a factor_scores column, or "mom_12m"
        start="2018-01-01",
        end="2024-12-31",
        freq="QE",
    )

print(result.summary())  # net and gross results, with the execution lag and cost used
print(result.mean_ic, result.ic_ir)  # rank information coefficient and its stability
print(result.quantile_summary())  # mean return per quantile

factor_backtest builds the universe at each rebalance date from index membership, reads each signal value as of that date, prices trades with a one-day execution lag (execution_lag=1) and charges 10 bps per unit traded (cost_bps=10.0). Positions in companies that delist are truncated, not dropped, and the summary lists what the study could not use. For a custom signal, run the three steps yourself:

from valuein_sdk import ValueinClient, backtest

with ValueinClient() as client:
    universe = client.universe("SP500", start="2018-01-01", end="2024-12-31", freq="QE")
    panel = client.signal_panel(universe, ratios=["return_on_equity", "debt_to_equity"])
    panel = client.forward_returns(panel)  # appends forward-return columns

panel["score"] = panel["return_on_equity"].rank(pct=True) - panel["debt_to_equity"].rank(pct=True)
result = backtest(panel, signal="score", quantiles=5, cost_bps=10.0)
print(result.summary())

From the shell: valuein backtest return_on_equity --start 2018-01-01 --end 2024-12-31 --freq QE. More recipes, including Monte Carlo and reproducible bundles, are in the Python SDK docs.

Prices and total return

Every tier has stock_price: one close per company at each fiscal period end and each completed month end, with the listing's total_return_index (splits and dividends reinvested).

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.stock_price("AAPL"))  # latest row
    monthly = client.run_query(
        """
        SELECT price_date, close, total_return_index
        FROM stock_price
        WHERE entity_id = '0000320193' AND observation = 'monthly'
        ORDER BY price_date
        """
    )

tri = monthly["total_return_index"]
print(f"12-month total return: {tri.iloc[-1] / tri.iloc[-13] - 1:.1%}")

Daily bars (stock_price_daily) are on Pro and Institutional:

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    bars = (
        client.prices(["AAPL", "MSFT"])
        .between("2024-01-01", None)
        .fields("close", "total_return")
        .to_pandas()
    )
    growth = client.total_return("AAPL", "2020-01-01", "2024-12-31")  # a fraction
    # one column per ticker
    panel = client.price_panel(["AAPL", "MSFT"], "2024-01-01", "2024-12-31")

Use a total-return basis (total_return_index, or the total_return field, which is the default) for return math. Raw close is not split-adjusted, and adding div_cash on top of a total-return series counts dividends twice. stock_price_daily has one row per security per day, so a company with two share classes has two rows per day; the SDK's price methods pick one bar per company per day for you.

Run a SQL template

The package ships parameterized SQL templates for common analyses: margins, free cash flow, Piotroski and Altman inputs, DuPont, restatement history, filing delays and more.

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.list_templates())
    fcf = client.run_template(
        "free_cash_flow",
        ticker="MSFT",
        form_types=["10-K"],
        start_date="2021-01-01",
        end_date="2025-12-31",
    )
print(fcf.head())

Pass parameters as keywords: run_template(name, **params). Every value is validated and quoted before the SQL is rendered: tickers such as "BRK-B" (share classes take a hyphen, as references spells them), XBRL frames such as "CY2023", "CY2024Q1" or "CY2024Q1I", fiscal_period one of Q1 to Q4, FY or TTM, and min_rank a percentile from 0.0 to 1.0. Common parameters you omit get defaults: form_types is ["10-K", "10-Q"], start_date five years ago, end_date today, and fiscal_period is "FY" for a template that reads ratio (otherwise "Q1"). Templates read the same point-in-time views as run_query. The smart-money templates (insider_buys, blockholders, top_institutional_holders, manager_portfolio) need Institutional; price_history, price_return and price_momentum_screen need Pro or Institutional. Copy-paste SQL patterns are in the SQL cookbook.

Raw SQL over the tables

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    current_members = client.run_query(
        """
        SELECT r.cik, r.symbol, r.name, r.sector
        FROM "references" r
        JOIN index_membership im ON im.cik = r.cik
        WHERE im.index_name = 'SP500'
          AND im.removal_date IS NULL
          AND r.is_active AND r.is_primary_ticker
        ORDER BY r.symbol
        """
    )
print(current_members.head())

• Tables mount on first use; a query can reference any table on your plan.
• "references" is an SQL keyword: keep the double quotes.
• run_query accepts one SELECT, WITH or EXPLAIN statement. Writes, file and network functions (read_parquet, glob, ...) and system catalogs are rejected.
• Other outputs: client.to_arrow(sql), client.to_polars(sql), and client.stream(sql) for results too large to hold in memory.
• Columns: client.get_schema("fact"), or the schema reference.

Verify a number back to the SEC filing

from valuein_sdk import FactRecord, ValueinClient

with ValueinClient() as client:
    facts = client.read_table("fact", tickers="AAPL")
    row = (
        facts[(facts["standard_concept"] == "TotalRevenue") & (facts["fiscal_period"] == "FY")]
        .sort_values(["period_end", "accepted_at"])
        .iloc[-1]
    )
    record = FactRecord.model_validate(row.to_dict())
    assert record.verify()  # fact_id matches the hash of its identity fields

    links = client.filing_links("AAPL", form_types=["10-K"])
    filing = links[links["accession_id"] == record.accession_id].iloc[0]

print(record.numeric_value, record.unit, record.period_end, record.fact_id)
print(filing["inline_viewer_url"] or filing["document_url"] or filing["sec_url"])

filing_links returns accession_id, form_type, filing_date, accepted_at and four EDGAR URLs per filing: inline_viewer_url (the Inline XBRL viewer; None for older filings), document_url, viewer_url and sec_url (the filing index, always present). compute_fact_id(entity_id, accession_id, concept, period_end, unit) computes the same hash as a plain function.

Track restatements

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    events = client.restatements(ticker="AAPL")

columns = ["period_end", "standard_concept", "first_value", "current_value", "disclosure_class"]
print(events[columns])

restatements() reads restatement_events on every tier, including with no token. Each row is one reported value that a later filing changed, with both accession numbers. disclosure_class is non_reliance (an 8-K Item 4.02 notice), amended (a 10-K/A or 10-Q/A) or undisclosed (the change appeared in a routine filing). Filter with disclosure_class=, severity= and min_delta_pct=.

Value a company and compare its peers

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    result = client.dcf("AAPL", stage1_growth_rate=0.08)
    table = client.peers("AAPL", n=5)

print(result.value_per_share, result.price, result.upside)
print(result.inputs_frame()[["name", "value", "fact_id", "accession_id"]])
print(table[["ticker", "is_subject", "pe_ratio", "roe"]])

dcf() is the MCP compute_dcf model (two-stage, free cash flow growing at your stage1_growth_rate, discounted at wacc, default 9%) computed in-process from the annual filings known at the client's as_of: nothing is sent to the MCP server. Every input (operating cash flow, capex, debt, cash, shares) carries the fact_id and filing it came from, defaults are flagged in result.assumptions, and projection_frame() and sensitivity_frame() give the year-by-year cash flows and a 5x5 grid. The growth rate is yours: the SDK never guesses one. peers() returns the subject first, then companies sharing its SIC code (S&P 500 members first), with the pipeline ratios as of the same date; pass peers=["MSFT", "GOOGL"] to choose them yourself. Formatted DCF and comps workbooks come from the Valuein Workspace or the MCP server's document tools.

Mirror a snapshot locally and pin it

client.sync(path) copies your plan's published table files into a directory, byte for byte, with a SHA-256 and the published ETag for each. Running it again moves only the tables that were republished: an unchanged table costs one body-free request. The mirror is also a research bundle, so it replays offline (an air-gapped host included) through the same point-in-time views, and a client pinned to its snapshot refuses to read any other.

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    report = client.sync("./valuein-mirror", tables=["references", "fact"])
print(report.snapshot, report.downloaded, report.bytes_downloaded)

with ValueinClient.from_bundle("./valuein-mirror") as offline:
    revenue = offline.run_query(
        "SELECT entity_id, period_end, numeric_value FROM fact "
        "WHERE standard_concept = 'TotalRevenue' LIMIT 5"
    )

with ValueinClient(snapshot=report.snapshot) as pinned:
    assert pinned.manifest()["snapshot"] == report.snapshot

The gateway serves only its current snapshot. Once it publishes the next one, the pinned client raises ValueinSnapshotError; the mirror still reads that snapshot offline. A sync writes nothing if the snapshot changes while it runs, so a mirror never mixes two.

Plans and tiers

The SDK reads your plan from your token; your code does not change between plans. The same token unlocks the bulk data API, the MCP server and the Valuein Workspace at your plan.

client.plan shows the active plan. get_plans() returns each plan's request rate limits from the gateway. Prices and history windows: valuein.biz/pricing.

Tables

The table list and every column come from the gateway's manifest at runtime: use client.tables() and client.get_schema(table), and client.manifest() for the snapshot and schema version you are reading. "PIT" means the view is filtered to accepted_at <= as_of.

Join keys: fact.entity_id, filing.entity_id and security.entity_id hold the CIK; fact.accession_id = filing.accession_id; index_membership.cik = "references".cik. There is no is_sp500 column: join index_membership instead. For one quarter of a cash-flow item use COALESCE(derived_quarterly_value, numeric_value), because Q2 and Q3 10-Qs report year-to-date figures.

API at a glance

Everything below imports from valuein_sdk. Every public method is typed and documented: help(ValueinClient.read_table) shows the arguments, the returned columns and the errors, and client.capabilities() returns the whole surface as a dictionary.

ValueinClient(as_of=None, api_key=None, gateway_url=None, tables=None, config=None, snapshot=None)

Also exported: backtest, factor_report, describe_library, to_alphalens, block_bootstrap, bootstrap, gbm and correlated_gbm (every simulation requires a seed), AlphaEngine with built-in factors such as ROE and GROSS_MARGIN, FactRecord, compute_fact_id, ValueinConfig and the ValueinError hierarchy; valuein_sdk.quant adds fama_macbeth, factor_returns, deflated_sharpe, probability_of_backtest_overfitting, haircut_sharpe and explain_cell. Every result object (BacktestResult, FactorReport, Financials, ScreenResult, VintageComparison, Study, FamaMacBethResult, SimulationResult) has summary(), to_frame(), to_dict() (strict JSON with params and provenance), plot() (needs valuein-sdk[research]), explain() and a notebook view. valuein_sdk.aio.AsyncValueinClient is the asyncio client.

Command line

The valuein command installs with the package and uses the same token rules.

Configuration

Environment variables

api_key=None (the default) reads the environment, api_key="" forces the sample tier, and any other string is used as the token.

ValueinConfig

from valuein_sdk import ValueinClient, ValueinConfig

config = ValueinConfig(memory_limit="8GB", threads=8, safe_mode=True)
with ValueinClient(config=config) as client:
    print(client.run_query('SELECT count(*) AS n FROM "references"'))

ValueinConfig is frozen: build a new one instead of changing a field.

Errors

Every SDK error subclasses ValueinError, and every message says what was wrong and how to fix it.

from valuein_sdk import ValueinClient, ValueinError

with ValueinClient() as client:
    try:
        client.run_query("DELETE FROM fact")
    except ValueinError as exc:
        print(type(exc).__name__, exc)  # ValueinValidationError and the reason

Using valuein-sdk with AI coding assistants

Paste this block into ChatGPT, Claude, Copilot or your agent's system prompt before asking for code that uses this library.

You are writing Python that uses the valuein-sdk library (PyPI: valuein-sdk).

Core API
- from valuein_sdk import ValueinClient
- Use it as a context manager:
  with ValueinClient(as_of=datetime(2024, 6, 30, tzinfo=timezone.utc)) as client: ...
- as_of must be a timezone-aware datetime. It defaults to now (UTC). Point-in-time tables
  (filing, fact, ratio, factor_scores, earnings_signals, stock_price, stock_price_daily
  and the smart-money tables) only show rows with accepted_at <= as_of.
- client.read_table(table, columns=None, limit=None, tickers=None) -> DataFrame
- client.run_query(sql) -> DataFrame. One SELECT, WITH or EXPLAIN statement. Values go
  inline as SQL literals. No read_parquet, no file or network functions.
- client.run_template(name, **params) -> DataFrame. Keyword arguments only.
  client.list_templates() lists the names.
- Also: client.resolve(identifiers), client.pit_universe("YYYY-MM-DD"),
  client.restatements(ticker=...), client.filing_links(ticker),
  client.stock_price(ticker), client.get_schema(table), client.tables(),
  client.capabilities().
- Quant layer, which needs a Pro or Institutional plan because it reads
  stock_price_daily: client.factor_backtest(signal, start=, end=, freq=),
  client.universe(), client.signal_panel(), client.forward_returns(),
  valuein_sdk.backtest().

Rules
1. Identify companies by CIK (10 digits, zero-padded, e.g. "0000320193"). Resolve a
   ticker once with client.resolve() and carry the CIK. Tickers get reused by other
   companies; CIKs do not.
2. Never invent, estimate or round a financial number. Only report values the library
   returned. If a query returns no rows, say so.
3. When you report a number from the fact table, cite its fact_id and accession_id. Use
   client.filing_links() for the SEC URL.
4. For backtests, set as_of and use fact.numeric_value. With an explicit as_of,
   value_current, restated and restatement_count are recomputed at the cutoff;
   without one they are the latest export's values.
5. In SQL, write "references" with double quotes (it is a keyword). Index membership is
   a JOIN on index_membership.cik; there is no is_sp500 column.
6. ratio has FY and TTM rows: always filter fiscal_period. A 10-K carries prior-year
   comparatives: group by period_end, not report_date. For one quarter of a cash-flow
   item use COALESCE(derived_quarterly_value, numeric_value).
7. For return math use total_return_index (or the SDK's total_return basis), never raw
   close, and never add div_cash on top of it.
8. client.get(table) skips the as_of filter. Use read_table or run_query instead.
9. To run SQL you generated, create the client with
   config=ValueinConfig(safe_mode=True).
10. SDK errors are ValueinError subclasses whose message states the fix. Read it before
    retrying.

The SDK is data plus local compute: every query, ratio and backtest runs in your process. Documents (DCF and comps workbooks, research briefs) come from the Valuein Workspace or the MCP server at https://mcp.valuein.biz/mcp, which agents that call tools instead of writing Python can use with the same token.

Examples and notebooks

Runnable examples live in the public valuein/valuein repository:

• Python scripts
• Jupyter notebooks

Notebook	Open
01 · Quickstart: your first query
02 · Fundamentals as of a date
03 · Survivorship-free screening
04 · Point-in-time factor backtest
05 · Prices and total return
06 · Restatements and how they were disclosed
07 · Smart money: insiders, 13F holders, advisers
08 · Verify a number against its SEC filing
09 · Use Valuein from an AI assistant
10 · Discounted cash flow valuation
11 · Piotroski F-score screen
12 · Earnings quality: the accrual anomaly
13 · Sector comparison: DuPont ROE
14 · Restatement alpha
15 · Capital allocation
16 · Filing delay

Support

• Documentation: valuein.biz/developers/python-sdk
• Questions and bugs: github.com/valuein/valuein/issues or support@valuein.biz
• A wrong number: client.report_issue("...", category="data_quality", fact_id=..., ticker=...) sends it to the Valuein team from your code, with no token needed.

License

Apache License 2.0. See the license text.

This library and its data are for research and education. Nothing here is financial advice.