Data API
One keyed JSON API for everything TraderTools shows in the app: SEC filings and dilution risk, short interest, insiders and institutions, federal contracts, supply-chain graphs, biotech catalysts, news, search, screeners and exports, plus Catalyst Convergence: the explained cross-domain score, catalyst stack and event screens.
Quick start
Base URL: https://tradertools.pro/api/pro/v1. Send your key in the Authorization header (or X-API-Key). Keys are never accepted in the URL.
curl -s "https://tradertools.pro/api/pro/v1/ticker/NVDA/brief" \ -H "Authorization: Bearer $TT_API_KEY"
import os, requests
r = requests.get("https://tradertools.pro/api/pro/v1/sec/dilution/NVDA",
headers={"Authorization": "Bearer " + os.environ["TT_API_KEY"]}, timeout=30)
r.raise_for_status()
print(r.json())const r = await fetch("https://tradertools.pro/api/pro/v1/screener/sec?size=25&sort=dilution_score&desc=true", {
headers: { Authorization: `Bearer ${process.env.TT_API_KEY}` },
});
console.log(await r.json());Authentication and key safety
- Create keys on the API access page after an API plan is active on your account. A key is shown once; we store only a one-way hash, so a lost key cannot be recovered, only replaced.
- Keys are for servers. Requests that carry a browser
Originheader (cross-site or in-page JavaScript) are refused, and there is no CORS support, so a key placed in a web page or mobile app is not usable and can be abused by anyone who reads it. Keep keys in server-side secrets. - A key used from more IP addresses in one day than its plan allows is blocked automatically, to stop leaked or shared keys. Revoking a key takes effect within seconds.
- Repeated requests with missing or invalid keys cause a temporary block of the sending address.
Plans, credits and limits
Each request costs credits (shown per endpoint below; most cost 1 to 5). Your plan sets a per-minute and a per-day credit budget, how many requests may run at once, how much response data it may download per day, how deep a client may page (page × size), how many tickers one bulk call may carry, and which groups of endpoints it includes. The daily budget resets at 00:00 UTC. Failed requests caused by our side are not charged.
| Plan | Price | Credits / minute | Credits / day | Keys | Data / day | Max paging depth | Bulk tickers / call | Includes |
|---|---|---|---|---|---|---|---|---|
| Developer | Contact us | 60 | 5,000 | 2 | 100 MB | 1,000 | 25 | Data |
| Pro | Contact us | 300 | 50,000 | 5 | 1,000 MB | 5,000 | 100 | Data + exports, account, bulk |
| Scale | Contact us | 1,200 | 500,000 | 20 | 10,000 MB | 20,000 | 250 | Data + exports, account, bulk |
| Enterprise | Custom | 3,000 | 5,000,000 | 100 | 100,000 MB | 100,000 | 500 | Data + exports, account, bulk |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit, X-Quota-Remaining and X-Credits-Charged. Call GET /me for your plan, limits and today's usage.
Errors
| HTTP | code | Meaning |
|---|---|---|
| 400 | key_in_url / bad_paging | The key was sent in the URL, or page/size were not integers. |
| 401 | api_key_required / invalid_api_key / key_expired | No key, a malformed or unknown key, a revoked key or an expired key. |
| 403 | no_active_plan / not_in_plan / scope_required | The account has no active API plan, the endpoint is not in the plan, or the key lacks the read/write scope. |
| 403 | paging_too_deep | page × size exceeds the plan's paging depth. Narrow the filters instead. |
| 403 | key_flagged / ip_blocked / browser_use_not_allowed | The key was blocked for use from too many IP addresses, the sending address is temporarily blocked, or a browser request was refused. |
| 404 | not_found | No such endpoint or record. |
| 429 | rate_limited / daily_quota_exceeded / daily_volume_exceeded / too_many_concurrent_requests / server_busy | A credit, data-volume or concurrency limit was reached, or large exports are briefly busy. See the Retry-After header. |
| 502 | http_502 | A data source is temporarily unavailable; retry shortly. Not charged. |
Errors always look like {"error": {"code": "...", "message": "..."}}. Data responses carry evidence and freshness fields (provenance, observed_at) wherever the underlying record has them; filings link to their SEC EDGAR records.
Catalyst Convergence API: connected events, not separate widgets
The Catalyst Convergence endpoints connect the events around a stock: FDA and clinical catalysts, financing and dilution pressure, insider activity, federal contract awards, supply-chain relationships, short interest and filing flow. Instead of five datasets you get one answer, with every point of the score explained.
- Catalyst stack (
/convergence/stack/{symbol}): seven layers per ticker (near-term catalyst, supporting evidence, financing risk, ownership and positioning, commercial exposure, timing risk, evidence quality) with plain-language narratives such as "FDA decision in 32 days, but financing pressure is elevated". - Explainable score (
/convergence/score/{symbol},/convergence/method): 0 to 100, always returned with its components, the number behind each, and the count of independent source domains. It is an evidence score, not a price prediction. - Event screens (
/convergence/screens,/convergence/screen): ready-made screens such as "catalyst within 90 days + cash under 12 months + insider buying" and a custom screen across every domain. - What changed (
/convergence/changes,/convergence/changes/{symbol}): daily snapshots turned into events: score moves, dilution and cash-runway changes, insider purchases, new awards, new or moved catalyst dates. - Decision-style signals (
/convergence/signals): what a combination of events means, not just that something was filed. - Contract equity exposure (
/convergence/contracts/exposure) and supply-chain exposure (/convergence/supply/exposure/{symbol}): which public companies sit behind an agency, program, supplier or customer, with their own catalysts and financing risk attached. - Evidence layer (
/convergence/evidence/{symbol}): every data point with source, source date, ingestion date, current or stale status, confidence and whether it was reported or inferred. - Alert rules (
/alert-rules, Pro plans and up): 13 Convergence rule kinds, such as "catalyst ahead while financing pressure is elevated" or "insiders net buying with a catalyst ahead". They deliver in-app, by email or by webhook with the same context, and send one digest instead of a flood when a rule matches many tickers at once. The rule kinds are listed in thekindsobject returned byGET /alert-rules. - Research brief (
/convergence/brief/{symbol}and.../export.pdf|docx|xlsx|txt|csv): an evidence-linked packet with data limitations and a neutral conclusion. It is not investment advice.
curl -H "Authorization: Bearer $TT_KEY" \ "https://tradertools.pro/api/pro/v1/convergence/screens/fda-cash-insider" curl -H "Authorization: Bearer $TT_KEY" \ "https://tradertools.pro/api/pro/v1/convergence/screen?catalyst_within=90&min_dilution=50&min_domains=2&sort=days_to_event&desc=false"
Every Convergence endpoint is in the Data category, so it works on every plan. See the full list under "Catalyst Convergence" below.
API endpoints for SEC, dilution, contracts, supply-chain and biotech data
All paths are relative to https://tradertools.pro/api/pro/v1 and all responses are JSON unless an export format is requested. "Min plan" is the cheapest plan that includes the endpoint.
Catalyst Convergence
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /convergence/method | How the convergence score is built: every component, its points, the limits and the evidence labels. | 1 | Developer |
| GET | /convergence/overview | Market-wide convergence: highest-scoring tickers, catalyst-versus-financing collisions, score distribution and recent changes. | 3 | Developer |
| GET | /convergence/screens | The ready-made event screens with the number of tickers matching each right now. | 1 | Developer |
| GET | /convergence/screens/{key}Parameters
| Run one ready-made event screen (FDA date + thin cash + insider buying, catalyst + dilution, contracts + insider buying, ...). Paged. | 3 | Developer |
| GET | /convergence/screenParameters
| Custom event screen across every domain: score, domains, catalyst timing, cash runway, dilution, insider buying, awards, short interest, tier. Paged. | 3 | Developer |
| GET | /convergence/signalsParameters
| Decision-style signals: what a combination of events means, e.g. FDA decision in 32 days while financing pressure is elevated. | 3 | Developer |
| GET | /convergence/changesParameters
| What changed across the market: score moves, dilution and cash-runway changes, insider purchases, new awards, new and moved catalyst dates. | 3 | Developer |
| GET | /convergence/changes/{symbol}Parameters
| What changed for one ticker: before/after for score, dilution, runway, insider and awards, plus new awards, filings and news. | 3 | Developer |
| GET | /convergence/contracts/exposureParameters
| Public companies exposed to an agency or program: awards, value, new-versus-repeat awardee, with insider, financing and catalyst context. Paged. | 3 | Developer |
| GET | /convergence/supply/exposure/{symbol}Parameters
| Suppliers, customers and partners of a ticker with the events attached to each counterparty (catalysts, awards, financing risk). | 3 | Developer |
| GET | /convergence/stack/{symbol}Parameters
| The catalyst stack for one ticker: near-term catalyst, supporting evidence, financing risk, positioning, commercial exposure, timing risk, evidence quality, plus the explained score. | 4 | Developer |
| GET | /convergence/score/{symbol}Parameters
| The convergence score for one ticker with every component, its points and the number behind it. | 2 | Developer |
| GET | /convergence/evidence/{symbol}Parameters
| Evidence and confidence layer: every data point with source, source date, ingestion date, current/stale status, confidence and reported-versus-inferred. | 3 | Developer |
| GET | /convergence/brief/{symbol}Parameters
| Evidence-linked research brief for one ticker as structured data: stack, changes, counterparties, evidence, limitations and a neutral conclusion. | 8 | Developer |
| GET | /convergence/brief/{symbol}/export.{fmt}Parameters
| The research brief as a document (pdf | docx | xlsx | txt | csv). | 25 | Pro |
Account & workspace
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /overview | Your workspace overview. | 3 | Pro |
| GET | /watchlists | Your watchlists. | 1 | Pro |
| GET | /watchlists/{wid}/overviewParameters
| Every ticker on a watchlist with scores, dilution, insider, short interest, catalysts, news and contracts. | 5 | Pro |
| POST | /watchlists | Create a watchlist (write scope). Body: {name, description?}. | 1 | Pro |
| POST | /watchlists/{wid}/itemsParameters
| Add a ticker to a watchlist (write scope). Body: {ticker}. | 1 | Pro |
| POST | /watchlists/{wid}/items/{iid}Parameters
| Update a watchlist item (write scope). | 1 | Pro |
| POST | /watchlists/{wid}/deleteParameters
| Delete a watchlist (write scope). | 1 | Pro |
| GET | /savedParameters
| Your saved searches and screeners. | 1 | Pro |
| POST | /saved | Save a search or screener (write scope). | 1 | Pro |
| POST | /saved/{sid}/deleteParameters
| Delete a saved search (write scope). | 1 | Pro |
| GET | /alertsParameters
| Your alert inbox. Paged. | 2 | Pro |
| GET | /alerts/{alert_id}Parameters
| One alert. | 1 | Pro |
| POST | /alerts/{alert_id}/stateParameters
| Mark an alert read, dismissed or open (write scope). | 1 | Pro |
| GET | /alert-rules | Your alert rules. | 1 | Pro |
| POST | /alert-rules | Create an alert rule (write scope). | 1 | Pro |
| POST | /alert-rules/{rule_id}Parameters
| Update an alert rule (write scope). | 1 | Pro |
| GET | /contracts/watchlist | Your watchlist tickers with their latest contract awards. | 3 | Pro |
SEC filings & dilution
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /sec/signals | Market-wide SEC signals: highest dilution risk, heaviest short interest, net insider selling/buying and shortest cash runway. | 2 | Developer |
| GET | /sec/history/{symbol}Parameters
| Short-interest, institutional and filing-count history for a ticker. | 3 | Developer |
| GET | /sec/evidence/{symbol}Parameters
| Source evidence and freshness for every SEC data set held for a ticker. | 3 | Developer |
| GET | /sec/{section}/{symbol}Parameters
| One SEC data set for a ticker. section = ticker | filings | insider | short-interest | institutional | beneficial | float | dilution. | 2 | Developer |
| GET | /sec-universe/lookupParameters
| Find SEC-registered companies by name or ticker. | 1 | Developer |
Contracts
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /contracts/status | Freshness and coverage of the federal-contract data. | 1 | Developer |
| GET | /contracts/dashboard | Federal award totals by agency, source and period. | 2 | Developer |
| GET | /contracts/heatmapParameters
| Monthly award value grid by agency, category, country or source. | 2 | Developer |
| GET | /contracts/moversParameters
| Companies with the largest change in awarded value versus the prior period. | 2 | Developer |
| GET | /contracts/trending | Companies whose award activity is accelerating. | 2 | Developer |
| GET | /contracts/analysis | Distributions of award size, category, duration and matching method. | 2 | Developer |
| GET | /contracts/signals | News and SEC signals attached to contract-matched companies. | 2 | Developer |
| GET | /contracts/leaderboardParameters
| Companies ranked by total award value, count or average size. | 2 | Developer |
| GET | /contracts/alerts | Contract-related alert feed. | 2 | Developer |
| GET | /contracts/categories | Award categories. | 1 | Developer |
| GET | /contracts/awardsParameters
| Search federal contract awards (agency, value, date, category, ticker, expiry...). Paged. | 2 | Developer |
| GET | /contracts/award/{award_id}Parameters
| One contract award with its company matches. | 2 | Developer |
| GET | /contracts/companiesParameters
| Companies with matched awards, totals and latest award. Paged. | 2 | Developer |
| GET | /contracts/company/{symbol}Parameters
| A company's matched awards, signals and news. | 3 | Developer |
| GET | /contracts/award/{award_id}/export.{fmt}Parameters
| Export one award (pdf | docx | xlsx | txt | csv). | 20 | Pro |
Supply chain
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /supply/graph/{ticker}Parameters
| Supply-chain relationship graph around a ticker (nodes and evidenced edges). | 3 | Developer |
| GET | /supply/chain/{ticker}Parameters
| Walk suppliers and customers hop by hop from a ticker. | 3 | Developer |
| GET | /supply/correlations/{ticker}Parameters
| Entity correlations for a ticker with strength, confidence and evidence. | 3 | Developer |
| GET | /supply/stats | Graph-wide statistics and coverage. | 2 | Developer |
| GET | /supply/searchParameters
| Search supply-chain entities. | 1 | Developer |
| GET | /supply/correlation-searchParameters
| Search graph-wide correlations by entity and kind. | 2 | Developer |
| GET | /supply/logistics/{ticker}Parameters
| Edges whose evidence describes shipping, freight, distribution or warehousing. | 3 | Developer |
| GET | /supply/risk | Supply-chain risk across the universe. | 3 | Developer |
| GET | /supply/footprint/{ticker}Parameters
| Domicile and country footprint of a company's supply chain. | 2 | Developer |
Biotech catalysts
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /pharma/overview | Biotech universe overview. | 2 | Developer |
| GET | /pharma/dashboard | Biotech command-center data: next FDA decisions, catalyst intensity, risk. | 3 | Developer |
| GET | /pharma/calendarParameters
| PDUFA dates, trial readouts and advisory committees in a date range. | 2 | Developer |
| GET | /pharma/calendar.icsParameters
| The same calendar as an .ics file. | 5 | Pro |
| GET | /pharma/calendar.export.{fmt}Parameters
| Calendar export (pdf | docx | xlsx | txt | csv). | 40 | Pro |
| GET | /pharma/programsParameters
| Drug programs with phase, indication, designations and next event. Paged. | 2 | Developer |
| GET | /pharma/pipelineParameters
| Programs per company by highest phase. | 2 | Developer |
| GET | /pharma/partnershipsParameters
| Collaboration, license and partnership relationships found in SEC filings. Paged. | 2 | Developer |
| GET | /pharma/records/{kind}Parameters
| Raw biotech records by kind (catalyst, trial, designation, ...). Paged. | 2 | Developer |
| GET | /pharma/company/{symbol}Parameters
| Scorecard, catalysts, trials, designations and partnerships for one biotech. | 3 | Developer |
| GET | /pharma/universe/{symbol}Parameters
| Biotech scorecard row for a ticker. | 1 | Developer |
News
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /newsParameters
| News and SEC-filing headlines, filterable by ticker, source, kind, sector and days. Paged. | 2 | Developer |
| GET | /news/sectorsParameters
| News counts by sector. | 1 | Developer |
| GET | /news/sourcesParameters
| News sources and counts. | 1 | Developer |
| GET | /news/export.{fmt}Parameters
| Export a news query (pdf | docx | xlsx | txt | csv). | 40 | Pro |
| GET | /news/item/{item_id}/export.{fmt}Parameters
| Export one news item. | 10 | Pro |
Search & screeners
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /searchParameters
| Unified search across companies, filings, awards, supply-chain nodes and biotech records. | 2 | Developer |
| GET | /search/ticker/{symbol}Parameters
| Every data view we hold for one ticker in a single response. | 15 | Developer |
| GET | /screener/meta | Screener domains, fields and operators. | 1 | Developer |
| GET | /screener/{domain}/facetsParameters
| Facet counts for a screener domain. | 2 | Developer |
| GET | /screener/{domain}/export.csvParameters
| Screener result as CSV. | 30 | Pro |
| GET | /screener/{domain}/export.{fmt}Parameters
| Screener result export (pdf | docx | xlsx | txt). | 50 | Pro |
| GET | /screener/{domain}Parameters
| Run a screener (sec | contracts | supply | biotech). Paged. | 3 | Developer |
| GET | /universeParameters
| Browse the searchable universe (companies, filings, awards, nodes). Paged; depth is capped by plan. | 2 | Developer |
Ticker & market views
| Path | What it returns | Credits | Min plan | |
|---|---|---|---|---|
| GET | /ticker/{symbol}/briefParameters
| One-call brief: SEC metrics, supply chain, biotech, catalysts, news and awards. | 5 | Developer |
| GET | /me | Your key, plan, limits and today's usage. | per item | Developer |
| GET | /views | Catalogue of every per-ticker and market-wide data view. | 1 | Developer |
| GET | /ticker/{symbol}/views/{key} | One data view for one ticker (see /views for keys). | 3 | Developer |
| GET | /market/{key} | A market-wide view: movers, MA targets, calendars, leaderboards, heatmaps (see /views). | 2 | Developer |
| GET | /ticker/{symbol}/everything | Every ticker view, the one-call brief and key SEC sections in a single response. | 15 | Developer |
| POST | /bulk/briefParameters
| Brief for many tickers at once. Body: {"symbols": ["NVDA", ...]}. Costs 5 credits per ticker; max per call set by plan. | per item | Developer |
Frequently asked questions
What data does the TraderTools Data API cover?
SEC filings and dilution risk scores, short interest, insider and institutional activity, public float, federal contract awards, supply-chain relationships, biotech catalysts such as PDUFA dates and clinical trials, news, search, screeners and exports, plus Catalyst Convergence: an explainable score, catalyst stack, event screens and change tracking that connect those datasets.
Is there a free API?
No. Every request needs an API key on an active paid plan, and requests without a valid key never receive data. Use the request-access link to get started.
How do I authenticate?
Send your key in the Authorization header as a Bearer token (or in X-API-Key). Keys are never accepted in the URL and are shown only once when you create them.
What are the rate limits?
Each plan has a per-minute and a per-day credit budget, a daily data-volume allowance, a concurrency limit and a paging-depth limit. Most endpoints cost 1 to 5 credits, and every response reports your remaining limits in its headers.
Can I call the API from a browser or mobile app?
No. The API is for server-side use only: requests from browsers (CORS) are refused so that keys are never exposed in web pages or apps.
Can I resell or redistribute the data?
You can use the data in your own products, research and internal tools. You may not resell it or republish it as a competing data service, and keys may not be shared between organizations.
Where does the data come from and how fresh is it?
TraderTools processes public sources such as SEC EDGAR filings, federal award records and ClinicalTrials.gov. Responses include observed_at and provenance fields so you can see when each record was last updated.
Acceptable use
- Use the API for your own products, research and internal tools. Do not resell, redistribute or republish the data as a competing data service, and do not share keys between organizations.
- Do not scrape the website or attempt to bypass limits, rotate addresses to evade blocks, or enumerate the whole database. Paging depth, credits and per-key IP limits exist to prevent this, and keys that try may be suspended without refund.
- Data is provided for information, as described in the Terms of Service; it is not investment advice and completeness or timeliness is not guaranteed. Cite TraderTools.pro when you display it publicly.