---
title: "List the user's recent triggered+unread price alerts (bell-badge)"
method: GET
path: "/api/alerts/unread"
tags: ["Alerts"]
---

# List the user's recent triggered+unread price alerts (bell-badge)

`GET /api/alerts/unread`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/alerts/unread`
- Auth: none declared

Return up to 10 of the user's most-recent triggered+unread
alert events. Drives the bell-badge dropdown in PR2's
`static/js/notifications.js`.

Required fields per F4.3 contract: `events: List[AlertEvent]`,
`count: int`. Frontend reads `data.count` to drive the badge
number + iterates `data.events.forEach(...)` to render dropdown
rows. Error path MUST still emit `events: []` per the silent-
shadow defect class (CLAUDE.md §"Contract tests").

## Response `200`

Successful Response

- AlertUnreadResponse: `GET /api/alerts/unread` response. Drives the bell-badge poll. Required fields: `events` and `count`. Frontend reads `data.count` to set the badge number + iterates `data.events.forEach(...)` to render the dropdown rows. Error path MUST still emit `events: []` per CLAUDE.md silent-shadow defect class (frontend `events.forEach` NPEs on undefined).
  - `events` AlertEvent[], required: Up to 10 most-recent triggered+unread events.
    - `id` integer, required: Primary key (used as POST /api/alerts/{id}/read path param).
    - `ticker` string, required: Stock ticker (uppercased).
    - `condition_type` string, required: One of 'price_above' / 'price_below' (PR2 v1) — frontend renders 'crossed above' / 'crossed below' copy from this.
    - `triggered_at` string, required: ISO-8601 timestamp the cron fired the alert. Frontend renders relative-time ('2 min ago').
    - `threshold` number, nullable: The user's set threshold; rendered in the badge row header copy.
    - `fair_value` number, nullable: The price at the moment the cron fired. Rendered as the numeric anchor in the dropdown row.
    - `note` string, nullable: The user's optional 'why this price' note from when they set the alert. Surfaces on hover in the dropdown row.
  - `count` integer, required: len(events). Drives the bell-badge counter.

## Other responses

- `401`: Unauthorized
- `500`: Internal Server Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)