/api/v1/ownership/positions/issuer/{issuer_cik}/timelineChronological events across all holders for one issuer.
Chronological events across all holders for one issuer.
5 tokensSince v3.1.0
Why use this
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.
Common 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').
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. The natural backend for 'show me all ownership activity for AAPL in the last 30 days' dashboards and for activist-tracking workflows that need to spot 13D filings as they emerge. The action field is a human-readable summary that combines source-type semantics (P/S Form 4 codes, 13F position counts, 13D 5%-threshold language) into a single one-line view. For the holder-rollup view of the same data (deduplicated to one row per holder) use GET /api/v1/ownership/positions/issuer/{issuer_cik}/holders. For per-holder position history (a single holder's position evolution over time) use GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| issuer_cik | path | required | — | — | Issuer CIK. Both 10-character zero-padded (`0000320193`) and short unpadded (`320193`) formats accepted. | 0000320193 |
| 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). | 2026-01-01 |
| endDate | query | optional | — | — | End date filter (ISO 8601 date, inclusive). Pair with `startDate` for date-range filtering. | 2026-04-30 |
| source | query | optional | — | — | Filter by source-type — `Form 4` / `13F` / `13D` / `13G`. Omit for all sources. | 13F |
| limit | query | optional | 100 | — | Max events returned (1-500). Server caps at 500. | — |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| issuer_cik | string | no | Echoed issuer CIK in 10-character zero-padded form. |
| issuer_ticker | string | yes | Resolved issuer ticker (canonical hyphen form). |
| events | array | no | 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 | no | 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 | no | 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 | no | Source-type — `Form 4` / `13F` / `13D` / `13G` / `13D/A` / `13G/A`. |
| events[].holder_uuid | string | no | Phase 47 unified-holder UUID of the party affecting the position. |
| events[].holder_name | string | no | Holder name at the time of the event. |
| events[].action | string | no | 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 | yes | 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 | yes | Post-event percent of class held. Null on Form-4-only events without a class-percentage calculation. |
| events[].accession_number | string | no | SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. |
| meta | object | no | Pagination + filter echo: `{ total: integer, limit: integer, startDate: string|null, endDate: string|null, source: string|null }`. |
Sample response
·
- "issuer_cik": "0000320193"
- "issuer_ticker": "AAPL"
- "events":
- "meta":
- "total": 1247
- "limit": 100
- "startDate": null
- "endDate": null
- "source": null
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/issuer/{issuer_cik}/timeline?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).