Skip to main content
GET
/
ai-visibility
curl "https://app.neariq.io/api/v1/ai-visibility?days=30&location=Austin" \
  -H "X-NearIQ-Key: niq_your_key_here"
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.
​
X-NearIQ-Key
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"

​
Query parameters

NameTypeDefaultNotes
daysinteger30Clamped between 7 and 90.
locationstringall locationsOptional 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.