get · mentions:read

List mentions

The core read capability. Newest first, already classified. Every parameter is optional — call it with nothing for the latest. Page with the returned nextCursor rather than an offset, so rows arriving mid-walk cannot shift the window.

Read onlyIdempotent

REST

get/api/v1/mentions

curl "https://herculeradar.com/api/v1/mentions" \
  --header "Authorization: Bearer hr_live_…"

MCP

Tool name list_mentions. It takes the same input and returns the same { data, meta } envelope as REST, because both call the same function.

The main read tool. Returns collected posts newest first, already classified. Call with no arguments for the latest, or filter by category, sentiment, urgency, source, intent, speaker or a named time window. Exact From filters use author_handle / author_name / author_url. Page with the returned nextCursor.

Parameters

monitor_id	string	Restrict to one monitor
source	x \| reddit \| youtube \| linkedin \| threads \| hn \| news \| reviews	Platform (repeat or comma-separate for several)
category	testimonial \| bug_report \| product_idea \| complaint \| other \| misinformation	AI category
sentiment	positive \| neutral \| negative	AI sentiment
status	new \| reviewed \| done \| ignored	Triage status
intent	buying \| switching \| problem \| praise \| question \| announcement \| chatter	What the author is trying to do
speaker	customer \| prospect \| competitor \| media \| bystander	Who is talking
next_action	reply \| fix \| ask_for_testimonial \| correct \| watch \| none	Recommended next step
keyword	string	Exact matched keyword (not the monitor id)
engagement	string	Per-source floor as source:metric:min
min_urgency	integer	Lower bound, 0-100. 70+ is worth interrupting someone for.
max_urgency	integer	Upper bound, 0-100
author_handle	string	Exact author handle for a From filter (with or without @)
author_name	string	Exact author display name when no handle exists
author_url	string	Exact author profile URL fallback
search	string	Case-insensitive substring of the mention text (and OCR from images)
sort	published_at \| urgency	Order key (default published_at)
direction	asc \| desc	asc or desc (default desc)
date_preset	today \| last_24_hours \| last_7_days \| last_4_weeks \| last_30_days \| last_90_days \| last_6_months \| last_12_months \| month_to_date \| quarter_to_date \| year_to_date \| all_time	Named window, so you need not compute dates
since	string	ISO 8601 lower bound. Overrides date_preset.
until	string	ISO 8601 upper bound
cursor	string	nextCursor from the previous page
limit	integer	Page size, 1-100 (default 50)

Response

{
  "data": {
    "items": [
      {
        "id": "7b0f1e3a-1c4d-4a0a-9f2b-2f4a8c1d0e11",
        "source": "reddit",
        "url": "https://reddit.com/r/SaaS/comments/abc123",
        "author_handle": "ops_kate",
        "text": "Our analytics bill tripled. Anyone know a cheaper alternative?",
        "published_at": "2026-09-01T09:14:00.000Z",
        "engagement": {
          "upvotes": 128,
          "comments": 41
        },
        "is_relevant": true,
        "category": "complaint",
        "sentiment": "negative",
        "urgency": 72,
        "ai_summary": "User is priced out of a competitor and asking for alternatives.",
        "status": "new"
      }
    ],
    "nextCursor": "MjAyNi0wOS0wMVQwOToxNDowMC4wMDBafDdiMGYxZTNh",
    "hasMore": true
  },
  "meta": {
    "capability": "list_mentions",
    "requestId": "req_9f2b4a8c1d0e",
    "idempotencyReplayed": false,
    "docs": "https://herculeradar.com/docs/reference/list_mentions"
  }
}

Authorization

Requires the mentions:read scope. A credential without it gets 403 FORBIDDEN. Resources in projects the credential cannot reach answer 404 NOT_FOUND rather than 403, so ids cannot be probed across tenants.

REST conventions MCP setup Errors & limits