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

# Analytics, Sources & Searches

> Visibility, share of voice and win rate for your app and every app the assistants name, per prompt, with the sites they cite and the searches they run.

These endpoints count over every answer in a date window, where one answer is one prompt asked to one assistant on one day. They are the numbers behind the **Overview**, **Prompts**, **Competitors** and **Sources** tabs of AI Visibility in the dashboard.

> [!NOTE]
>
> All endpoints accept an API key or a signed-in session and bill the **AI Visibility credit pool**. Reads cost **1 credit**. Hiding an app and showing it again are free. See [Pricing](https://docs.appeeky.com/docs/ai-visibility-overview.md#pricing).

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/ai-visibility/:appId/analytics` | Your app and every app named, ranked, with the previous period |
| GET | `/v1/ai-visibility/:appId/prompts` | The same metrics per tracked prompt |
| GET | `/v1/ai-visibility/:appId/sources` | Sites and pages the assistants cite, with gaps |
| GET | `/v1/ai-visibility/:appId/sources/answers` | The answers that cite one site or one page |
| GET | `/v1/ai-visibility/:appId/searches` | Web searches the assistants ran before answering |
| GET | `/v1/ai-visibility/:appId/hidden-brands` | Apps you marked as not competitors |
| POST | `/v1/ai-visibility/:appId/hidden-brands` | Hide an app |
| DELETE | `/v1/ai-visibility/:appId/hidden-brands/:key` | Show a hidden app again |

***

## Filters

`/analytics`, `/prompts`, `/sources`, `/sources/answers` and `/searches` take the same query parameters:

| Name | Type | Default | Description |
| - | - | - | - |
| country | string | `us` | Storefront. Data is kept per country |
| days | int | `30` | Trailing window ending today, 1–90 |
| from, to | string | — | Inclusive UTC days as `YYYY-MM-DD`. Used instead of `days` when both are set; the window is capped at 90 days |
| models | string | all | Comma-separated: `chatgpt`, `claude`, `gemini`, `perplexity`, `google_ai_overview` |
| intentIds | string | all | Comma-separated intent UUIDs |
| styles | string | all | Comma-separated prompt styles: `branded`, `unbranded`, `problem`, `use_case`, `comparison` |

Answers that failed, and Google searches that showed no AI Overview, are left out of every number.

***

## Analytics

```
GET /v1/ai-visibility/:appId/analytics?country=us&days=30
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "range": { "from": "2026-10-20", "to": "2026-11-18", "days": 30 },
    "previousRange": { "from": "2026-09-20", "to": "2026-10-19", "days": 30 },
    "totals": { "answers": 412, "prompts": 48, "mentions": 2310, "answersPrevious": 388 },
    "owner": {
      "name": "Your App",
      "rank": 4,
      "answers": 412,
      "mentions": 96,
      "visibilityPct": 23.3,
      "sovPct": 4.2,
      "positionAvg": 3.1,
      "winRatePct": 5.8,
      "sentimentPct": 78,
      "previous": { "answers": 388, "mentions": 61, "visibilityPct": 15.7, "sovPct": 2.9, "positionAvg": 3.8, "winRatePct": 3.1, "sentimentPct": 74 }
    },
    "brandsTotal": 57,
    "brands": [
      {
        "key": "571800810",
        "name": "Calm",
        "trackId": "571800810",
        "isOwnerApp": false,
        "rank": 1,
        "iconUrl": null,
        "answers": 412,
        "mentions": 301,
        "visibilityPct": 73.1,
        "sovPct": 13.0,
        "positionAvg": 1.6,
        "winRatePct": 41.3,
        "sentimentPct": 82,
        "previous": null
      }
    ],
    "series": {
      "bucket": "day",
      "keys": [{ "key": "__owner", "name": "Your App", "isOwnerApp": true, "iconUrl": null }],
      "points": [{ "date": "2026-11-18", "answers": 96, "values": { "__owner": 24.0 } }]
    },
    "byModel": [
      { "model": "chatgpt", "answers": 144, "owner": { "answers": 144, "mentions": 21, "visibilityPct": 14.6, "sovPct": 2.6, "positionAvg": 3.9, "winRatePct": 2.1, "sentimentPct": 75 } }
    ],
    "hiddenBrands": [{ "key": "appstoreconnect", "name": "App Store Connect" }]
  }
}
```

| Field | Description |
| - | - |
| `visibilityPct` | Share of answers that name the app |
| `sovPct` | The app's share of every app mention in those answers (share of voice) |
| `positionAvg` | Mean position where the answer gave an order; 1 is first, `null` when never ranked |
| `winRatePct` | Share of answers that put the app first |
| `sentimentPct` | 0–100, `null` without a reading |
| `previous` | The same numbers for the window before, of equal length; `null` when it has no data |
| `owner.rank`, `brands[].rank` | Place among every app named, by visibility |
| `brands[].key` | Stable id of the app: its App Store id when the name was matched, otherwise `name:` plus the normalised name. Your own app is `__owner` |
| `series` | `visibilityPct` over time for the top apps, per `day` or per `week` on long windows |
| `byModel` | Your app's numbers per assistant |

Different spellings of one app ("Sensor Tower", "SensorTower") are counted as one.

A high `visibilityPct` with a low `sovPct` means you are named, in long lists next to many others. A good `visibilityPct` with a low `winRatePct` means you are named and rarely first.

***

## Prompts

```
GET /v1/ai-visibility/:appId/prompts?country=us&days=30
```

One row per tracked prompt.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "range": { "from": "2026-10-20", "to": "2026-11-18", "days": 30 },
    "answersTotal": 412,
    "prompts": [
      {
        "promptId": "8f2c6c0e-1f6b-4c1d-9a55-6f0d2b7f3a10",
        "text": "what app helps me fall asleep to rain sounds",
        "style": "problem",
        "status": "active",
        "source": "llm",
        "intentId": "b0a1f1b2-55c1-4f0e-8a3e-0d8c2b5f7e21",
        "intentLabel": "Fall asleep to rain sounds",
        "answers": 9,
        "visibilityPct": 11.1,
        "sovPct": 2.0,
        "positionAvg": 4,
        "winRatePct": 0,
        "sentimentPct": 70,
        "webSearchPct": 66.7,
        "topBrands": [
          { "key": "571800810", "name": "Calm", "trackId": "571800810", "isOwnerApp": false, "visibilityPct": 88.9, "iconUrl": null }
        ],
        "byModel": { "chatgpt": { "answers": 3, "mentioned": 0 }, "claude": { "answers": 3, "mentioned": 1 } },
        "lastAnswerId": "0c8b8a44-2f58-4b0c-9a0d-3f1b7c2e9d55",
        "lastAnsweredAt": "2026-11-18T20:04:11.000Z"
      }
    ]
  }
}
```

