# Company `GET /v1/companies/{ticker}` Everything bullpen.news has on one company, by its ticker: its sector and market cap, the stories and X posts that mention it, and the investor letters that discuss it. days narrows the stories and X posts to the last N days, today included; it doesn't narrow letters. Any other parameter is refused. ## Parameters | Parameter | Type | Description | | --- | --- | --- | | `ticker` | string, in the path, required | The company's stock ticker, such as NVDA. | | `days` | integer, 1 to 365 | Only stories and X posts from the last N days, today included, 1 to 365. 7 is this week. Letters aren't narrowed. | | `limit` | integer, 1 to 100, default 10 | How many results to return, from 1 to 100. | | `cursor` | string | One of the nextCursors a previous call returned, for that list's next page. Keep the other arguments the same. | ```sh curl "https://api.bullpen.news/v1/companies/NVDA?limit=1" \ -H "Authorization: Bearer $BULLPEN_KEY" ``` ```python import os, requests r = requests.get( "https://api.bullpen.news/v1/companies/NVDA", params={"limit": 1}, 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/companies/NVDA?limit=1', { 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 | | --- | --- | --- | | `company` | object | The company. Left out when the call pages a list. | | `company.ticker` | string | Its ticker now. A ticker it used to trade under finds it too. | | `company.name` | string | | | `company.sector` | string or null | Its GICS sector, such as Technology. Null when we don't know it. | | `company.marketCapUsd` | integer or null | Its market cap in whole US dollars. Null when we don't know it or it no longer trades. | | `company.mentions` | integer | How many stories, X posts and videos on bullpen.news name it. | | `company.bullpenUrl` | string | Its page on bullpen.news. | | `stories` | array of [Story](/docs/reference#story) or [Video](/docs/reference#video) | Stories and videos about it, as its page on bullpen.news lists them: newest first, by day. Never X posts. Left out when the call pages another list. | | `xPosts` | array of [XPost](/docs/reference#xpost) | X posts about it, as its page lists them: newest first, by day. Left out when the call pages another list. | | `letters` | array of [Letter](/docs/reference#letter) | Investor letters that discuss it, as its page lists them: the letters most about it first, then newest first. days doesn't narrow them. Left out when the call pages another list. | | `tickers` | map of [TickerEntry](/docs/reference#tickerentry) | Each company the results name, by ticker. | | `nextCursors` | object | Each list's cursor for its next page: pass one as cursor. A list on its last page has none. | | `nextCursors.stories` | string | | | `nextCursors.xPosts` | string | | | `nextCursors.letters` | string | | | 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, 404, 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, 404, 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/companies/NVDA?limit=1` ```json { "company": { "ticker": "NVDA", "name": "Nvidia CORP", "sector": "Technology", "marketCapUsd": 5150000000000, "mentions": 207, "bullpenUrl": "https://bullpen.news/ticker/NVDA" }, "stories": [ { "id": "story:5120111", "kind": "story", "title": "What I'm Watching In November: Midterm Madness, Nvidia, And Walmart", "summary": "November markets hinge on U.S. midterms, CPI, payrolls and OPEC+, with Nvidia guidance and Walmart sales testing the AI trade and consumer demand.", "source": "Seeking Alpha", "author": "Passage Research", "published": "2026-10-29T12:53:45Z", "wentLive": "2026-10-29T13:06:07Z", "url": "https://seekingalpha.com/article/4959231-what-im-watching-in-november-midterm-madness-nvidia-and-walmart?source=generic_rss", "companies": [ "NVDA", "WMT" ] } ], "xPosts": [ { "id": "x:5332882", "kind": "x_post", "postId": "2116515542148493324", "url": "https://x.com/i/web/status/2116515542148493324", "published": "2026-10-31T13:00:02Z", "wentLive": "2026-10-31T13:01:11Z", "companies": [ "CBRS", "NVDA", "SMCI" ] } ], "letters": [ { "id": "letter:10", "kind": "letter", "title": "Third Quarter 2025 Commentary", "firm": "Palm Valley Capital", "period": "Third Quarter 2025", "published": "2025-10-01T12:00:00Z", "wentLive": "2026-08-04T16:06:14Z", "summary": "Palm Valley Capital Fund kept roughly three quarters of assets in cash equivalents while arguing that AI-led mega-cap valuations and small-cap multiples leave little margin for error. It added Teleflex, Robert Half, LKQ, and Avista, sold Seaboard after shares exceeded its valuation, and trimmed precious-metals trusts to manage their weightings.", "url": "https://www.palmvalleycapital.com/_files/ugd/ef2f99_e6aa8ad43cf9478da541105baeb19e58.pdf", "companies": [ "NVDA", "AVA", "DOX", "FLO", "IBX", "INTC", "LKQ", "PHYS", "PSLV", "RHI", "SEB", "TFX" ] } ], "tickers": { "NVDA": { "name": "Nvidia CORP", "sector": "Technology", "marketCapUsd": 5150000000000, "bullpenUrl": "https://bullpen.news/ticker/NVDA" }, "WMT": { "name": "Walmart Inc.", "sector": "Consumer Staples", "marketCapUsd": 979900000000, "bullpenUrl": "https://bullpen.news/ticker/WMT" }, "CBRS": { "name": "Cerebras Systems Inc.", "sector": "Technology", "marketCapUsd": 26740000000, "bullpenUrl": "https://bullpen.news/ticker/CBRS" }, "SMCI": { "name": "Super Micro Computer, Inc.", "sector": "Technology", "marketCapUsd": 21650000000, "bullpenUrl": "https://bullpen.news/ticker/SMCI" }, "AVA": { "name": "Avista CORP", "sector": "Utilities", "marketCapUsd": 3150000000, "bullpenUrl": "https://bullpen.news/ticker/AVA" }, "DOX": { "name": "Amdocs LTD", "sector": "Technology", "marketCapUsd": 6430000000, "bullpenUrl": "https://bullpen.news/ticker/DOX" }, "FLO": { "name": "Flowers Foods INC", "sector": "Consumer Staples", "marketCapUsd": 1310510000, "bullpenUrl": "https://bullpen.news/ticker/FLO" }, "IBX": { "name": "Tradr 2X Long IBM Daily ETF", "sector": null, "marketCapUsd": 1000000, "bullpenUrl": "https://bullpen.news/ticker/IBX" }, "INTC": { "name": "Intel CORP", "sector": "Technology", "marketCapUsd": 349030000000, "bullpenUrl": "https://bullpen.news/ticker/INTC" }, "LKQ": { "name": "Lkq CORP", "sector": "Consumer Discretionary", "marketCapUsd": 4330000000, "bullpenUrl": "https://bullpen.news/ticker/LKQ" }, "PHYS": { "name": "Sprott Physical Gold Trust", "sector": "Financials", "marketCapUsd": 10525560000, "bullpenUrl": "https://bullpen.news/ticker/PHYS" }, "PSLV": { "name": "Sprott Physical Silver Trust", "sector": "Financials", "marketCapUsd": 8826050000, "bullpenUrl": "https://bullpen.news/ticker/PSLV" }, "RHI": { "name": "Robert Half INC.", "sector": "Industrials", "marketCapUsd": 4295100000, "bullpenUrl": "https://bullpen.news/ticker/RHI" }, "SEB": { "name": "Seaboard CORP", "sector": "Consumer Staples", "marketCapUsd": 3723980000, "bullpenUrl": "https://bullpen.news/ticker/SEB" }, "TFX": { "name": "Teleflex INC", "sector": "Healthcare", "marketCapUsd": 5889760000, "bullpenUrl": "https://bullpen.news/ticker/TFX" } }, "nextCursors": { "stories": "WyJjb21wYW55Iiwic3RvcmllcyIsIkwxTnlfNmJIQktWOGlBUE4iLDFd", "xPosts": "WyJjb21wYW55IiwieFBvc3RzIiwiTDFOeV82YkhCS1Y4aUFQTiIsMV0", "letters": "WyJjb21wYW55IiwibGV0dGVycyIsIkwxTnlfNmJIQktWOGlBUE4iLDFd" } } ``` ## 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) | | `404` | Nothing by that ticker, firm, id or day (not_found). | [`not_found`](/docs/errors#not_found) | | `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:** New items within minutes of going live. Up to a minute old. **History:** Everything we hold on the company, from 28 July 2026, plus back catalogue. **Cost:** One call, for all three lists.