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

# AI Search Visibility

> Read AI answer visibility for the active business.

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

<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/ai-visibility?days=30&location=Austin" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```

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

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

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

```bash cURL theme={null}
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:

```json theme={null}
{
  "success": true,
  "checksRun": 20,
  "queriesChecked": 5,
  "dailyRemaining": 17,
  "dailyLimit": 20,
  "checkLocation": "Austin"
}
```

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

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