`webSearchPct` is the share of the prompt's answers that cited a source, which means the assistant searched the web for it. Open `lastAnswerId` with [GET /answers/:answerId](https://docs.appeeky.com/docs/ai-visibility-answers.md).

### Compare one app with yours

Add `brand` with a key from `/analytics` (`brands[].key`):

```
GET /v1/ai-visibility/:appId/prompts?country=us&days=30&brand=571800810
```

Every prompt then carries `focus`, that app's numbers on the prompt:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"focus": { "answers": 9, "visibilityPct": 88.9, "positionAvg": 1.3 }
```

Prompts where `focus.visibilityPct` is high and your own `visibilityPct` is 0 are the questions that app wins without you.

***

## Sources

```
GET /v1/ai-visibility/:appId/sources?country=us&days=30
```

Every site the assistants cited across the app. Only answers produced with web search carry sources.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "range": { "from": "2026-10-20", "to": "2026-11-18", "days": 30 },
    "ownerDomain": "yourapp.com",
    "answersTotal": 412,
    "answersWithCitations": 263,
    "citationsTotal": 1480,
    "byType": [{ "type": "editorial", "domains": 41, "citations": 520, "sharePct": 35.1 }],
    "domains": [
      {
        "domain": "reddit.com",
        "type": "ugc",
        "answers": 58,
        "usedPct": 14.1,
        "citations": 91,
        "urlCount": 37,
        "models": ["chatgpt", "perplexity"],
        "backsOwner": false,
        "apps": ["Calm", "Headspace"],
        "isGap": true,
        "gapScore": 100,
        "topUrls": [{ "url": "https://www.reddit.com/r/sleep/comments/example", "title": "Best rain sound apps?", "answers": 6, "pageType": "discussion" }]
      }
    ],
    "urls": [
      { "url": "https://www.reddit.com/r/sleep/comments/example", "domain": "reddit.com", "title": "Best rain sound apps?", "answers": 6, "type": "ugc", "pageType": "discussion", "backsOwner": false, "apps": ["Calm"] }
    ]
  }
}
```

| Field | Description |
| - | - |
| `type` | `owner` (your site), `app_store`, `ugc` (communities), `review`, `editorial`, `reference`, `other` |
| `answers`, `usedPct` | Answers that cited the site, and their share of all answers in the window |
| `apps` | The apps the site was cited for |
| `backsOwner` | An answer cited the site next to your app |
| `isGap`, `gapScore` | Cited for other apps and never for yours. The score is 0–100 against the strongest gap |
| `pageType` | `listicle`, `comparison`, `how_to`, `review`, `store_listing`, `discussion`, `video`, `article` |

