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

# Overview Endpoint

> AI Visibility Score, sentiment, and coverage — the data behind the dashboard gauge

```
GET /v1/ai-visibility/:appId/overview
```

Returns the **headline numbers** for AI Visibility — the AI Visibility Score gauge, the sentiment percentage, and how many of your tracked intents you actually showed up in. One row per `(app, country, model)` for the most recent scan, plus the previous-period values for trend arrows.

Use this endpoint to populate the top of a dashboard. For per-intent breakdown, see [GET /intents](/docs/ai-visibility-intents).

***

## Path parameters

| Name  | Type   | Required | Description            |
| ----- | ------ | -------- | ---------------------- |
| appId | string | Yes      | Apple App ID (numeric) |

## Query parameters

| Name    | Type   | Default   | Description                                                                             |
| ------- | ------ | --------- | --------------------------------------------------------------------------------------- |
| country | string | `us`      | ISO country code                                                                        |
| model   | string | `chatgpt` | One of `chatgpt`, `claude`, `gemini`, `perplexity`. Each model is scored independently. |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "modelSlug": "chatgpt",
    "scoredAt": "2026-05-12",
    "visibilityScore": {
      "score": 92,
      "label": "excellent"
    },
    "sentimentPct": 75,
    "intentsTotal": 8,
    "intentsCovered": 7,
    "trend": {
      "visibilityScorePrev": 88,
      "sentimentPctPrev": 71
    }
  }
}
```

| Field                       | Description                                                                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scoredAt`                  | UTC date (`YYYY-MM-DD`) of the most recent scan rolled up. `null` if the app has never been scanned for this `(country, model)`.                    |
| `visibilityScore.score`     | **0–100 composite**. Weighted 70% by visibility (% of tracked prompts where your app appeared, position-weighted), 30% by sentiment when mentioned. |
| `visibilityScore.label`     | One of `excellent` (≥80), `good` (≥60), `fair` (≥40), `poor` (less than 40).                                                                        |
| `sentimentPct`              | Average sentiment of the assistant when it talked about your app, normalised to a 0–100% scale. `null` if your app wasn't mentioned.                |
| `intentsTotal`              | Number of active intents tracked for this app.                                                                                                      |
| `intentsCovered`            | Number of those intents in which your app appeared **at least once** in the most recent scan.                                                       |
| `trend.visibilityScorePrev` | The same `visibilityScore.score` from the previous scan day. `null` if you don't have prior data yet.                                               |
| `trend.sentimentPctPrev`    | Same idea for sentiment.                                                                                                                            |

When the app has been bootstrapped but not yet scanned, the response is the same shape but `scoredAt: null`, `score: 0`, `label: "poor"`, `sentimentPct: null`, `intentsCovered: 0`.

***

## Reading the score

The score is a **single composite gauge**. If you want to interpret it:

* **80–100 (excellent)**: AI assistants reliably recommend your app for the intents you care about, near the top of their lists, with positive framing.
* **60–79 (good)**: You're a top-of-mind option but not always the first one mentioned. Look at per-intent visibility to find where you're weak.
* **40–59 (fair)**: You appear sometimes, often near the end of lists or with neutral language. Significant ASO + content opportunities.
* **0–39 (poor)**: AI assistants rarely surface you for these intents. Consider whether your intents accurately reflect what you do, and whether your app's discoverability outside the App Store (web presence, reviews, mentions in content the assistants train on) is enough.

***

## Code examples

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/ai-visibility/1234567890/overview?country=us&model=chatgpt" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({ country: "us", model: "chatgpt" });
  const res = await fetch(
    `https://api.appeeky.com/v1/ai-visibility/1234567890/overview?${params}`,
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();

  console.log(`AI Visibility: ${data.visibilityScore.score} (${data.visibilityScore.label})`);
  console.log(`Sentiment: ${data.sentimentPct}%`);
  console.log(`Intents: ${data.intentsCovered}/${data.intentsTotal} covered`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  r = requests.get(
    "https://api.appeeky.com/v1/ai-visibility/1234567890/overview",
    params={"country": "us", "model": "chatgpt"},
    headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = r.json()["data"]
  print(f"Score: {data['visibilityScore']['score']} ({data['visibilityScore']['label']})")
  ```
</CodeGroup>

***

## Pattern: render gauges for all enabled models side-by-side

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const models = ["chatgpt", "claude", "gemini", "perplexity"];
const all = await Promise.all(
  models.map((m) =>
    fetch(
      `https://api.appeeky.com/v1/ai-visibility/1234567890/overview?country=us&model=${m}`,
      { headers: { "X-API-Key": "YOUR_API_KEY" } }
    ).then((r) => r.json())
  )
);
all.forEach((res, i) =>
  console.log(`${models[i]}: ${res.data.visibilityScore.score}`)
);
```

You'll typically see different scores per model — a 92 on ChatGPT and a 58 on Gemini is meaningful signal.

***

## Credits

* **2 credits** per call.

***

## Errors

| Status | Code             | When                             |
| ------ | ---------------- | -------------------------------- |
| 400    | INVALID\_APP\_ID | Missing or non-numeric app ID    |
| 401    | —                | Missing or invalid API key / JWT |
| 429    | —                | Insufficient monthly credits     |

***

## See also

* [Bootstrap](/docs/ai-visibility-bootstrap) — required before this endpoint returns scored data
* [Intents endpoint](/docs/ai-visibility-intents) — per-intent breakdown that drives the score
* [Competitors](/docs/ai-visibility-competitors) — apps appearing alongside or instead of you
* [AI Visibility overview](/docs/ai-visibility-overview) — concept page