# Position Tracking — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 19e9dd55
> Fetch this file at: https://uat.finradarapi.com/llms/position-tracking.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Position Tracking

Unified position tracking across Form 4, 13F, and 13D/G with event-sourced ledger and point-in-time calculations.

### GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}

Calculate current ownership position for a holder in an issuer.

**Token cost:** 10 tokens per call

**Response fields:**
- `holderUuid` (string): Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping is correct.
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker.
- `currentShares` (number): Net shares held by this holder in this issuer as of `asOf`. Positive = long position; 0 = position fully exited (still returned for audit trail). Computed from the event-sourced ledger replay, NOT looked up from a single filing — combines 13F base + Form 4 deltas. Split-adjusted to most recent split for clean cross-time comparison.
- `currentPercent` (number (nullable)): Estimated `percent_of_class` when computable from the most recent 13D/13G assertion in the ledger replay. Null when only 13F + Form 4 sources contribute (since 13F doesn't carry percent-of-class — only an aggregate value). Below 5% positions typically have null `currentPercent` since they're not subject to 13D/G disclosure.
- `sourceFormTypes` (array): Array of form types that contributed to the ledger-replay calculation (e.g. `["13F-HR", "4", "4", "13D/A"]`). Order matches chronological replay order. Use to audit the position derivation and surface 'last-13D-was-N-quarters-ago' staleness signals to consumers.
- `asOf` (string): ISO-8601 UTC timestamp of the MOST RECENT filing contributing to the position calculation (i.e. the high-water-mark of the ledger replay). Echoes the `asOfDate` query parameter when one was passed; otherwise reflects the latest contributing filing's `filedAt`. Use to detect position staleness — if `asOf` is months old, the ledger has no fresh signal.
- `firstObservedAt` (string): ISO-8601 UTC timestamp of the EARLIEST filing contributing to the position. Useful for tenure metrics — `asOf - firstObservedAt` is roughly the holder's holding-period in this issuer. Berkshire's AAPL position has `firstObservedAt` around 2016-Q1 (when the 13F first surfaced the position).

**Since:** v3.1.0

**Utility:** Compute the current (or as-of-date) ownership position of a unified holder in an issuer by REPLAYING THE EVENT-SOURCED LEDGER: take the most recent 13D/13G or 13F assertion as the base position, then apply Form 4 transaction deltas chronologically forward to today. Solves the per-holder-per-issuer 'what's their current position?' question without forcing the customer to manually replay 30+ filings. Returns the source form types contributing to the calculation so you can audit the derivation. Pair with `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history` for the time-series version of the same calculation. The right endpoint when you need a single-number answer like 'how many AAPL shares does Berkshire hold right now?'

**Use case:** Get point-in-time ownership estimate with confidence scoring.

**Parameters:**
- `holder_uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker. Lookup via `GET /api/v1/ownership/holders` with the `q` search parameter. UUIDs are stable across re-runs for the same `(cik, name)` cluster.
- `issuer_cik` (path, required): Issuer CIK (the company being held). Accepts both 10-char zero-padded form and unpadded. Returns 404 when no filings exist linking this holder to this issuer.
- `asOfDate` (query, optional): Compute position AS OF this date (ISO `YYYY-MM-DD`). Default is today. The ledger replays only filings with `filedAt <= asOfDate`. Useful for historical reconstruction — 'what was Berkshire's AAPL position on Q4 2024 close?' Returns same shape as today-calculation; does NOT mark-to-market the price.

**Sample response:**
```json
{
  "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "issuerCik": "0000320193",
  "issuerTicker": "AAPL",
  "currentShares": 905560000,
  "currentPercent": 5.84,
  "sourceFormTypes": [
    "13F",
    "13D"
  ],
  "asOf": "2026-04-15T20:14:32.000Z",
  "firstObservedAt": "2016-05-16T20:14:32.000Z"
}
```

### GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history

Time series of position events for a holder-issuer pair.

**Token cost:** 10 tokens per call

**Response fields:**
- `holderUuid` (string): Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping.
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `events` (array): Array of position events sorted by `eventDate ASC` (oldest first — chart-friendly ordering). Mixes transactional events (`sharesDelta` set) and assertion events (`sharesDelta` null, `postEventShares` is a snapshot value). Empty array when no events match the filters.
- `events[].eventDate` (string): ISO `YYYY-MM-DD` event date — for Form 4 this is the trade date; for 13F-HR it's the quarter-end (`period_of_report`); for 13D/G it's the filing's reported event date (which may pre-date `filedAt`). The chart x-axis.
- `events[].sourceFormType` (string): Canonical form type of the source filing — `4`, `13F-HR`, `13D`, `13G`, plus amendment variants. Use to color-code chart events (Form 4 = transaction dot, 13F = snapshot line, 13D = annotation marker).
- `events[].accessionNumber` (string): SEC accession number of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to the form-type-specific filing-detail endpoint to drill into the underlying filing.
- `events[].action` (string): Event action label — one of `"buy"`, `"sell"`, `"snapshot"`, `"13D filed"`, `"13G filed"`, `"13D amendment"`, etc. Use for chart-tooltip labels and timeline-row icons. `snapshot` is the canonical action for 13F quarterly assertions.
- `events[].sharesDelta` (number (nullable)): Share-count delta this event contributed to the running position. Positive = position increased (Form 4 buy); negative = position decreased (Form 4 sell). NULL for snapshot/assertion events (13F-HR, 13D, 13G) where the source filing reports a level rather than a delta — for those rows, only `postEventShares` is meaningful.
- `events[].postEventShares` (number): Cumulative position after this event was applied. For transactional events (`sharesDelta` set): `prior_position + sharesDelta`. For snapshot events (`sharesDelta` null): the AS-FILED level reported on the source filing (which becomes the new ledger baseline). Always non-negative.
- `events[].postEventPercent` (number (nullable)): Percent-of-class after this event when computable. Set on 13D/G assertion events (which carry `percent_of_class`). Null on Form 4 events (since Form 4 doesn't typically carry a percent reading) and on 13F events (since 13F doesn't carry percent — only an aggregate value).

**Since:** v3.1.0

**Utility:** The chart-ready time-series view of one holder's position in one issuer — every contributing event (Form 4 transaction, 13F quarterly snapshot, 13D/G filing) in chronological order with the post-event position. Drives the position-history chart on holder-detail pages and the 'show me how Berkshire's AAPL stake evolved over 8 years' workflow. Each event carries `sharesDelta` (for transactional events — buys/sells) OR a snapshot indicator (for assertion events — 13F quarter-ends, 13D filings). The right endpoint when you need the time-series (use `/positions/{holder_uuid}/issuer/{issuer_cik}` for the single-number current-state version of the same data).

**Use case:** Build ownership change timeline charts.

**Parameters:**
- `holder_uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker. Lookup via `GET /api/v1/ownership/holders` with the `q` search parameter. Stable across linker re-runs for the same `(cik, name)` cluster.
- `issuer_cik` (path, required): Issuer CIK (the company being held). Accepts both 10-char zero-padded and unpadded forms.
- `startDate` (query, optional): Inclusive lower bound on `eventDate`. Format ISO `YYYY-MM-DD`. Default: no lower bound (full history back to first observed event). Useful for narrowing chart x-axis to recent periods.
- `endDate` (query, optional): Inclusive upper bound on `eventDate`. Format ISO `YYYY-MM-DD`. Default: no upper bound (up to today).
- `sourceType` (query, optional): Filter to one source-form-type — `SC_13D`, `SC_13G`, `FORM_4`, or `FORM_13F`. Default returns all event types blended. Use `FORM_4` to see only the discrete buy/sell events; use `FORM_13F` to see only the quarterly snapshot points.

**Sample response:**
```json
{
  "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "issuerCik": "0000320193",
  "events": [
    {
      "eventDate": "2026-04-15",
      "sourceFormType": "13D",
      "accessionNumber": "0001193125-26-001234",
      "action": "13D filed",
      "sharesDelta": null,
      "postEventShares": 905560000,
      "postEventPercent": 5.84
    }
  ]
}
```

### GET /api/v1/ownership/positions/issuer/{issuer_cik}/holders

All holders of an issuer from position events, deduplicated via unified_holders.

**Token cost:** 5 tokens per call

**Response fields:**
- `issuer_cik` (string): Echoed issuer CIK in 10-character zero-padded form.
- `issuer_ticker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker.
- `as_of` (string): ISO-8601 UTC timestamp of the latest contributing event across all holders. Use to verify staleness (>30 days warrants a refresh during 13F filing windows).
- `holders` (array): Array of unified-holder rows for this issuer. Order: by `shares_held` DESC (largest holders first). Deduplicated via Phase 47 unified-holder layer — a fund that filed both 13F and 13D for the same position appears as ONE row, not two.
- `holders[].holder_uuid` (string): Phase 47 unified-holder UUID.
- `holders[].name` (string): Canonical holder name.
- `holders[].cik` (string (nullable)): Primary 10-char zero-padded holder CIK.
- `holders[].type` (string): Holder classification — `individual` / `institution` / `group`.
- `holders[].shares_held` (integer): Latest known share count for this holder. NOT split-adjusted server-side (preserves the as-filed view per Phase 52 redirect convention) — for split-adjusted aggregation queries use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/company-data/ticker-research/get-tickers-ticker-fund-trends) instead.
- `holders[].percent_of_class` (number (nullable)): Latest known percent of class held (0.0-100.0 decimal). Null on Form-4-only holders where the underlying filing did not include a class-percentage calculation.
- `holders[].sources` (array): Array of source-flag strings indicating which SEC reporting regimes contributed to this position — e.g. `["13F"]` (13F filer only), `["13D", "13F"]` (filed both), `["Form 4"]` (Section 16 insider only). Multi-source positions are common for activist 13F filers who cross 5% (Buffett's BRK both files 13F and 13D for AAPL pre-2020).
- `holders[].last_event_at` (string): ISO-8601 UTC timestamp of the most-recent event affecting this position. The chronological sort key for 'recently active holders'.
- `meta` (object): Pagination block: `{ total: integer, limit: integer, offset: integer }`. `total` is the holder count for this issuer.

**Since:** v3.1.0

**Utility:** All holders of an issuer rolled up from the Phase 47 unified position-event ledger — combines 13F snapshots + 13D/13G filings + Form 4 insider holdings into one deduplicated holder list per issuer. Each row shows the latest position state for the (holder, issuer) pair, derived from the most-recent contributing event of any type. The single canonical 'who owns this stock?' rollup that spans all three SEC reporting regimes — institutional 13F filers, 5%+ beneficial owners (13D/G), and Section 16 insiders all in one list. Pair with [GET /api/v1/ownership/positions/issuer/{issuer_cik}/timeline](/docs/ownership-and-positions/unified-holders/get-ownership-positions-issuer-timeline) for the time-ordered event view.

**Use case:** WhaleWisdom-style institutional-ownership-breakdown pages — show all funds + insiders + beneficial owners holding AAPL today, sorted by share count or percent of class. Also useful for 'find all activist 13D filers in Berkshire's portfolio' workflows (filter `holders[].type=group` and the source-flag list to `[13D]`).

**Parameters:**
- `issuer_cik` (path, required): Issuer CIK (the company being analyzed). Both 10-character zero-padded (`0000320193`) and short unpadded (`320193`) formats accepted. Returns 404 when no positions have ever been observed for the issuer (rare; typically only pre-IPO entities or de-registered issuers).

**Sample response:**
```json
{
  "issuer_cik": "0000320193",
  "issuer_ticker": "AAPL",
  "as_of": "2026-04-15T20:14:32Z",
  "holders": [
    {
      "holder_uuid": "f0e1d2c3-b4a5-9876-5432-10fedcba9876",
      "name": "VANGUARD GROUP INC",
      "cik": "0000884144",
      "type": "institution",
      "shares_held": 1380000000,
      "percent_of_class": 8.85,
      "sources": [
        "13F"
      ],
      "last_event_at": "2026-02-14T18:52:10Z"
    },
    {
      "holder_uuid": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "name": "BLACKROCK INC",
      "cik": "0001364742",
      "type": "institution",
      "shares_held": 1100000000,
      "percent_of_class": 7.05,
      "sources": [
        "13F",
        "13G"
      ],
      "last_event_at": "2026-02-14T17:24:05Z"
    },
    {
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983",
      "type": "institution",
      "shares_held": 300000000,
      "percent_of_class": 1.92,
      "sources": [
        "13F"
      ],
      "last_event_at": "2026-02-14T16:12:48Z"
    }
  ],
  "meta": {
    "total": 4218,
    "limit": 50,
    "offset": 0
  }
}
```

### GET /api/v1/ownership/positions/issuer/{issuer_cik}/timeline

Chronological events across all holders for one issuer.

**Token cost:** 5 tokens per call

**Response fields:**
- `issuer_cik` (string): Echoed issuer CIK in 10-character zero-padded form.
- `issuer_ticker` (string (nullable)): Resolved issuer ticker (canonical hyphen form).
- `events` (array): Array of position-events in REVERSE chronological order (most-recent first). Mixes Form 4 transactions, 13F snapshot deltas, 13D/G filings into one sorted feed.
- `events[].event_id` (string): Unique event identifier — composite of `(holder_uuid, source, accession_number, line_number)`. Stable across re-runs of the unified position-event ledger build.
- `events[].event_at` (string): ISO-8601 UTC timestamp of the event. For Form 4: trade execution date (or filing-acceptance if trade date is missing). For 13F: quarter-end period_of_report. For 13D/G: signature date or filing date (whichever is earlier).
- `events[].source` (string): Source-type — `Form 4` / `13F` / `13D` / `13G` / `13D/A` / `13G/A`.
- `events[].holder_uuid` (string): Phase 47 unified-holder UUID of the party affecting the position.
- `events[].holder_name` (string): Holder name at the time of the event.
- `events[].action` (string): Human-readable action summary — `"BUY 50,000 shares @ $175.25"` (Form 4 P transaction), `"13G filed at 5.2%"` (13G), `"Position increased to 7.1%"` (13D-A), `"13F-HR: position held 245,000 shares"` (13F snapshot).
- `events[].shares_after` (integer (nullable)): Post-event share count for the (holder, issuer) position. Null on 13D/G events that did not include explicit share counts.
- `events[].percent_after` (number (nullable)): Post-event percent of class held. Null on Form-4-only events without a class-percentage calculation.
- `events[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format.
- `meta` (object): Pagination + filter echo: `{ total: integer, limit: integer, startDate: string|null, endDate: string|null, source: string|null }`.

**Since:** v3.1.0

**Utility:** Time-ordered event feed across ALL holders for one issuer — every contributing event from the unified position-event ledger (Form 4 transactions, 13F snapshots, 13D/G filings) in reverse chronological order, with the post-event position state. The natural backend for 'show me all ownership activity for AAPL in the last 30 days' dashboards. Pair with [GET /api/v1/ownership/positions/issuer/{issuer_cik}/holders](/docs/ownership-and-positions/unified-holders/get-ownership-positions-issuer-holders) for the holder-rollup view of the same data.

**Use case:** Monitor all ownership activity for a specific company in chronological order — useful for compliance review, news-driven activity analysis ('did anyone trim their position around the Q4 earnings miss?'), and activist-tracking workflows ('show me every 13D filing on this issuer in the last 90 days').

**Parameters:**
- `issuer_cik` (path, required): Issuer CIK. Both 10-character zero-padded (`0000320193`) and short unpadded (`320193`) formats accepted.
- `startDate` (query, optional): Start date filter (ISO 8601 date). Returns events with `event_at >= startDate`. Omit for the full available history (typically 5+ years for established issuers).
- `endDate` (query, optional): End date filter (ISO 8601 date, inclusive). Pair with `startDate` for date-range filtering.
- `source` (query, optional): Filter by source-type — `Form 4` / `13F` / `13D` / `13G`. Omit for all sources.
- `limit` (query, optional, default: 100): Max events returned (1-500). Server caps at 500.

**Sample response:**
```json
{
  "issuer_cik": "0000320193",
  "issuer_ticker": "AAPL",
  "events": [
    {
      "event_id": "evt_a1b2c3d4_0",
      "event_at": "2026-04-15T20:14:32Z",
      "source": "13D",
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "holder_name": "BERKSHIRE HATHAWAY INC",
      "action": "13D filed at 5.4% of class",
      "shares_after": 845000000,
      "percent_after": 5.42,
      "accession_number": "0001193125-26-001234"
    },
    {
      "event_id": "evt_e5f6g7h8_0",
      "event_at": "2026-03-31T00:00:00Z",
      "source": "13F",
      "holder_uuid": "f0e1d2c3-b4a5-9876-5432-10fedcba9876",
      "holder_name": "VANGUARD GROUP INC",
      "action": "13F-HR: position held 1,380,000,000 shares",
      "shares_after": 1380000000,
      "percent_after": 8.85,
      "accession_number": "0000884144-26-001892"
    },
    {
      "event_id": "evt_i9j0k1l2_0",
      "event_at": "2026-02-12T14:35:00Z",
      "source": "Form 4",
      "holder_uuid": "b3c4d5e6-7f80-9abc-def0-123456789abc",
      "holder_name": "COOK TIMOTHY D",
      "action": "SELL 50,000 shares @ $175.25",
      "shares_after": 3284621,
      "percent_after": null,
      "accession_number": "0000320193-26-000056"
    }
  ],
  "meta": {
    "total": 1247,
    "limit": 100,
    "startDate": null,
    "endDate": null,
    "source": null
  }
}
```

### GET /api/v1/ownership/cross-reference/{holder_uuid}

Cross-system filing reference for a unified holder.

**Token cost:** 5 tokens per call

**Response fields:**
- `holder_uuid` (string): Echoed UUID.
- `name` (string): Canonical holder name.
- `form_4` (array): Array of Form 3/4/5 (Section 16 insider) filings the holder has been a party to, sorted by `filed_at DESC`. Empty array on holders who have never filed Section 16. Each entry: `{ accession_number: string, filed_at: string, issuer_cik: string, issuer_ticker: string|null, action: string }`.
- `form_13f` (array): Array of 13F-HR/NT filings the holder has filed, sorted by `period_of_report DESC`. Empty array on holders who have never filed 13F. Each entry: `{ accession_number: string, filed_at: string, period_of_report: string, position_count: integer, total_aum_usd: number }`. `period_of_report` is the calendar quarter-end (always calendar-aligned per SEC mandate).
- `form_13dg` (array): Array of Schedule 13D / 13G / 13D-A / 13G-A filings the holder has filed, sorted by `filed_at DESC`. Empty array on holders who have never filed 13D/G. Each entry: `{ accession_number: string, filed_at: string, form_type: string, issuer_cik: string, issuer_ticker: string|null, percent_of_class: number|null, purpose: string|null }`.
- `summary` (object): Cross-source rollup metadata: `{ total_filings: integer, form_4_count: integer, form_13f_count: integer, form_13dg_count: integer, first_filing_at: string, last_filing_at: string, unique_issuers: integer }`. The `unique_issuers` count rolls up issuers across all three source-types — useful for sizing the holder's coverage breadth (Berkshire ~75 unique issuers, BlackRock ~12K).

**Since:** v3.1.0

**Utility:** Cross-source filing rollup grouped by source-type — for one unified holder, returns separate `form_4[]`, `form_13f[]`, and `form_13dg[]` arrays so consumers can render per-source-type drill-down panels (e.g. 'Berkshire's Form 4 history (Buffett's personal trades) here, 13F portfolio history there, 13D activist positions in a third panel'). Differs from [GET /api/v1/ownership/holders/{uuid}/filing-history](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid-filing-history) which returns ONE merged chronological feed — use whichever shape is more natural for your UI.

**Use case:** Per-source-type drill-down panels on a holder profile page where the user wants to see Form 4 / 13F / 13D-G activity SEPARATELY (vs the merged-chronological feed from `/holders/{uuid}/filing-history`). Also useful for compliance audits that need 'show me ALL Section 16 filings from this entity, separately from their 13F/13D activity'.

**Parameters:**
- `holder_uuid` (path, required): Phase 47 unified-holder UUID. Look up via [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders). Returns 404 on unknown UUIDs.

**Sample response:**
```json
{
  "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "name": "BERKSHIRE HATHAWAY INC",
  "form_4": [],
  "form_13f": [
    {
      "accession_number": "0001067983-26-000037",
      "filed_at": "2026-02-14T16:12:48Z",
      "period_of_report": "2025-12-31",
      "position_count": 42,
      "total_aum_usd": 312485000000
    },
    {
      "accession_number": "0001067983-25-000189",
      "filed_at": "2025-11-14T17:03:21Z",
      "period_of_report": "2025-09-30",
      "position_count": 41,
      "total_aum_usd": 295712000000
    }
  ],
  "form_13dg": [
    {
      "accession_number": "0001193125-26-001234",
      "filed_at": "2026-04-15T20:14:32Z",
      "form_type": "SC 13D",
      "issuer_cik": "0000320193",
      "issuer_ticker": "AAPL",
      "percent_of_class": 5.42,
      "purpose": "Investment"
    }
  ],
  "summary": {
    "total_filings": 110,
    "form_4_count": 0,
    "form_13f_count": 102,
    "form_13dg_count": 8,
    "first_filing_at": "1999-11-15T17:00:00Z",
    "last_filing_at": "2026-04-15T20:14:32Z",
    "unique_issuers": 75
  }
}
```