AI Search Visibility

GET /api/v1/ai-visibility returns the active business’s stored AI answer presence for Growth plans and higher. The public v1 response is limited to raw stored facts such as mentions, engines, queries, positions, and collected snippets; generated scores and recommendations remain dashboard-only. The dashboard also exposes POST /api/businesses/me/ai-visibility/check for authenticated users who can run an immediate visibility check from the AI Visibility tab. Use an API key with the ai-visibility:read scope.

string

required

Your API key from Settings > API Keys

curl "https://app.neariq.io/api/v1/ai-visibility?days=30&location=Austin" \
  -H "X-NearIQ-Key: niq_your_key_here"

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

Query parameters

Name	Type	Default	Notes
`days`	integer	`30`	Clamped between `7` and `90`.
`location`	string	all locations	Optional city name. When present, the response is filtered to checks run for that city.

Response

localMetricsAvailable is false for online/no-location businesses, so clients should hide region selectors and local/GEO-only metrics while still showing AI visibility query evidence.

{
  "connected": true,
  "businessId": "uuid",
  "businessName": "NearIQ Demo Fitness",
  "days": 30,
  "availableLocations": [
    { "city": "Austin", "state": "TX", "label": "Austin, TX" },
    { "city": "Round Rock", "state": "TX", "label": "Round Rock, TX" }
  ],
  "selectedLocation": "Austin",
  "dailyChecksRemaining": 17,
  "dailyChecksLimit": 20,
  "localMetricsAvailable": true,
  "engines": {
    "answer_engine": {
      "mentioned": 3,
      "total": 8,
      "percentage": 37,
      "averagePosition": 2.3
    }
  },
  "topQueries": [
    {
      "query": "best gym austin",
      "mentioned": true,
      "engines": ["answer_engine"],
      "position": 2,
      "mentionText": "NearIQ Demo Fitness is known for...",
      "competitorsMentioned": ["Example Competitor"],
      "checkedAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "lastChecked": "2026-05-01T00:00:00.000Z",
  "recent": []
}

Dashboard on-demand checks

POST /api/businesses/me/ai-visibility/check runs a fresh dashboard check for the active business and optional selected location. This route uses the signed-in dashboard session, not a public API key.

cURL

curl "https://app.neariq.io/api/businesses/me/ai-visibility/check" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "location": "Austin" }'

Run this from an authenticated dashboard session. Do not paste session cookies into scripts, docs, support messages, or client-side code. The response includes the daily quota state:

{
  "success": true,
  "checksRun": 20,
  "queriesChecked": 5,
  "dailyRemaining": 17,
  "dailyLimit": 20,
  "checkLocation": "Austin"
}

If the user has exhausted the daily quota, the route returns:

{
  "error": "Daily check limit reached. Resets at midnight UTC.",
  "dailyRemaining": 0,
  "dailyLimit": 20
}

Access

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

API Reference

Endpoints

Webhooks

AI Search Visibility

Query parameters

Response

Dashboard on-demand checks

Access

​Query parameters

​Response

​Dashboard on-demand checks

​Access

Query parameters

Response

Dashboard on-demand checks

Access