Engagement Report Card

GET /api/v1/behavioral-signals returns raw stored facts for the active business’s engagement and listing activity compared with tracked competitors. Generated grades, percentiles, scores, and recommendations remain dashboard-only. This endpoint is available on Growth plans and higher. Use an API key with the analytics:read scope.

string

required

Your API key from Settings > API Keys

curl "https://app.neariq.io/api/v1/behavioral-signals" \
  -H "X-NearIQ-Key: niq_your_key_here"

const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
const signals = await neariq.behavioralSignals.get()

Response

{
  "connected": true,
  "businessId": "uuid",
  "businessName": "NearIQ Demo Fitness",
  "signals": {
    "reviewResponseRate": {
      "value": 45,
      "displayValue": "45%",
      "unit": "%",
      "benchmark": 72,
      "benchmarkDisplay": "72%",
      "trend": "stable",
      "higherIsBetter": true
    },
    "reviewResponseTime": {
      "value": 48,
      "displayValue": "48h",
      "unit": "hours",
      "benchmark": 12,
      "benchmarkDisplay": "12h",
      "trend": "unknown",
      "higherIsBetter": false
    }
  },
  "competitorComparison": [
    {
      "id": "uuid",
      "name": "NearIQ Demo Fitness",
      "isYou": true,
      "metrics": {
        "reviewResponseRate": 45,
        "reviewResponseTimeHours": 48,
        "reviewVelocityMonthly": 3.2,
        "photoCount": 42,
        "postFrequencyMonthly": null,
        "reviewRecencyDays": 8
      }
    }
  ],
  "dataCoverage": {
    "competitors": 4,
    "reviews": true,
    "snapshots": true,
    "listing": true,
    "posts": false
  }
}

Signals

Signals include values, display text, stored benchmarks, trends, units, and whether a higher value is better. The competitor comparison table returns raw metric values for each row so API consumers can apply their own scoring model.

Signal	Meaning
`reviewResponseRate`	Percent of visible reviews with an owner reply.
`reviewResponseTime`	Average time between review publication and owner reply. Uses cached `competitor_reviews_cache.avg_response_hours` when available, then falls back to stored review timestamps.
`reviewVelocity`	Estimated new reviews per month from snapshots or cached review dates.
`photoCount`	Listing photo count when available from cached listing data.
`postFrequency`	Monthly listing post activity when collected.
`reviewRecency`	Days since the newest visible review. Lower is better.

Access

The endpoint uses the caller’s active personal or organization business context. Organization members only receive data for businesses they can access. Accounts below Growth receive 403. API keys without analytics:read receive 403 requiredScope.

API Reference

Endpoints

Webhooks

Engagement Report Card

Response

Signals

Access

​Response

​Signals

​Access

Response

Signals

Access