Skip to main content
NearIQ generates alerts whenever something meaningful changes in your competitive landscape or on your own listing. Each alert includes a plain-language title, a description of what changed, and an AI-generated recommendation that suggests a concrete action you can take in response. Alerts are scoped to your user account and cover both your own business and any competitors you track.

​
GET /api/v1/me/alerts

Returns recent alerts triggered for your account. Alerts are returned in reverse-chronological order. 
curl "https://neariq.io/api/v1/me/alerts?limit=50" \
  -H "X-NearIQ-Key: niq_live_..."

​
Request parameters

​
limit
number
default:"50"
Maximum number of alerts to return. Maximum value is 200.
​
unread
boolean
default:"false"
Set to true to return only alerts that have not been read.
​
type
string
Filter by alert type. See the full list of types below. Example: type=rating_drop.

​
Response fields

​
count
number
required
Number of alerts in this response.
​
alerts
object[]
required

​
Alert types

NearIQ generates alerts for the following event types. Use the exact type string in the type query parameter to filter.
TypeDescription
rating_dropA tracked competitor’s rating fell since the last check
rating_riseA tracked competitor’s rating rose since the last check
review_surgeA tracked competitor received an unusual spike in new reviews
velocity_spikeA competitor’s review velocity (rate of new reviews) has accelerated significantly
hours_changeA tracked competitor updated their opening hours
website_changeA tracked competitor changed their website URL
hiring_activityA tracked competitor posted new job listings (signal of expansion)
new_competitorNearIQ detected a new business in your category and area
own_rating_dropYour own Google rating dropped since the last check
own_rating_riseYour own Google rating rose since the last check
own_review_surgeYour own listing received an unusual spike in new reviews

​
Severity levels

Every alert carries a severity label that tells you how urgently you should act.
SeverityMeaning
infoInformational — awareness only, no immediate action required
warningNeeds attention — something changed that may affect your competitive position
opportunityCompetitive gap — a competitor is weakening while you have room to gain
dangerUrgent — your own rating or reviews are declining and action is recommended immediately

​
The recommendation field

When available, the recommendation field contains an AI-generated suggested action. For example, if a competitor’s rating drops, the recommendation might be: “This is a good time to promote your higher rating in local ads or on your homepage.” Not all alerts include a recommendation. The field is null when NearIQ does not have enough context to generate a meaningful suggestion.

​
Fetching urgent unread alerts

A common pattern is to poll for unread alerts at high severity to trigger notifications in your own system. 
import { NearIQ } from '@neariq/sdk'

const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

// Fetch all unread alerts (limit 200)
const { alerts } = await client.me.alerts({ unread: true, limit: 200 })

// Filter to danger and opportunity severities
const urgent = alerts.filter(
  (a) => a.severity === 'danger' || a.severity === 'opportunity'
)

for (const alert of urgent) {
  console.log(`[${alert.severity.toUpperCase()}] ${alert.title}`)
  if (alert.recommendation) {
    console.log(`  → ${alert.recommendation}`)
  }
}
For real-time alert delivery without polling, use webhooks and subscribe to the alert.created event.