# List mentions

Source: https://langbot.ai/docs/api/history/list-mentions

`GET /v1/history/mentions`

Langbot's own phrase hits on recorded events, with the speaker, timestamps and tickers, never the surrounding text.

**Auth.** An API token: `Authorization: Bearer lb_…` ([create one](https://langbot.ai/app/tokens)). Signed-in web sessions work too.

**Limits.** One history query per call (500 a day on Free; unlimited on Builder and Standard).

## Parameters

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `speaker` | string | no | A canonical speaker key. |
| `phrase` | string | no | A normalized phrase key. |
| `event_id` | string | no | One event (`ev_…`). |
| `since` | integer | no | ms epoch; default 30 days ago. |
| `until` | integer | no | ms epoch; default now. |
| `limit` | integer | no | Page size. 1 to 1000. Default `50`. |

## Request

**curl**

```bash
curl "https://api.langbot.ai/v1/history/mentions?speaker=powell&limit=1" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN"
```

**Python**

```python
from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    for m in await lb.mentions(speaker="powell", limit=1):
        print(m.phrase, m.t_spoken, m.market_refs)
```

**TypeScript**

```ts
import { LangbotClient } from "@langbotai/sdk";

const lb = new LangbotClient(); // reads LANGBOT_API_TOKEN
const mentions = await lb.mentions({ speaker: "powell", limit: 1 });
console.log(mentions);
```

## Response

`200 OK`

```json
{
  "count": 1,
  "since": 1790800000000,
  "until": 1793392000000,
  "mentions": [
    { "id": "evt_01K7Q0000000000000000000A2", "phrase": "transitory", "speaker": "powell", "event_id": "ev_fomc_sep_2026_presser", "source_id": "src_fomc_sep_2026_public", "market_refs": ["KXFEDMENTION-26SEP-TRANSITORY"], "confidence": 0.96, "t_spoken": 1758653012000, "t_detected": 1758653012080, "t_emitted": 1758653012086, "lag_vs_public_ms": 4100, "source_kind": "hls", "seq": 2210, "verdict": { "counts": true, "reason": "mention 1 (1 needed)", "role": null } }
  ]
}
```

## Errors

| Status | `code` | When |
|---|---|---|
| 401 | `auth_required` | No token was sent. |
| 401 | `token_invalid` | The token was not recognised (mistyped, revoked or expired). |
| 422 | `validation_error` | A parameter failed validation; `detail[].loc` names it. |
| 429 | `quota_exceeded` | Today's history queries are spent; `quota.resets_at` says when they reset. |
| 429 | `rate_limited` | Over your request budget; wait `Retry-After` seconds. |

Every error body is `{"detail": …, "code": "…"}`; branch on `code`. All codes: [Errors](https://langbot.ai/docs/api#errors).