Start with the domains where `isGap` is `true`: the assistants already read them when they recommend the apps in `apps`.

### Answers behind a source

```
GET /v1/ai-visibility/:appId/sources/answers?country=us&domain=reddit.com
```

Pass `domain` or `url`, plus the [filters](#filters). Returns up to 50 answers, each with `answerId`, `promptId`, `promptText`, `modelSlug`, `fetchedAt` and the `urls` it cited from that source.

***

## Searches

```
GET /v1/ai-visibility/:appId/searches?country=us&days=30
```

What the assistants typed into a search engine before answering. ChatGPT, Claude and Gemini report their searches.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "range": { "from": "2026-10-20", "to": "2026-11-18", "days": 30 },
    "available": true,
    "answersTotal": 412,
    "answersWithQueries": 190,
    "distinctQueries": 312,
    "totalOccurrences": 540,
    "queries": [
      { "query": "best rain sounds app for sleep 2026", "occurrences": 9, "models": ["chatgpt", "claude"], "prompts": 3, "namesOwner": false }
    ],
    "terms": [{ "term": "rain sounds", "occurrences": 41 }]
  }
}
```

`available` is `false` when no searches are recorded for the app yet. `prompts` is how many tracked prompts triggered the search, and `terms` are the most common two-word phrases.

A page that ranks for these searches is a page the assistants can cite, so use them as wording for your website and your listing. Assistants often search in English even when the prompt is in another language.

***

## Hidden apps

Assistants also name things that are not your competitors: a platform, a tool from another category, a wrong match. Hide them and they are left out of `/analytics`, `/prompts` and `/sources` for that storefront, so ranks and share of voice are counted among real competitors. Stored answers are not changed.

```
GET /v1/ai-visibility/:appId/hidden-brands?country=us
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "hiddenBrands": [{ "key": "appstoreconnect", "name": "App Store Connect" }] } }
```

### Hide an app

```
POST /v1/ai-visibility/:appId/hidden-brands?country=us
```

| Field | Type | Required | Description |
| - | - | - | - |
| name | string | Yes | The app's name as `/analytics` shows it. Every spelling of it is hidden |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "hidden": { "key": "appstoreconnect", "name": "App Store Connect" } } }
```

### Show it again

```
DELETE /v1/ai-visibility/:appId/hidden-brands/:key?country=us
```

`key` comes from the list above.

***

## Code examples

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/ai-visibility/1234567890/analytics?country=us&days=30&models=chatgpt,claude" \
  -H "X-API-Key: YOUR_API_KEY"
```

```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const base = "https://api.appeeky.com/v1/ai-visibility/1234567890";
const headers = { "X-API-Key": process.env.APPEEKY_API_KEY };

const { data } = await fetch(`${base}/analytics?country=us&days=30`, { headers }).then((r) => r.json());
const leader = data.brands[0];

const prompts = await fetch(`${base}/prompts?country=us&days=30&brand=${encodeURIComponent(leader.key)}`, { headers })
  .then((r) => r.json());
const lost = prompts.data.prompts.filter((p) => p.visibilityPct === 0 && (p.focus?.visibilityPct ?? 0) > 0);
console.log(`${leader.name} is named on ${lost.length} prompts where you are not`);
```

***

## Errors

| Status | Code | When |
| - | - | - |
| 400 | INVALID\_INPUT | `/sources/answers` without `domain` or `url` |
| 400 | INVALID\_REQUEST | Hiding an app without `name` |
| 401 | — | Missing or invalid API key / JWT |
| 429 | — | Insufficient AI Visibility credits |

***

## MCP

| Tool | Description |
| - | - |
| `ai_visibility_analytics` | Your app and every app named, with the previous period |
| `ai_visibility_prompts` | Metrics per prompt; `brand` compares one app with yours |
| `ai_visibility_sources` | Cited sites and pages, with gaps |
| `ai_visibility_searches` | Searches the assistants ran |
| `ai_visibility_hidden_apps` | Apps you marked as not competitors |
| `ai_visibility_app_hide` / `ai_visibility_app_unhide` | Hide an app or show it again (free) |

***

## See also

* [Overview](https://docs.appeeky.com/docs/ai-visibility-overview.md) — how AI Visibility works, models and pricing
* [Answers](https://docs.appeeky.com/docs/ai-visibility-answers.md) — the full text behind any `answerId`
* [Runs, Opportunities & Fixes](https://docs.appeeky.com/docs/ai-visibility-runs-and-opportunities.md) — turn a gap into a fix and measure it
* [Scan settings](https://docs.appeeky.com/docs/ai-visibility-scan-settings.md) — which assistants are asked, and how often


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.