# akkru_insider_transactions

Trades insiders report on SEC Form 4 (and Form 5), nested filing then transactions, with the insiders, footnotes and links to the filing. A trade's direction is its acquired_disposed_code (A or D). Rows failing a consistency check carry data_quality_flags and are left out unless include_anomalies is true; the count left out is reported.

## Actions

| Action | What it does |
|---|---|
| `list` | One company's (ticker or cik) and/or one insider's (insider_cik) filings. 30 credits per page. |
| `stats` | Totals over a date window for one company and/or insider, with the ids of every transaction counted. 40 credits plus 5 per 1,000 transactions counted. |
| `get` | Transactions by id (from stats), up to 100. 10 credits per 5 ids. |
| `insiders` | Everyone who filed a Form 4 for one company, one row per CIK, with roles, latest title and filing counts; gives the insider_cik the other actions take. 30 credits. |
| `types` | The transaction codes with their official names. Free. |
| `tickers` | The companies with Form 4 data, 500 per page. 30 credits per page. |
| `search` | Screen every company's trades with trade_filters and aggregate_filters. Pro plan or higher; 65-920 credits. |

A company outside your plan's coverage returns 403 and the call is still charged.

## Parameters

| Parameter | Type | Actions | Description |
|---|---|---|---|
| `ticker` | string | `list`, `stats`, `insiders` | Company ticker, e.g. "AAPL" (US), "000100" (Korea), "1332" (Japan), "VIRI_F" (Europe), "600519_CN" (China A-share); any symbol the company has traded under. |
| `cik` | string | `list`, `stats`, `insiders` | Company SEC CIK, digits, e.g. "320193"; any CIK the company has filed under. Give ticker or cik, not both. |
| `insider_cik` | string | `list`, `stats` | Insider SEC CIK, digits (from action "insiders"). |
| `transaction_code` | array of string | `list`, `stats` | SEC transaction codes to keep, e.g. ["P", "S"] (up to 20; action "types" lists them). Unknown codes are dropped and reported in _warnings. |
| `transaction_form_type` | string | `list` | Only "4" or only "5". |
| `relationship` | array of string | `list`, `stats`, `insiders` | list, stats: the role on the filing, any of "is_director", "is_officer", "is_ten_percent_owner", "is_other". insiders: a role ever reported, any of "ever_director", "ever_officer", "ever_ten_percent_owner", "ever_other". |
| `include_unresolved_amendments` | boolean | `list`, `stats` | true: include amendments that could not be matched to their original filing. |
| `exclude_likely_merged` | boolean | `list`, `stats` | true: leave out filings whose amendment match is only probable. |
| `include_anomalies` | boolean | `list`, `stats` | true: include rows that fail a consistency check (left out by default). |
| `start_date` | string | `stats`, `search` | Window start, transaction date "YYYY-MM-DD". |
| `as_of_date` | string | `stats`, `search` | Window end, transaction date "YYYY-MM-DD" (not in the future); filings submitted after it are left out too. |
| `method` | string | `stats` | "ad" (default): totals by acquired_disposed_code; "ps": P as a buy and S as a sell, only those two codes. One of `ad`, `ps`. |
| `is_derivative` | boolean | `stats` | true: derivative rows only; false: non-derivative rows only. |
| `ids_page` | integer | `stats` | Page of transaction_ids in the stats response (default 1). |
| `ids_page_size` | integer | `stats` | transaction_ids per page, 1-1,000 (default 200). |
| `transaction_ids` | array of integer | `get` | Transaction ids from action "stats" (1-100). |
| `tickers` | array of string | `search` | Only these companies (up to 100); any symbol a company has traded under. Default: every company. |
| `exclude_tickers` | array of string | `search` | Leave these companies out (up to 100). |
| `sectors` | array of string | `search` | Only companies in these sectors (names from akkru_metrics action "catalog"). Pro plan or higher. |
| `trade_filters` | object | `search` | Trade-level filters: transaction_code, relationship, is_derivative, principal_amount_not_shares, include_anomalies, exclude_likely_merged, include_unresolved_amendments, and up to 8 conditions {field, op, value} on transaction_value, price_per_share, shares, own_pct_change, split_adjusted_shares or split_adjusted_price. |
| `aggregate_filters` | array of object | `search` | Company-level conditions (up to 8) {metric, op, value} on value_acquired, value_disposed, net_value, shares_acquired, shares_disposed, net_shares, txn_count, txn_count_acquired, txn_count_disposed, max_txn_value_acquired, max_txn_value_disposed or distinct_insiders. Operators for both: >, >=, <, <=, between ([low, high]). |
| `group_by_ticker` | boolean | `search` | true (default): one row per company; false: one row per transaction. |
| `sort_by` | string | `search` | Grouped: ticker or txn_count. One row per transaction: transaction_date, filing_date, transaction_value, shares, price_per_share, own_pct_change, split_adjusted_shares or split_adjusted_price. |
| `sort_order` | string | `search` | "desc" (default) or "asc". |
| `page` | integer | `list`, `get`, `tickers`, `search` | Page number, from 1; the response's next_page gives the next one. |
| `page_size` | integer | `list`, `get`, `tickers`, `search` | list, get: filings per page; search: rows per page, with page times page_size at most 500; tickers: companies per page, up to 500. |
| `detail` | string | `list`, `stats`, `get`, `search` | Response detail: "full" (default) returns the most detail available; "light" leaves out the bulkiest fields, such as breakdown lists; "minimal" returns the values with only what defines them. All three are charged the same. One of `full`, `light`, `minimal`. |

## Examples

```json
{"action": "list", "ticker": "AAPL", "transaction_code": ["P", "S"], "page_size": 5}
```

```json
{"action": "stats", "ticker": "AAPL", "start_date": "2025-01-01"}
```

```json
{"action": "get", "transaction_ids": [123456, 123457]}
```

```json
{"action": "insiders", "ticker": "AAPL", "relationship": ["ever_officer"]}
```

```json
{"action": "types"}
```

```json
{"action": "tickers", "page": 1}
```

```json
{"action": "search", "start_date": "2026-04-01", "trade_filters": {"transaction_code": ["P"]}, "page_size": 10}
```