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

# Runs, Opportunities & Fixes

> Check setup and scan status, find the intents where AI assistants recommend other apps, see which sources they cite, and track fixes from proposal to measured result.

These endpoints cover everything around the score: which apps you have set up, whether the latest scan worked, where you are missing from AI answers, which websites the assistants cite, and fixes you can ship to close the gaps.

In the dashboard this lives under **AI Visibility**: the gaps list, the cited sources, the fix cards and the scan history.

> [!NOTE]
>
> All endpoints accept an API key or a signed-in session and bill the **AI Visibility credit pool**, not your general API credits. Reads cost **1 credit**. Editing or dismissing a fix is free. Generating fixes costs **5 credits**; shipping a fix is charged like a scan. See [Pricing](https://docs.appeeky.com/docs/ai-visibility-overview.md#pricing).

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/ai-visibility/apps` | Apps you have set up for AI Visibility |
| GET | `/v1/ai-visibility/:appId/status` | Setup state, latest scan and per-model health |
| GET | `/v1/ai-visibility/:appId/storefronts` | Countries you track and countries you could add |
| GET | `/v1/ai-visibility/:appId/runs` | Recent scan runs |
| GET | `/v1/ai-visibility/:appId/runs/:runId` | One run with an excerpt of every answer |
| GET | `/v1/ai-visibility/:appId/opportunities` | Every intent classified as missing, weak or winning, plus cited sources |
| GET | `/v1/ai-visibility/:appId/intents/:intentId/sources` | Websites the assistants cite for one intent |
| GET | `/v1/ai-visibility/:appId/fixes` | Fixes and their before/after measurement |
| POST | `/v1/ai-visibility/:appId/intents/:intentId/fixes/generate` | Propose 2–4 fixes for one intent |
| POST | `/v1/ai-visibility/:appId/fixes/:fixId/ship` | Mark a fix shipped and measure its effect |
| PATCH | `/v1/ai-visibility/:appId/fixes/:fixId` | Dismiss a fix or set its target URL |

Every endpoint except `/apps` and `/storefronts` takes an optional `country` query parameter (default `us`). Data is kept per country, so pass the storefront you set the app up in.

***

## Your apps

`GET /v1/ai-visibility/apps` lists the apps that have been bootstrapped or scanned, most recently active first. By default it lists the `us` storefront; pass `?country=all` to list every country, which is how you find an app that was set up outside the US.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "apps": [
      {
        "appId": "1234567890",
        "country": "us",
        "lastScanAt": "2026-10-30T06:12:00.000Z",
        "lastBootstrapAt": "2026-10-01T09:00:00.000Z"
      }
    ]
  }
}
```

***

## Setup and scan status

`GET /v1/ai-visibility/:appId/status?country=us` answers "is this app set up, and did the last scan work?"

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "setup": {
      "country": "us",
      "language": "en",
      "enabled": true,
      "bootstrappedAt": "2026-10-01T09:00:00.000Z",
      "lastScanAt": "2026-10-30T06:12:00.000Z",
      "nextScanAt": "2026-11-02T06:00:00.000Z",
      "activeIntents": 9,
      "activePrompts": 52,
      "scanCadenceDays": 3
    },
    "latestRun": {
      "id": "run_123",
      "triggerSource": "schedule",
      "models": ["chatgpt", "perplexity"],
      "status": "partial",
      "promptsTotal": 52,
      "answersOk": 101,
      "answersFailed": 3,
      "startedAt": "2026-10-30T06:00:00.000Z",
      "completedAt": "2026-10-30T06:12:00.000Z",
      "degradedReason": null,
      "byModel": {
        "chatgpt": { "ok": 52, "failed": 0, "lastError": null },
        "perplexity": { "ok": 49, "failed": 3, "lastError": "Request timed out" }
      }
    },
    "modelHealth": {
      "perplexity": { "status": "ok", "failRate": 0.02, "lastError": null, "checkedAt": "2026-11-01T08:00:00.000Z" }
    }
  }
}
```

* `latestRun` is `null` before the first scan.
* `modelHealth` shows whether each assistant is answering normally right now. Models that are down are skipped on manual scans, so you are not charged for them.

***

## Storefronts

`GET /v1/ai-visibility/:appId/storefronts` helps you pick a country and language before you [bootstrap](https://docs.appeeky.com/docs/ai-visibility-bootstrap.md).

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "configured": ["us"],
    "suggested": [
      { "country": "us", "source": "configured" },
      { "country": "gb", "source": "store_cache" }
    ],
    "primaryLanguage": "en",
    "languages": ["de", "en", "fr"]
  }
}
```

