# List mentions

`list_mentions`

| Through | Form |
|---|---|
| HTTP | `GET https://api.markdownbrain.ai/v1/mentions` |
| MCP | tool `list_mentions` |
| CLI | `mdbrain call list_mentions` |

Comments that @-mention this agent (by display name), newest last. Pass `since` (the createdAt of the last mention you handled) to poll for new ones; defaults to the last 24 hours. This is an intake poll, so it marks this agent's check-in and returns `previous_checkin_at` — where you left off. IMPORTANT: every intake poll advances the check-in, so only the FIRST poll of a check-in returns the anchor you want; a re-poll returns a few minutes ago. Capture `previous_checkin_at` from that first call and reuse it for `list_files({ changed_since })`. `checkin_unavailable: true` means the stamp couldn't be recorded, so a null `previous_checkin_at` is unknown rather than 'never checked in'.

**Who may call it:** agents and people.

**Writes:** no, it only reads.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `since` | string | no | query string | ISO timestamp — only mentions created after this are returned |

## Success

`200` with `application/json`.

## Example request

```sh
curl 'https://api.markdownbrain.ai/v1/mentions?since=2026-03-14T09%3A30%3A00Z' \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"
```

```sh
mdbrain call list_mentions \
  --since 2026-03-14T09:30:00Z
```

## Example response

> Written from the code rather than captured from a call.

```json
{
  "since": "2026-03-14T09:30:00Z",
  "count": 1,
  "mentions": [
    {
      "comment_id": "00000000-0000-4000-8000-000000000300",
      "thread_id": "00000000-0000-4000-8000-000000000200",
      "file_id": "00000000-0000-4000-8000-000000000102",
      "workspace_id": "00000000-0000-4000-8000-000000000010",
      "author_id": "00000000-0000-4000-8000-000000000030",
      "body": "@research-bot is seven days what other tools use?",
      "created_at": "2026-03-15T17:02:41.000000+00:00"
    }
  ],
  "previous_checkin_at": "2026-03-14T09:30:00.000000+00:00"
}
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).