# Person

`GET /v1/people/{slug}`

A person we cover, such as Warren Buffett, by their slug or name: their videos with our summaries, or, given a query, short passages of what they said, each with the second it starts. Any other parameter is refused.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | string, in the path, 1 to 100 characters, required | A person we cover, by their slug or their name, such as warren-buffett or Warren Buffett. Spaces at either end don't count, and it can't contain a null character. |
| `query` | string, 1 to 200 characters | Words they said, such as float or "share buybacks": quotes keep a phrase together. Leave it out for their videos, newest first. Spaces at either end don't count, and it can't contain a null character. A query with no word to look for is refused. |
| `who` | string | Whose words query searches: person (the default) for the person's own, everyone for anyone in their videos. Only with query. It must come with query. One of `person` or `everyone`. |
| `limit` | integer, 1 to 10, default 10 | How many videos to return, from 1 to 10. |
| `cursor` | string | The nextCursor a previous call returned, for the next page. Keep the other arguments the same. |

```sh
curl "https://api.bullpen.news/v1/people/warren-buffett?query=float&limit=1" \
  -H "Authorization: Bearer $BULLPEN_KEY"
```

```python
import os, requests

r = requests.get(
    "https://api.bullpen.news/v1/people/warren-buffett",
    params={"query": "float", "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/people/warren-buffett?query=float&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 |
| --- | --- | --- |
| `person` | object |  |
| `person.slug` | string | Their slug on bullpen.news, which person takes. |
| `person.name` | string |  |
| `person.line` | string or null | Who they are, in one line. |
| `person.bullpenUrl` | string | Their page on bullpen.news. |
| `videos` | array of object | Newest first. With query, the videos with the most passages first. |
| `videos[].id` | string | Its id, such as video:789. |
| `videos[].kind` | `video` |  |
| `videos[].url` | string | The video on YouTube. |
| `videos[].published` | string (date-time) | When it was published, in UTC. |
| `videos[].wentLive` | string (date-time) or null | When it went live on bullpen.news, in UTC. |
| `videos[].companies` | array of string | The companies it is about, by ticker. tickers says what each one is. |
| `videos[].summary` | string | Our summary of what is said in it, from our own transcript. Only with bullpenUrl. |
| `videos[].people` | array of object | The people we cover who are in it. Left out when none. |
| `videos[].people[].slug` | string | The person's slug on bullpen.news. |
| `videos[].people[].name` | string |  |
| `videos[].bullpenUrl` | string | Its page on bullpen.news, with what was said in it. Only on a video of a person we cover, once its page is ready. |
| `videos[].passages` | array of [Passage](/docs/reference#passage) | With query: up to 3 short passages that hold it, in time order. Empty when only our summary matches. |
| `tickers` | map of [TickerEntry](/docs/reference#tickerentry) | Each company the results name, by ticker. |
| `nextCursor` | string | Pass it as cursor for the next page. Left out on the last page. |

| 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/people/warren-buffett?query=float&limit=1`

```json
{
  "person": {
    "slug": "warren-buffett",
    "name": "Warren Buffett",
    "line": "Ran Berkshire Hathaway from 1965 to 2025.",
    "bullpenUrl": "https://bullpen.news/people/warren-buffett"
  },
  "videos": [
    {
      "id": "video:7186332",
      "kind": "video",
      "url": "https://www.youtube.com/watch?v=x2xUC9gWy3Q",
      "published": "2020-11-03T22:00:14Z",
      "wentLive": "2026-11-18T05:40:44Z",
      "companies": [
        "BRK.A"
      ],
      "summary": "Warren Buffett and Charlie Munger answer shareholder questions at Berkshire Hathaway’s 2001 annual meeting. They return repeatedly to buying durable businesses, deploying insurance float, GEICO and General Re underwriting, and Berkshire’s limits as it grows. They also discuss technology, accounting for options and pensions, derivatives, corporate acquisition practices, utilities, succession, and the risks hidden in leveraged financial institutions.",
      "people": [
        {
          "slug": "warren-buffett",
          "name": "Warren Buffett"
        }
      ],
      "bullpenUrl": "https://bullpen.news/people/warren-buffett/2001-annual-meeting",
      "passages": [
        {
          "text": "And then we have the use of float for many years to come and there are no subsequent charges against that. So in respect to those contracts, the important thing is that we tell you, and we should tell you really every quarter, if they’re significant and certainly yearly, any significant items that fall in that category.",
          "start": 1115,
          "url": "https://www.youtube.com/watch?v=x2xUC9gWy3Q&t=1115",
          "bullpenUrl": "https://bullpen.news/people/warren-buffett/2001-annual-meeting?t=1115"
        },
        {
          "text": "And therefore our cost of float, if we hadn’t willingly engaged in those transactions, would have been about 4.5%. I should mention to you that I expect that our cost of float, I said in the annual report that absent a mega catastrophe, and I might define a mega catastrophe as insured losses, we’ll say of 20 billion or more…",
          "start": 1216,
          "url": "https://www.youtube.com/watch?v=x2xUC9gWy3Q&t=1216",
          "bullpenUrl": "https://bullpen.news/people/warren-buffett/2001-annual-meeting?t=1216"
        },
        {
          "text": "I should mention to you that I expect that our cost of float, I said in the annual report that absent a mega catastrophe, and I might define a mega catastrophe as insured losses, we’ll say of 20 billion or more or something on that order. Absent a mega catastrophe, we expected our cost of float to come down this…",
          "start": 1224,
          "url": "https://www.youtube.com/watch?v=x2xUC9gWy3Q&t=1224",
          "bullpenUrl": "https://bullpen.news/people/warren-buffett/2001-annual-meeting?t=1224"
        }
      ]
    }
  ],
  "tickers": {
    "BRK.A": {
      "name": "Berkshire Hathaway INC",
      "sector": "Financials",
      "marketCapUsd": 1257063710000,
      "bullpenUrl": "https://bullpen.news/ticker/BRK.A"
    }
  },
  "nextCursor": "WyJwZXJzb24iLCJ2aWRlb3MiLCI5VEswcU1zenRxVzkzMnh6IiwxXQ"
}
```

## 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, day or person (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:** A video arrives once its page is ready. Up to a minute old.
**History:** Every video of theirs with a page.
**Cost:** One call.