| Field | Meaning |
| - | - |
| `configured` | Countries already set up for this app |
| `suggested` | Configured countries first, then other countries where the app is on the store |
| `primaryLanguage` | Suggested scan language |
| `languages` | Every language the app's listing ships in |

***

## Scan runs

`GET /v1/ai-visibility/:appId/runs?country=us&limit=30` lists recent runs, newest first. `limit` is 1–100 (default `30`).

| Field | Meaning |
| - | - |
| `triggerSource` | `schedule`, `manual`, `bootstrap` or `fix_remeasure` |
| `status` | `running`, `completed`, `partial` (some answers failed) or `failed` |
| `models` | Models the run asked |
| `promptsTotal`, `answersOk`, `answersFailed` | Run size and outcome |
| `failuresByModel` | Failed answers per model, e.g. `{ "perplexity": 3 }` |
| `degradedReason` | `insufficient_credits` when models were dropped to fit your remaining credits, otherwise `null` |

`GET /v1/ai-visibility/:appId/runs/:runId` returns the `run` plus one row per answer: `answerId`, `promptText`, `intentLabel`, `modelSlug`, `status`, a short `excerpt`, `mentionsCount` and `ownerMentioned`. Open the full answer with [`GET /answers/:answerId`](https://docs.appeeky.com/docs/ai-visibility-answers).

***

## Opportunities

`GET /v1/ai-visibility/:appId/opportunities?country=us&days=30` is the "where AI doesn't recommend you" view. `days` is 1–90 (default `30`).

Each active intent gets a status from its latest scores across all models:

| Status | Meaning |
| - | - |
| `missing` | Your app is in 0% of answers |
| `weak` | Your app appears, but in less than 25% of answers |
| `winning` | Your app appears in 25% or more of answers |
| `no_data` | Not scanned yet in this window |

Intents are sorted with the biggest gaps first.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "1234567890",
    "country": "us",
    "days": 30,
    "summary": { "missing": 3, "weak": 4, "winning": 2, "noData": 0 },
    "intents": [
      {
        "intentId": "int_123",
        "label": "Fall asleep faster",
        "description": null,
        "status": "missing",
        "ownerVisibilityPct": 0,
        "byModel": {
          "chatgpt": { "visibilityPct": 0, "positionAvg": null, "promptsTotal": 6, "date": "2026-10-30" }
        },
        "winners": [
          {
            "trackId": "987654321",
            "name": "Example Sleep",
            "iconUrl": "https://…",
            "mentionCount": 5,
            "sharePct": 83.3,
            "models": ["chatgpt"]
          }
        ]
      }
    ],
    "sources": {
      "ownerDomain": "example.com",
      "answersTotal": 104,
      "answersWithCitations": 41,
      "sources": [
        {
          "domain": "examplereviews.com",
          "url": "https://examplereviews.com/best-sleep-apps",
          "title": "The best sleep apps",
          "count": 12,
          "models": ["perplexity"],
          "citesOwner": false,
          "appsMentioned": ["Example Sleep"]
        }
      ]
    }
  }
}
```

`winners` are the apps recommended for that intent instead of yours, with the share of answers they appear in. `sources` lists the websites the assistants cite across the whole app; most citations come from models that search the web, such as Perplexity.

***

## Sources for one intent

`GET /v1/ai-visibility/:appId/intents/:intentId/sources?country=us&days=30` returns the same `sources` list, limited to one intent's answers: each cited domain with its most-cited URL, how many answers cited it, which models, the apps it backed, and `citesOwner` (`true` when the domain is your own website). Use it to find the pages worth getting listed on.

***

## Fixes

A fix is a concrete action for one intent, grounded in your scan data:

| `kind` | What it suggests |
| - | - |
| `publish_page` | Publish a page that answers the intent on your own site |
| `get_listed` | Get your app onto a page the assistants already cite |
| `answer_prompt` | Answer a specific prompt where you are missing |

A fix moves through these statuses:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  A[open] --> B[shipped]
  B --> C[verified]
  B --> D[no_change]
  A --> E[dismissed]
```

