Runs, Opportunities & Fixes

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.

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.

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.

{
  "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?”

{
  "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.

{
  "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.

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.

{
  "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:

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

{
  "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?”

My Data - Appeeky Web

AI Visibility

SEO for Apps

Growth Channels

UGC & Phones

API

Your apps

Setup and scan status

Storefronts

Scan runs

Opportunities

Sources for one intent

Fixes

Errors

MCP

See also

​API

​Your apps

​Setup and scan status

​Storefronts

​Scan runs

​Opportunities

​Sources for one intent

​Fixes

​Errors

​MCP

​See also

API

Your apps

Setup and scan status

Storefronts

Scan runs

Opportunities

Sources for one intent

Fixes

Errors

MCP

See also