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.

curl Python JavaScript

curl "https://api.bullpen.news/v1/search?query=nvidia&limit=2" \
  -H "Authorization: Bearer $BULLPEN_KEY"

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())

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	Investor letters that discuss a company with that ticker or say those words.
`tickers`	map of 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

{
  "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`, `invalid_request`, `invalid_cursor`
`401`	No valid key (unauthorized), or a revoked one (revoked).	`unauthorized`, `revoked`
`403`	Your account can't use this endpoint now: invite, disabled, terms, no_plan, ended, unpaid or tool.	`no_plan`, `ended`, `unpaid`, `terms`, `disabled`, `invite`, `tool`
`429`	Your plan's minute or day limit is reached (minute, day).	`minute`, `day`
`500`	Something went wrong on bullpen.news (internal).	`internal`
`503`	The API is paused (off), busy (ceiling) or having trouble (unavailable). Retry-After comes with all but off.	`ceiling`, `off`, `unavailable`

Fresh: Up to a minute old.
History: Every company and letter we hold.
Cost: One call.