1. **Generate.** `POST /v1/ai-visibility/:appId/intents/:intentId/fixes/generate?country=us` proposes 2–4 fixes. It needs at least one scan of the intent; otherwise it returns `422 NO_FIXES`. Costs 5 credits.
2. **Ship.** After you make the change, call `POST /v1/ai-visibility/:appId/fixes/:fixId/ship`. Appeeky saves the intent's current numbers as the `baseline`. Optional body: `{ "targetUrl": "https://example.com/sleep" }`. Charged like a scan of your enabled models.
3. **Measure.** The next completed scan after shipping is compared with the baseline. If visibility rose by more than one point the fix becomes `verified`, otherwise `no_change`. The `result` field holds the after numbers either way.

To drop a fix, call `PATCH /v1/ai-visibility/:appId/fixes/:fixId` with `{ "status": "dismissed" }`. Send `{ "targetUrl": "…" }` instead to only change the URL.

`GET /v1/ai-visibility/:appId/fixes?country=us` lists fixes, newest first. Filter with `intentId`; dismissed fixes are hidden unless you pass `includeDismissed=true`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "fixes": [
      {
        "id": "fix_123",
        "appId": "1234567890",
        "country": "us",
        "intentId": "int_123",
        "kind": "get_listed",
        "title": "Get listed on examplereviews.com's best sleep apps page",
        "rationale": "Perplexity cites this page in 5 of 6 answers for this intent and your app is not on it.",
        "targetUrl": "https://examplereviews.com/best-sleep-apps",
        "targetPrompt": null,
        "status": "verified",
        "baseline": { "visibilityPct": 0, "avgPosition": null, "promptsWithOwner": 0, "promptsTotal": 6, "measuredAt": "2026-10-10T00:00:00.000Z", "byModel": {} },
        "result": { "visibilityPct": 33.3, "avgPosition": 3, "promptsWithOwner": 2, "promptsTotal": 6, "measuredAt": "2026-10-24T00:00:00.000Z", "byModel": {} },
        "createdAt": "2026-10-09T12:00:00.000Z",
        "shippedAt": "2026-10-10T08:00:00.000Z",
        "verifiedAt": "2026-10-24T07:00:00.000Z"
      }
    ]
  }
}
```

### Errors

| Status | Code | When |
| - | - | - |
| 403 | `TIER_LIMIT_EXCEEDED` | Your plan doesn't include AI Visibility |
| 404 | `NOT_FOUND` | Intent, run or fix not found |
| 409 | `INVALID_STATE` | Shipping a fix that is not `open` |
| 422 | `NO_FIXES` | No fix could be grounded in your data yet. Run a scan first |
| 400 | `INVALID_INPUT` | `PATCH` with a status other than `dismissed` |

***

## MCP

| Tool | Description |
| - | - |
| `ai_visibility_runs` | Recent scan runs with status and answer counts |
| `ai_visibility_run_detail` | One run with answer excerpts |
| `ai_visibility_intent_sources` | Websites cited for one intent |
| `ai_visibility_fixes_list` | Fixes with status and before/after numbers |
| `ai_visibility_fixes_generate` | Propose 2–4 fixes for an intent (5 credits) |
| `ai_visibility_fix_ship` | Mark a fix shipped and measure it (charged like a scan) |
| `ai_visibility_fix_dismiss` | Dismiss a fix (free) |

Example prompt: *"Which AI Visibility intents is my app 1234567890 missing from, and what should I fix first?"*

***

## See also

* [Overview](https://docs.appeeky.com/docs/ai-visibility-overview.md): how AI Visibility works and what it costs
* [Intents](https://docs.appeeky.com/docs/ai-visibility-intents.md) and [Prompts](https://docs.appeeky.com/docs/ai-visibility-prompts.md): manage what gets measured
* [Scan & Settings](https://docs.appeeky.com/docs/ai-visibility-scan-settings.md): run a scan now or change the cadence


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