Build with Harpoonist data

The Harpoonist REST API gives programmatic access to congressional and insider trade disclosures, security prices, filer profiles, the performance leaderboard, and your alert automation rules. All endpoints accept an X-API-Key header — no OAuth dance required.

Interactive API reference →

Quickstart

Mint a key at Account → API keys (requires an API plan), then make your first request:

curl -H "X-API-Key: hp_your_key_here" \
  "https://api.harpoonist.com/trades?limit=10"

That's it. The response is JSON — paginated with a next_cursor field when more results exist.

Authentication

Every request must include your API key in the X-API-Key request header. API keys are server-side secrets — keep them in environment variables and never include them in browser-side code or commit them to source control.

An invalid or inactive key returns 401 Unauthorized. A missing X-API-Key header returns the same status with code missing_api_key. Every error response includes a request_id you can quote to support:

{
  "error": {
    "code": "invalid_api_key",
    "message": "invalid or inactive API key",
    "request_id": "a1b2c3d4e5f6..."
  }
}

Keys are tied to your account and API plan. If your key is revoked or your API subscription lapses, requests return 401 until the key is regenerated or the subscription is renewed.

Endpoints

All endpoints are under https://api.harpoonist.com. The /alerts endpoints manage your automation alert rules (webhook, Discord, email) — the same rules you manage in the Harpoonist dashboard, scoped to the account that owns your API key.

Method	Path	Description
`GET`	`/trades`	List trades with cursor pagination and filters.
`GET`	`/trades/{id}`	Retrieve a single trade by ID.
`GET`	`/trades/export`	Bulk NDJSON export of all trades matching filters. API plan required. Counts as 1 request toward your monthly quota.
`GET`	`/securities/{ticker}`	Security profile: metadata and recent activity.
`GET`	`/securities/{ticker}/prices`	Daily close prices for the ticker.
`GET`	`/filers`	List all known filers (congress members, insiders).
`GET`	`/filers/{id}`	Filer detail: profile, stats, and recent trades.
`GET`	`/filers/{id}/activity`	Filer trading-activity analytics: buy/sell counts, notionals, top tickers, and monthly series.
`GET`	`/stats/leaderboard`	Performance leaderboard across tracked filers.
`GET`	`/stats/data-quality`	Coverage & freshness: per-source trade counts, ingestion lag, and parse rates.
`GET`	`/alerts`	List your automation alert rules (scoped to your API key).
`POST`	`/alerts`	Create an automation alert rule for your account (webhook / Discord / email).
`GET`	`/alerts/{id}`	Retrieve one of your alert rules.
`PATCH`	`/alerts/{id}`	Update one of your alert rules.
`DELETE`	`/alerts/{id}`	Delete one of your alert rules.

For full parameter references, response schemas, and live try-it panels, see the interactive API reference.

Rate limits

The API Personal plan allows 60 requests per minute per API key and 50,000 requests per month. Every API-key-authenticated response includes these headers:

Header	Description
`X-RateLimit-Limit`	Your key's request limit per minute.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Seconds until the rate limit window resets.
`X-Monthly-Quota-Limit`	Your plan's monthly request cap (resets on your billing anniversary).
`X-Monthly-Quota-Remaining`	Requests remaining in the current billing month.

When you exceed the per-minute limit, the API returns 429 Too Many Requests with code rate_limit_exceeded and a Retry-After header (same value as X-RateLimit-Reset) indicating how many seconds to wait before retrying.

When you exceed the monthly quota, the API returns 429 Too Many Requests with code monthly_quota_exceeded.

Helpful notes on rate limits

Requests that trigger a 429 still count toward your usage — the counter increments before the limit check. Keep this in mind when reading your usage figures.
These headers are designed for server-to-server use. Because API keys should never be used in browser code, the headers are not exposed to browser JavaScript across origins (CORS does not list them as safe-listed response headers).

Data windows

Plan	Data freshness	History window
API Personal	Real-time (as ingested)	Full history (2023→)

API keys require an active API Personal plan and deliver real-time data as ingested, with full history back to 2023.

Nothing in this documentation constitutes investment advice.

MCP — use Harpoonist in Claude

The Harpoonist MCP (Model Context Protocol) server lets AI assistants like Claude Desktop and Claude Code call Harpoonist data tools directly — no copy-paste, no manual API calls. Ask Claude to look up a filer, pull recent disclosures, or check the performance leaderboard and it queries the live API on your behalf.

The MCP server is mounted at /mcp on the Harpoonist API and uses the same bearer API key authentication as the REST API — no separate credentials needed.

Add to Claude Desktop

Paste the following into ~/Library/Application Support/Claude/claude_desktop_config.json (create the file if it does not exist), then replace hp_your_api_key with your plaintext API key:

{
  "mcpServers": {
    "harpoonist": {
      "type": "http",
      "url": "https://api.harpoonist.com/mcp",
      "headers": {
        "Authorization": "Bearer hp_your_api_key"
      }
    }
  }
}

For Claude Code, run:

claude mcp add harpoonist --transport http https://api.harpoonist.com/mcp \
  --header "Authorization: Bearer hp_your_api_key"

Mint a key at Account → API keys (requires an API plan).

Available tools

The MCP server exposes the following tools. Claude selects and calls them automatically based on your question.

Tool	Description
`search_trades`	Filter trades by ticker, filer, date, or transaction type.
`get_trade`	Retrieve a single trade by ID, including its amendment chain.
`get_filer`	Filer profile with recent trades, trade count, and total notional.
`get_ticker`	Security details with recent trades and latest closing price.
`leaderboard`	Top filers ranked by notional, trade count, or performance.
`recent_disclosures`	Live feed of the latest congressional and insider disclosures.
`price_history`	Daily closing prices for a ticker, oldest first.
`filer_activity`	Filer analytics: buy/sell splits, disclosure lag, realized P&L.
`search_filers`	Search the filer directory, ranked by trading activity; filter by role or home state.
`clusters`	Consensus view: distinct filers trading the same ticker, same side.

Quota: Each MCP tool call counts as one request toward your 50,000/month API quota — the same counter as REST requests.

Scope: MCP tools cover the read-only data endpoints. Alert-rule management and bulk export remain REST-only.

Client support: Claude Desktop and Claude Code work today using Streamable HTTP transport. Native Claude.ai web support via OAuth is coming; until then, use one of the desktop clients.

API keys are minted at Account → API keys and require an API plan. Questions? Reach out via the in-app support channel.