# Search companies and letters `GET /v1/search` Find companies by ticker or name, and the investor letters that match the same query. Use it when you aren't sure of a company's ticker. Any other parameter is refused. ## Parameters | Parameter | Type | Description | | --- | --- | --- | | `query` | string, 1 to 100 characters, required | A ticker, a company name or a few words, such as NVDA or Nvidia. Spaces at either end don't count, and it can't contain a null character. A query of only $ or punctuation is refused. | | `limit` | integer, 1 to 100, default 10 | How many results to return, from 1 to 100. | ```sh curl "https://api.bullpen.news/v1/search?query=nvidia&limit=2" \ -H "Authorization: Bearer $BULLPEN_KEY" ``` ```python import os, requests r = requests.get( "https://api.bullpen.news/v1/search", params={"query": "nvidia", "limit": 2}, headers={"Authorization": f"Bearer {os.environ['BULLPEN_KEY']}"}, ) r.raise_for_status() print(r.json()) ``` ```js const r = await fetch('https://api.bullpen.news/v1/search?query=nvidia&limit=2', { headers: { Authorization: `Bearer ${process.env.BULLPEN_KEY}` } }); if (!r.ok) throw new Error((await r.json()).detail); console.log(await r.json()); ``` ## What comes back | Field | Type | Description | | --- | --- | --- | | `companies` | array of object | Companies whose ticker or name matches, the closest match first. | | `companies[].ticker` | string | | | `companies[].name` | string | | | `companies[].mentions` | integer | How many stories, X posts and videos on bullpen.news name it. | | `companies[].bullpenUrl` | string | Its page on bullpen.news. | | `letters` | array of [Letter](/docs/reference#letter) | Investor letters that discuss a company with that ticker or say those words. | | `tickers` | map of [TickerEntry](/docs/reference#tickerentry) | Each company the results name, by ticker. | | Header | Sent with | Description | | --- | --- | --- | | `Request-Id` | every answer | This request's id, such as req_ followed by 24 letters and digits. Quote it to support. | | `RateLimit-Policy` | 200, 400, 429, 500, 503 | Your plan's quotas, per minute and per day (IETF draft-11). It may change to match the RFC. | | `RateLimit` | 200, 400, 429, 500, 503 | What each window has left, and the seconds until it resets (IETF draft-11). | | `WWW-Authenticate` | 401 | Bearer realm="bullpen.news" | | `Retry-After` | 429, 503 | How many seconds to wait. | `GET /v1/search?query=nvidia&limit=2` ```json { "companies": [ { "ticker": "NVDA", "name": "Nvidia CORP", "mentions": 207, "bullpenUrl": "https://bullpen.news/ticker/NVDA" } ], "letters": [ { "id": "letter:1227", "kind": "letter", "title": "Aristotle Multi-Asset Balanced Income Fund Commentary", "firm": "Aristotle Funds", "period": "third quarter of 2026", "published": "2026-09-30T12:00:00Z", "wentLive": "2026-10-30T16:30:50Z", "summary": "Aristotle Multi-Asset Balanced Income Fund retained an overweight to equities and AI-related themes, favoring emerging-market and Japanese stocks while keeping underweights in investment-grade and core bonds. The portfolio sees AI capital spending supporting growth but flags debt-funded datacenter investment, rising yields and an AI investment bubble as principal risks.", "url": "https://cdn.prod.website-files.com/642414d0e893bb832996f598/6ae4c42dbf99f2b717e39d50_Aristotle%20Multi-Asset%20Balanced%20Income%20Fund%20Commentary.pdf", "companies": [] }, { "id": "letter:1220", "kind": "letter", "title": "Quarterly Investor Letter Q3 2026", "firm": "O'Keefe Stevens Advisory", "period": "Q3 2026", "published": "2026-10-30T02:31:00Z", "wentLive": "2026-10-30T02:31:00Z", "summary": "O'Keefe Stevens bought Octave Intelligence following its Hexagon spin-off, arguing forced selling, fragmented listings and underappreciated cross-selling created an attractive entry point. The firm sold M&T Bank at fair value, retained Corning through AI-infrastructure volatility, and continues to hold Perrigo despite leverage and management uncertainty.", "url": "https://okeefestevens.com/quarterly-investor-letter-q3-2026/", "companies": [ "OCTV", "AMZN", "CALY", "GLW", "GOOGL", "HXGBY", "META", "MSFT", "MTB", "NVDA", "PRGO", "SPHR", "WY" ] } ], "tickers": { "NVDA": { "name": "Nvidia CORP", "sector": "Technology", "marketCapUsd": 5150000000000, "bullpenUrl": "https://bullpen.news/ticker/NVDA" }, "OCTV": { "name": "Octave Intelligence plc", "sector": "Technology", "marketCapUsd": 5780000000, "bullpenUrl": "https://bullpen.news/ticker/OCTV" }, "AMZN": { "name": "Amazon Com INC", "sector": "Consumer Discretionary", "marketCapUsd": 2590000000000, "bullpenUrl": "https://bullpen.news/ticker/AMZN" }, "CALY": { "name": "Callaway Golf Co", "sector": "Consumer Discretionary", "marketCapUsd": 2690000000, "bullpenUrl": "https://bullpen.news/ticker/CALY" }, "GLW": { "name": "Corning INC", "sector": "Technology", "marketCapUsd": 110950000000, "bullpenUrl": "https://bullpen.news/ticker/GLW" }, "GOOGL": { "name": "Alphabet Inc.", "sector": "Communication Services", "marketCapUsd": 3970000000000, "bullpenUrl": "https://bullpen.news/ticker/GOOGL" }, "HXGBY": { "name": "Hexagon AB ADR", "sector": "Technology", "marketCapUsd": 28680000000, "bullpenUrl": "https://bullpen.news/ticker/HXGBY" }, "META": { "name": "Meta Platforms, Inc.", "sector": "Communication Services", "marketCapUsd": 1614251020000, "bullpenUrl": "https://bullpen.news/ticker/META" }, "MSFT": { "name": "Microsoft CORP", "sector": "Technology", "marketCapUsd": 3880000000000, "bullpenUrl": "https://bullpen.news/ticker/MSFT" }, "MTB": { "name": "M&t Bank CORP", "sector": "Financials", "marketCapUsd": 31720000000, "bullpenUrl": "https://bullpen.news/ticker/MTB" }, "PRGO": { "name": "PERRIGO Co plc", "sector": "Healthcare", "marketCapUsd": 2190000000, "bullpenUrl": "https://bullpen.news/ticker/PRGO" }, "SPHR": { "name": "Sphere Entertainment Co.", "sector": "Communication Services", "marketCapUsd": 3910000000, "bullpenUrl": "https://bullpen.news/ticker/SPHR" }, "WY": { "name": "Weyerhaeuser CO", "sector": "Real Estate", "marketCapUsd": 14670000000, "bullpenUrl": "https://bullpen.news/ticker/WY" } } } ``` ## Status codes | Status | Meaning | Codes | | --- | --- | --- | | `200` | The answer. | | | `400` | A parameter is invalid or unknown (invalid_request), a key is in the URL (key_in_url), or a cursor is not this call's (invalid_cursor). | [`key_in_url`](/docs/errors#key_in_url), [`invalid_request`](/docs/errors#invalid_request), [`invalid_cursor`](/docs/errors#invalid_cursor) | | `401` | No valid key (unauthorized), or a revoked one (revoked). | [`unauthorized`](/docs/errors#unauthorized), [`revoked`](/docs/errors#revoked) | | `403` | Your account can't use this endpoint now: invite, disabled, terms, no_plan, ended, unpaid or tool. | [`no_plan`](/docs/errors#no_plan), [`ended`](/docs/errors#ended), [`unpaid`](/docs/errors#unpaid), [`terms`](/docs/errors#terms), [`disabled`](/docs/errors#disabled), [`invite`](/docs/errors#invite), [`tool`](/docs/errors#tool) | | `429` | Your plan's minute or day limit is reached (minute, day). | [`minute`](/docs/errors#minute), [`day`](/docs/errors#day) | | `500` | Something went wrong on bullpen.news (internal). | [`internal`](/docs/errors#internal) | | `503` | The API is paused (off), busy (ceiling) or having trouble (unavailable). Retry-After comes with all but off. | [`ceiling`](/docs/errors#ceiling), [`off`](/docs/errors#off), [`unavailable`](/docs/errors#unavailable) | **Fresh:** Up to a minute old. **History:** Every company and letter we hold. **Cost:** One call.