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

# Competitors

> Discover the apps AI assistants recommend instead of (or alongside) yours

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

Across all your tracked prompts, this endpoint returns the apps that ChatGPT, Gemini, Claude, or Perplexity surfaces — ranked by how often they appear. It's the "you should know about these competitors" list: every app the assistants think a user with your tracked intents might pick instead of yours.

Use it to:

* Identify competitors you didn't realise the AI consistently mentions in your space.
* Quantify how often a known competitor is recommended versus you.
* Find ASO benchmarking targets — the apps with the highest visibility in *your* prompts are the ones to study.

***

## 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` |
| windowDays | int    | `14`      | Lookback window for the rollup. Min 1, max 90.     |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "trackId": "571800810",
      "name": "Calm",
      "iconUrl": null,
      "appearancesTotal": 38,
      "intentsCovered": 7,
      "positionAvg": 1.4,
      "visibilityPct": 79.2
    },
    {
      "trackId": "493145008",
      "name": "Headspace",
      "iconUrl": null,
      "appearancesTotal": 31,
      "intentsCovered": 6,
      "positionAvg": 2.1,
      "visibilityPct": 64.6
    },
    {
      "trackId": "337472899",
      "name": "Insight Timer",
      "iconUrl": null,
      "appearancesTotal": 18,
      "intentsCovered": 4,
      "positionAvg": 3.6,
      "visibilityPct": 37.5
    }
  ]
}
```

Returned sorted by `appearancesTotal` desc. Up to 20 rows.

| Field              | Description                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trackId`          | Canonical App Store ID. `null` if AI Visibility couldn't confidently match the assistant's spelling against the App Store (rare, usually web-only products).                                    |
| `name`             | The app name as the assistant most recently spelled it.                                                                                                                                         |
| `iconUrl`          | Reserved — currently `null`. Will be populated in a future release; use [GET /apps/:id](/docs/get-app) with `trackId` to fetch the icon today.                                                  |
| `appearancesTotal` | Total number of times this app appeared across every (prompt × model × day) within the window. One assistant mentioning it in 3 prompts on 5 days counts as 15.                                 |
| `intentsCovered`   | Number of distinct intents (out of your tracked set) where this app appeared at least once. A high number means a broad competitor; a low number means a niche one.                             |
| `positionAvg`      | Average rank in the assistants' lists when this app was mentioned. Lower is better. `null` if the assistants only mentioned the app in non-list prose.                                          |
| `visibilityPct`    | % of distinct prompts (in the window) where this app appeared. The closest single number to your own [overview](/docs/ai-visibility-overview-endpoint) `visibilityScore` for direct comparison. |

***

## Reading the table

The most useful comparison is your own `visibilityPct` (from `GET /overview`) versus the competitors here:

```
Your AI Visibility Score:  38   ← from /overview
─────────────────────────────────────
Calm visibilityPct:        79.2  ← appears in 79% of your prompts
Headspace visibilityPct:   64.6
Insight Timer visibilityPct: 37.5  ← about even with you
```

Reading the row for **Insight Timer**: it appears in roughly the same share of your tracked prompts as your own app, but at average position 3.6 (vs. probably 1–2 for Calm). This means Insight Timer is a comparably-known alternative AI surfaces *with* you, not above you.

A row where `intentsCovered` is high and `positionAvg` is low is a competitor that's actively winning the same buyer journeys you target. That's where your ASO effort and any AI-assistant-targeted content (review-rich blogs, listicles in major publications) will move the needle the most.

***

## Code examples

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

  # 30-day window, Perplexity
  curl "https://api.appeeky.com/v1/ai-visibility/1234567890/competitors?country=us&model=perplexity&windowDays=30" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Compare AI competitor sets across all 4 models
  const models = ["chatgpt", "claude", "gemini", "perplexity"];
  const all = await Promise.all(
    models.map((m) =>
      fetch(
        `https://api.appeeky.com/v1/ai-visibility/1234567890/competitors?model=${m}&windowDays=14`,
        { headers: { "X-API-Key": "YOUR_API_KEY" } }
      ).then((r) => r.json())
    )
  );

  models.forEach((m, i) => {
    console.log(`\n=== ${m} ===`);
    all[i].data.slice(0, 5).forEach((c, idx) => {
      console.log(`${idx + 1}. ${c.name.padEnd(20)}  visibility=${c.visibilityPct}%  pos=${c.positionAvg}`);
    });
  });
  ```

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

  r = requests.get(
    "https://api.appeeky.com/v1/ai-visibility/1234567890/competitors",
    params={"country": "us", "model": "chatgpt", "windowDays": 30},
    headers={"X-API-Key": "YOUR_API_KEY"},
  )
  for c in r.json()["data"][:10]:
      print(f"{c['name']:<24}  vis={c['visibilityPct']}%  intents={c['intentsCovered']}")
  ```
</CodeGroup>

***

## Pattern: enrich with App Store metadata

The endpoint returns `trackId` for resolved competitors. To get icons, ratings, and developer info for the dashboard:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const competitors = (
  await fetch(
    "https://api.appeeky.com/v1/ai-visibility/1234567890/competitors?model=chatgpt",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  ).then((r) => r.json())
).data;

const enriched = await Promise.all(
  competitors
    .filter((c) => c.trackId)
    .slice(0, 5)
    .map(async (c) => {
      const meta = await fetch(
        `https://api.appeeky.com/v1/apps/${c.trackId}`,
        { headers: { "X-API-Key": "YOUR_API_KEY" } }
      ).then((r) => r.json());
      return { ...c, iconUrl: meta.data.iconUrl, rating: meta.data.averageUserRating };
    })
);
```

Or use the dedicated [Similar Apps](/docs/get-similar-apps) endpoint if you want App Store algorithm-derived competitors instead of AI-derived ones — the two sets are often different in interesting ways.

***

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

* [Overview endpoint](/docs/ai-visibility-overview-endpoint) — your own visibility, comparable side-by-side
* [Intents](/docs/ai-visibility-intents) — per-intent `topApps` breakdown drives this benchmark
* [Get app](/docs/get-app) — fetch icons + ratings for the resolved `trackId`s
* [Similar Apps](/docs/get-similar-apps) — App Store algorithm's view of "similar" apps