---
title: "Aligned stock comparison (Pro)"
method: GET
path: "/api/v1/compare"
tags: ["Compare"]
---

# Aligned stock comparison (Pro)

`GET /api/v1/compare`

## Request

- Base URL: `https://foliofact.com`
- URL: `https://foliofact.com/api/v1/compare`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Two or more companies side by side — valuation, financials, fund and insider summaries.

## Query parameters

- `tickers` string, required
- `insider_window` '90d' | '1y' | 'all'

## Response `200`

Aligned columns

- Comparison
  - `submitted_tickers` string, required
  - `tickers` string[], required
  - `unknown_tickers` string[], required
  - `insider_window` '90d' | '1y' | 'all', required
  - `insider_window_label` string, required
  - `columns` ComparisonColumn[], required
    - `ticker` string, required
    - `valuation_basis` ValuationBasis, required
      - `statement_on` string, date, nullable, required
      - `shares_on` string, date, nullable, required
      - `price_on` string, date, nullable, required
      - `measurement` string, nullable, required
      - `estimated` boolean, required
      - `description` string, required
      - `unavailable_reason` string, nullable, required
      - `ev_unavailable_reason` string, nullable, required
      - `accession_number` string, nullable, required
      - `source_url` string, nullable, required
      - `mapping_sources` string[], nullable, required
      - `calculation_version` string, required
      - `cash_flow_period` string, nullable, required
    - `name` string, nullable, required
    - `listing` PublicListing, nullable, required: Verified first public trading event. Null means unknown; provider history and first 13F appearance do not establish a listing date.
      - `listed_on` string, date, required
      - `event_type` 'ipo' | 'direct_listing' | 'spin_off', required
      - `recently_listed` boolean, required: True from the listing date until its twelve-month anniversary.
      - `source_url` string, uri, required
      - `disclosure_note` string, required
    - `market_cap` integer, nullable, required: Market capitalization in whole US dollars.
    - `enterprise_value` integer, nullable, required: Enterprise value in whole US dollars.
    - `ocf_ev_yield` number, nullable, required: Operating-cash-flow yield in percentage points on a 0-100 scale.
    - `fcf_ev_yield` number, nullable, required: Free-cash-flow yield in percentage points on a 0-100 scale.
    - `price_basis_kind` 'daily_close' | 'intraday' | 'implied_13f', nullable, required
    - `valuation_observed_at` string, date-time, nullable, required
    - `financial_point` object, nullable, required
      - `label` string, required
      - `end_on` string, date, nullable, required
    - `fund_summary` FundComparisonSummary, required
      - `available` boolean, required
      - `holder_count` integer, nullable, required
      - `total_value` integer, nullable, required: Aggregate position value in whole US dollars.
      - `top_position` TopPosition, required
        - `ticker` string, nullable, required
        - `name` string, nullable, required
        - `value` integer, nullable, required: Position value in whole US dollars.
        - `percent_of_fund` number, nullable, required: Portfolio weight in percentage points on a 0-100 scale.
      - `top_share` number, nullable, required: Leading-holder share in percentage points on a 0-100 scale.
      - `period_range` string[], nullable, required
      - `move_counts` MoveCounts, required
        - `keeps` integer, required
        - `opens` integer, required
        - `adds` integer, required
        - `trims` integer, required
        - `exits` integer, required
      - `average_weight` number, nullable, required: Average portfolio weight in percentage points on a 0-100 scale.
      - `conviction_score` number, nullable, required: Conviction score in percentage points on a 0-100 scale.
    - `insider_summary` InsiderComparisonSummary, required
      - `available` boolean, required
      - `summary` InsiderAggregate, required
        - `buy_value` integer, required: Open-market purchases in whole US dollars.
        - `sell_value` integer, required: Open-market sales in whole US dollars.
        - `net_value` integer, required: Purchases minus sales in whole US dollars.
        - `buyer_count` integer, required
        - `seller_count` integer, required
        - `largest_trade` InsiderTransaction, required
          - `date` string, date, required
          - `filed_on` string, date, nullable, required
          - `ticker` string, nullable, required
          - `company` string, nullable, required
          - `owner_name` string, nullable, required
          - `owner_role` string, nullable, required
          - `transaction_code` string, required
          - `shares` integer, required: Share count.
          - `price` string, nullable, required: Base-10 decimal price string in US dollars; null when undisclosed.
          - `value` integer, required: Whole US dollars; zero can mean the filing did not disclose a usable price.
      - `coverage_date` string, date, nullable, required

## Other responses

- `403`: Structured error
- `422`: Structured error
- `429`: Rate limit exceeded
- `default`: Structured error

---

[API](https://skmtc.dev/foliofact/apis/foliofact-api.md) · [All operations](https://skmtc.dev/foliofact/apis/foliofact-api/llms.txt) · [OpenAPI document](https://skmtc.dev/foliofact/apis/foliofact-api/revisions/a92e927f23f4?raw)