Point-in-Time Universe
get_pit_universeUse this tool to answer questions about historical index membership — e.g. "Was Company X in the S&P 500 on date Y?" or "Which companies were in the Russell 2000 on 2010-01-01?" Use this INSTEAD OF search_companies when the question involves a specific historical date or whether a company was an index member in the past — search_companies only returns current membership and cannot answer historical questions.
Returns a survivorship-free universe valid on a given as_of_date (only companies that existed and were members on that exact date — no hindsight). Supports SP500, RUSSELL1000, RUSSELL2000, RUSSELL3000 via index_membership.parquet (accurate join/leave dates, [) interval semantics). To check one company, pass its ticker + the target date: present = was a member, absent = was not.
Returns per company: CIK, ticker, name, sector, industry, SIC code, and per-row confidence (high/medium/low). _meta.pit_safe is true only when every matched row is high-confidence — treat low-confidence rows with caution. sector is SIC-derived (GICS-aligned, not licensed GICS) — a screening bucket, not an authoritative label.
Use as the first step of a quantitative backtest before get_compute_ready_stream. Returns an empty array (with error detail) if the date is out of range or has no coverage. Available on every plan — sample returns the subset covered by the sample bucket.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Index filter. 'sp500' (~500 large caps), 'russell1000' (~1000 large/mid), 'russell2000' (~2000 small caps), 'russell3000' (~3000 broad market). Omit for no index filter (sector-only or full universe queries). | |
| limit | No | Maximum companies to return (1–3500). Defaults to 100. Universe is deduped to one row per CIK, so set near the index size (SP500 ~505, Russell 3000 ~3050). | |
| offset | No | Zero-based row offset for paging a large universe. At most 250 rows are inlined per call; when more match, the response carries a `truncation` envelope — pass its `next_offset` here (keeping the same `limit`) to fetch the next page. Defaults to 0. | |
| sector | No | Sector filter (case-insensitive substring) over the SIC-derived, GICS-aligned label (not licensed GICS — see tool description). E.g. 'Technology', 'Energy'. | |
| is_active | No | Filter to active (currently trading) companies only. Omit to include all. WARNING: setting this to true on a HISTORICAL query reintroduces survivorship bias — companies that were active on as_of_date but later went bankrupt or got acquired will be filtered out. Leave unset for true PIT backtests. | |
| as_of_date | No | Historical date (YYYY-MM-DD) for survivorship-free construction. Index queries use index_membership join/leave dates (entrants after the date excluded, later-removed members kept); sector queries use security valid_from/valid_to. Omit for the current universe. | |
| as_of_basis | No | Which date column drives historical construction. 'effective' (default) = effective_date/removal_date (first trading day; passive replication). 'announcement' = announcement_date/removal_announcement_date (S&P's public-announcement day; for inclusion-arb backtests) — rows with NULL announcement_date (mostly pre-2015) are skipped. | effective |
| include_share_classes | No | false (default) collapses to one row per CIK (index-provider convention — BRK counts once, not BRK-A + BRK-B). true returns every share-class row (GOOG and GOOGL separately) — for security-level analysis only. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| _meta | Yes | Provenance envelope — data lineage for every MCP response | |
| index | Yes | ||
| sector | Yes | ||
| coverage | Yes | ||
| companies | Yes | ||
| as_of_date | Yes | ||
| truncation | No | Present only when the inline-row cap withheld rows. Page with `next_offset` (keep the same `limit`) or pull the full set via get_compute_ready_stream. | |
| as_of_basis | Yes | ||
| coverage_gap | Yes | ||
| universe_size | Yes | ||
| survivorship_free | Yes | ||
| confidence_summary | Yes |