> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Engagement Report Card

> Read engagement and listing-activity signals for the active business.

`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.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/v1/behavioral-signals" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```

  ```javascript JavaScript theme={null}
  const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
  const signals = await neariq.behavioralSignals.get()
  ```
</RequestExample>

## Response

```json theme={null}
{
  "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`.