/api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/historyTime series of position events for a holder-issuer pair.
Time series of position events for a holder-issuer pair.
10 tokensSince v3.1.0
Why use this
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).
Common use case
Build ownership change timeline charts.
Event-sourced position timeline for a (holder, issuer) pair — every contributing event (Form 4 transaction, 13F snapshot, 13D/G filing) in chronological order with the post-event position. Powers the position-history chart on holder pages.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| 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. | 7f1a2b30-c4d5-46e7-9f01-23456789abcd |
| issuer_cik | path | required | — | — | Issuer CIK (the company being held). Accepts both 10-char zero-padded and unpadded forms. | 0000320193 |
| 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. | 2026-01-01 |
| endDate | query | optional | — | — | Inclusive upper bound on `eventDate`. Format ISO `YYYY-MM-DD`. Default: no upper bound (up to today). | 2026-04-01 |
| 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. | FORM_4 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| holderUuid | string | no | Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping. |
| issuerCik | string | no | Issuer CIK echoed back in 10-char zero-padded form regardless of input. |
| events | array | no | 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 | no | 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 | no | 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 | no | 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 | no | 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 | yes | 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 | no | 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 | yes | 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). |
Sample response
·
- "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd"
- "issuerCik": "0000320193"
- "events":
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).