form4api-mcp

get_transactions

Read-only

Instructions

Search SEC Form 4 insider transactions with rich filters: ticker, insider CIK, transaction code/category, date range, a dollar floor (min_value), institutional-ownership trend, and (Pro+) upper trade-size bounds plus post-trade return screening (1d/1w/1m/3m/6m, returns as fractions e.g. 0.05 = +5%). Returns transaction-level rows — shares, price, total value, transaction code, 10b5-1 flag, insider role flags. Use this for filtered or historical search across many companies/insiders; use get_recent_filings for an unfiltered live feed instead, or get_insider_transactions/get_company_insiders when you already have a specific insider or company. Free plan, including min_value; max_value/min_shares/max_shares/min_return_*/max_return_*/has_returns require Pro. Paginated, max 100/page, and paging depth is plan-limited (Free 20 pages, Starter 100, Pro+ unlimited) — for a bulk pull use the REST endpoint GET /v1/transactions/export (Business) instead of paging.

Input Schema

Name	Required	Description
`to`	No	End date, inclusive, format YYYY-MM-DD (e.g. 2026-12-31). Filters on transactionDate.
`cik`	No	Company CIK number — SEC's numeric filer identifier, e.g. 0000320193. Leading zeros optional.
`code`	No	Single SEC transaction code to filter to. P=open-market purchase, S=open-market sale, A=grant/award, M=option exercise, F=tax withholding on vesting, D=disposition to issuer, G=gift, C=conversion of derivative, J=other. Use `codes` instead to match more than one.
`from`	No	Start date, inclusive, format YYYY-MM-DD (e.g. 2026-01-01). Filters on transactionDate.
`page`	No	1-based page number. Defaults to 1. Paging depth is plan-limited: Free reaches page 20, Starter page 100, Pro and above unlimited; beyond that the call returns 402 with the upgrade path. If you need the full history rather than a page of it, the REST endpoint GET /v1/transactions/export (Business plan) streams the entire filtered set as CSV in one request.
`codes`	No	Comma-separated list of SEC transaction codes to include, e.g. "P,S" (see `code` for the letter meanings). Multi-code superset of `code`.
`ticker`	No	Stock ticker symbol, case-insensitive, e.g. AAPL or aapl. Also accepts a comma-separated list of up to 25 symbols (e.g. "AAPL,MSFT") to match any of them in one call; tokens are trimmed and upper-cased, empty tokens are ignored, and more than 25 symbols returns 400.
`category`	No	Include only one category of transactions. open_market = P/S (the signal most users want); grants = award/comp noise; derivatives = option exercises etc.
`filed_to`	No	Inclusive end of the filed-date window, format YYYY-MM-DD. Filters on Filing.FiledAt.
`per_page`	No	Results per page. Defaults to 20, maximum 100.
`max_value`	No	Maximum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored. Use min_value alone to screen by size on a free key.
`min_value`	No	Minimum trade value in USD (shares × price), inclusive. Available on every plan.
`filed_from`	No	Inclusive start of the filed-date window, format YYYY-MM-DD. Filters on Filing.FiledAt (when the filing became public), not transactionDate — the two can differ by days to weeks. Use this to replay disclosures in the order the market actually saw them.
`max_shares`	No	Maximum number of shares, inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored.
`min_shares`	No	Minimum number of shares, inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored.
`has_returns`	No	If true, only return transactions with at least one computed post-trade return horizon (any of 1d/1w/1m/3m/6m). Requires Pro plan or higher — omitted or ignored on Free.
`insider_cik`	No	Insider CIK number — SEC's numeric filer identifier, e.g. 0001214128. Leading zeros optional.
`significant`	No	If true, preset = open-market trades only, no 10b5-1 plan trades, no derivatives. The "just show me real discretionary buys and sells" filter. Explicit params override it.
`exclude_10b5`	No	If true, exclude pre-scheduled 10b5-1 plan trades. Recommended for signal analysis — filters out automatic, non-discretionary trades.
`exclude_codes`	No	Comma-separated list of SEC transaction codes to exclude, e.g. "A,M,F,G" to drop grants, option exercises, tax withholding and gifts.
`max_return_1d`	No	Maximum 1-day post-trade return as a fraction (e.g. -0.1 = -10%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`max_return_1m`	No	Maximum 1-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`max_return_1w`	No	Maximum 1-week post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`max_return_3m`	No	Maximum 3-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`max_return_6m`	No	Maximum 6-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`min_return_1d`	No	Minimum 1-day post-trade return, as a FRACTION not a percentage (0.05 = +5%), inclusive. Rows with no computed 1-day return are excluded. Requires Pro plan or higher — omitted or ignored on Free.
`min_return_1m`	No	Minimum 1-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`min_return_1w`	No	Minimum 1-week post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`min_return_3m`	No	Minimum 3-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`min_return_6m`	No	Minimum 6-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.
`exclude_category`	No	Exclude an entire category of transactions, e.g. exclude_category=derivatives drops all option-related rows.
`exclude_derivative`	No	If true, drop derivative-security rows — the cleanest single "no options" switch.
`inst_ownership_trend`	No	Filter by the trailing quarter-over-quarter trend in institutional (13F) ownership of the underlying company. No effect if institutional-ownership enrichment is disabled server-side; rows where the trend was suppressed for insufficient 13F coverage still match "stable".

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.9.7Oct 14, 2026

addedInput schema / properties / filed_from

Added value: +{
+  "description": "Inclusive start of the filed-date window, format YYYY-MM-DD. Filters on Filing.FiledAt (when the filing became public), not transactionDate — the two can differ by days to weeks. Use this to replay disclosures in the order the market actually saw them.",
+  "type": "string"
+}

addedInput schema / properties / filed_to

Added value: +{
+  "description": "Inclusive end of the filed-date window, format YYYY-MM-DD. Filters on Filing.FiledAt.",
+  "type": "string"
+}

changedInput schema / properties / ticker / description

Previous value: -"Stock ticker symbol, case-insensitive, e.g. AAPL or aapl."New value: +"Stock ticker symbol, case-insensitive, e.g. AAPL or aapl. Also accepts a comma-separated list of up to 25 symbols (e.g. \"AAPL,MSFT\") to match any of them in one call; tokens are trimmed and upper-cased, empty tokens are ignored, and more than 25 symbols returns 400."

Changed17 schema fields changedv1.9.6Aug 25, 2026

addedInput schema / properties / has_returns

Added value: +{
+  "description": "If true, only return transactions with at least one computed post-trade return horizon (any of 1d/1w/1m/3m/6m). Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "boolean"
+}

addedInput schema / properties / inst_ownership_trend

Added value: +{
+  "description": "Filter by the trailing quarter-over-quarter trend in institutional (13F) ownership of the underlying company. No effect if institutional-ownership enrichment is disabled server-side; rows where the trend was suppressed for insufficient 13F coverage still match \"stable\".",
+  "enum": [
+    "increasing",
+    "decreasing",
+    "stable"
+  ],
+  "type": "string"
+}

addedInput schema / properties / max_return_1d

Added value: +{
+  "description": "Maximum 1-day post-trade return as a fraction (e.g. -0.1 = -10%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / max_return_1m

Added value: +{
+  "description": "Maximum 1-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / max_return_1w

Added value: +{
+  "description": "Maximum 1-week post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / max_return_3m

Added value: +{
+  "description": "Maximum 3-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / max_return_6m

Added value: +{
+  "description": "Maximum 6-month post-trade return as a fraction, inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

changedInput schema / properties / max_shares / description

Previous value: -"Maximum number of shares, inclusive. Requires Pro plan or higher — omitted or ignored on Free."New value: +"Maximum number of shares, inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored."

changedInput schema / properties / max_value / description

Previous value: -"Maximum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — omitted or ignored on Free."New value: +"Maximum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored. Use min_value alone to screen by size on a free key."

addedInput schema / properties / min_return_1d

Added value: +{
+  "description": "Minimum 1-day post-trade return, as a FRACTION not a percentage (0.05 = +5%), inclusive. Rows with no computed 1-day return are excluded. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / min_return_1m

Added value: +{
+  "description": "Minimum 1-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / min_return_1w

Added value: +{
+  "description": "Minimum 1-week post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / min_return_3m

Added value: +{
+  "description": "Minimum 3-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

addedInput schema / properties / min_return_6m

Added value: +{
+  "description": "Minimum 6-month post-trade return as a fraction (0.05 = +5%), inclusive. Requires Pro plan or higher — omitted or ignored on Free.",
+  "type": "number"
+}

changedInput schema / properties / min_shares / description

Previous value: -"Minimum number of shares, inclusive. Requires Pro plan or higher — omitted or ignored on Free."New value: +"Minimum number of shares, inclusive. Requires Pro plan or higher — the whole call is rejected with 403 on Free/Starter, not silently ignored."

changedInput schema / properties / min_value / description

Previous value: -"Minimum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — omitted or ignored on Free."New value: +"Minimum trade value in USD (shares × price), inclusive. Available on every plan."

changedInput schema / properties / page / description

Previous value: -"1-based page number. Defaults to 1."New value: +"1-based page number. Defaults to 1. Paging depth is plan-limited: Free reaches page 20, Starter page 100, Pro and above unlimited; beyond that the call returns 402 with the upgrade path. If you need the full history rather than a page of it, the REST endpoint GET /v1/transactions/export (Business plan) streams the entire filtered set as CSV in one request."

Changed13 schema fields changedJul 14, 2026

changedInput schema / properties / cik / description

Previous value: -"Company CIK number"New value: +"Company CIK number — SEC's numeric filer identifier, e.g. 0000320193. Leading zeros optional."

changedInput schema / properties / code / description

Previous value: -"SEC transaction code. P=purchase, S=sale, A=award, M=option exercise, F=tax withholding, D=disposition"New value: +"Single SEC transaction code to filter to. P=open-market purchase, S=open-market sale, A=grant/award, M=option exercise, F=tax withholding on vesting, D=disposition to issuer, G=gift, C=conversion of derivative, J=other. Use `codes` instead to match more than one."

changedInput schema / properties / codes / description

Previous value: -"Comma-separated list of SEC transaction codes to include, e.g. \"P,S\". Multi-code superset of `code`."New value: +"Comma-separated list of SEC transaction codes to include, e.g. \"P,S\" (see `code` for the letter meanings). Multi-code superset of `code`."

changedInput schema / properties / from / description

Previous value: -"Start date in ISO 8601 format, e.g. 2026-01-01"New value: +"Start date, inclusive, format YYYY-MM-DD (e.g. 2026-01-01). Filters on transactionDate."

changedInput schema / properties / insider_cik / description

Previous value: -"Insider CIK number"New value: +"Insider CIK number — SEC's numeric filer identifier, e.g. 0001214128. Leading zeros optional."

changedInput schema / properties / max_shares / description

Previous value: -"Maximum number of shares. Pro plan or higher."New value: +"Maximum number of shares, inclusive. Requires Pro plan or higher — omitted or ignored on Free."

changedInput schema / properties / max_value / description

Previous value: -"Maximum trade value in USD (shares × price). Pro plan or higher."New value: +"Maximum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — omitted or ignored on Free."

changedInput schema / properties / min_shares / description

Previous value: -"Minimum number of shares. Pro plan or higher."New value: +"Minimum number of shares, inclusive. Requires Pro plan or higher — omitted or ignored on Free."

changedInput schema / properties / min_value / description

Previous value: -"Minimum trade value in USD (shares × price). Pro plan or higher."New value: +"Minimum trade value in USD (shares × price), inclusive. Requires Pro plan or higher — omitted or ignored on Free."

changedInput schema / properties / page / description

Previous value: -"Page number for pagination"New value: +"1-based page number. Defaults to 1."

changedInput schema / properties / per_page / description

Previous value: -"Results per page (max 100)"New value: +"Results per page. Defaults to 20, maximum 100."

changedInput schema / properties / ticker / description

Previous value: -"Stock ticker symbol, e.g. AAPL"New value: +"Stock ticker symbol, case-insensitive, e.g. AAPL or aapl."

changedInput schema / properties / to / description

Previous value: -"End date in ISO 8601 format, e.g. 2026-12-31"New value: +"End date, inclusive, format YYYY-MM-DD (e.g. 2026-12-31). Filters on transactionDate."

First observedv1.0.0Jul 11, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint, so the description carries plan/auth behavior: which params are Free vs Pro, that Pro-gated params cause a 403 rejection rather than silent ignoring, and that paging depth is plan-limited with a 402 beyond the cap. It also states the row contents returned and the date-vs-filed-date distinction, adding context well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with verb+resource before the filter inventory, and every clause carries operational value (plan gating, alternatives, bulk path). It is dense and somewhat long, with pagination and the export fallback stated twice, so it is efficient rather than flawless.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 33-parameter tool with no output schema, the description covers the return shape, plan requirements, pagination limits, error codes, and sibling routing. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description groups the filters and clarifies the fraction convention (0.05 = +5%), but this is already documented per-parameter in the schema, so it adds little meaning beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (SEC Form 4 insider transactions), then enumerates the filter dimensions it supports. It explicitly names the siblings it is not (get_recent_filings, get_insider_transactions, get_company_insiders), so an agent can disambiguate without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit selection rule: use this for filtered/historical multi-company search, use get_recent_filings for an unfiltered live feed, and use the insider/company tools when an entity is already known. It also routes bulk pulls to the REST export endpoint, which is a concrete when-not-this-tool instruction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_transactions

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools