Skip to main content
This page covers two related groups of endpoints:
  • POST /scan — kick off an immediate re-scan (useful right after a metadata change or when you want fresh data without waiting for the daily run).
  • GET / PUT /settings — choose which AI models to scan, how often the scheduled scans run, and whether AI Visibility is enabled at all for the app.

​
Trigger an on-demand scan

POST /v1/ai-visibility/:appId/scan
Sends every active prompt for the app to every enabled AI model, parses the answers, resolves competitor app names, and updates the daily roll-up. Returns immediately (HTTP 201); the actual work runs in the background and full results land in GET /overview within roughly 3–6 minutes.
Scheduled scans run automatically — you should only need this endpoint when you want fresh data now (after a launch, a new feature, a metadata change, or right after adding new intents/prompts).

​
Path parameters

NameTypeRequiredDescription
appIdstringYesApple App ID (numeric)

​
Body

No body is required. The scan uses the app’s saved settings (country, models, language).

​
Response

{
  "data": {
    "taskRunId": "run_x9z2...",
    "promptsTotal": 48,
    "models": ["chatgpt", "claude", "gemini", "perplexity"],
    "estimatedCost": 1536
  }
}
FieldDescription
taskRunIdTrigger.dev run id for the orchestrator. Useful for support requests but not normally needed.
promptsTotalNumber of active prompts that will be sent.
modelsThe models that will receive each prompt — derived from your settings, capped at your plan’s maxModels and filtered to providers Appeeky has API keys for.
estimatedCostAI Visibility credits this scan will consume. Same value as the X-Credit-Cost header.
If there are no active prompts the call returns 400 NO_PROMPTS. Run bootstrap first or add intents + prompts manually.

​
Same-day idempotency

Each (prompt × model × day) is fingerprinted before the model call. Re-running /scan later the same day won’t charge you for a second round of model calls — the existing answers are reused. So you can hit “Refresh” in the UI without worrying about double-billing. If you really want a re-query on the same day (e.g. you suspect a flaky earlier answer), pause the prompt, scan, then re-activate it; or wait until tomorrow’s automatic scan.

​
Get or update settings

​
GET /v1/ai-visibility/:appId/settings

Returns the current scanning configuration for the app, plus the list of AI providers Appeeky currently has credentials for (so you can render a UI that only offers configurable options). 
{
  "data": {
    "settings": {
      "ownerEmail": "you@example.com",
      "appId": "1234567890",
      "country": "us",
      "language": "en",
      "enabled": true,
      "models": ["chatgpt", "perplexity"],
      "scanCadenceDays": 3,
      "nextScanAt": "2026-05-15T08:00:00.000Z",
      "lastScanAt": "2026-05-12T08:01:14.221Z",
      "lastBootstrapAt": "2026-05-10T15:42:08.001Z"
    },
    "availableModels": ["chatgpt", "claude", "gemini", "perplexity"],
    "tier": {
      "planId": "small",
      "enabled": true,
      "maxModels": 2,
      "maxApps": 2,
      "maxCountries": 1
    },
    "aiVisibilityCredits": {
      "limit": 8000,
      "used": 1944,
      "remaining": 6056,
      "estimatedMonthlyCost": 5760,
      "resetDate": "2026-06-12T00:00:00.000Z"
    }
  }
}
settings is null until you’ve called bootstrap at least once. tier reflects the caller’s current plan and the per-plan AI Visibility caps (see pricing overview). Use it in your dashboard to grey out model toggles the user can’t actually enable: e.g. on the small plan above, only the first 2 entries in availableModels are selectable. aiVisibilityCredits is the dedicated credit bucket for AI Visibility (separate from your general API quota). estimatedMonthlyCost is a forecast based on the current cadence and enabled models — (prompts × Σ(model_cost)) × (30 / scanCadenceDays). Use it to surface “you’ll spend ~5,760 / 8,000 this month” before the user commits to a setting change.

​
PUT /v1/ai-visibility/:appId/settings

{
  "enabled": true,
  "models": ["chatgpt", "perplexity"],
  "scanCadenceDays": 1,
  "language": "en"
}
FieldTypeDescription
enabledboolMaster switch. false stops scheduled scans (existing data and intents stay).
modelsstring[]Which AI models to scan. Subset of availableModels. The chatgpt model is the most commonly enabled — most users start with one or two and expand later.
scanCadenceDaysint0 disables scheduled scans, 1 = daily, 3 = every 3 days (default), 7 = weekly, max 30. The next scan after a settings change is scheduled scanCadenceDays from now. AI recommendations change slowly, so 3-day cadence captures most movement at a third of daily’s credit cost.
languagestringISO 639-1, biases newly-generated prompts. Doesn’t affect existing prompts.
All fields are optional — only the ones you provide are updated.

​
Cost controls

Both manual and scheduled scans bill against the dedicated AI Visibility credit bucket (api_plans.ai_visibility_monthly_credits) — not your general API quota. Each call costs per (prompt × model), summed across every model you’ve enabled.
ModelCredits per call
chatgpt9
claude15
gemini5
perplexity3
A typical setup of 8 intents × 6 prompts = 48 prompts at the default 3-day cadence (10 scans/month) burns:
Models enabledCredits per scanMonthly (3-day cadence)Monthly (daily cadence)
chatgpt only48 × 9 = 432~4,300~13,000
chatgpt + perplexity48 × 12 = 576~5,800~17,300
All four48 × 32 = 1,536~15,400~46,100
The exact estimate for your current setup is returned by GET /settings → aiVisibilityCredits.estimatedMonthlyCost. Manual /scan calls return the per-call charge in X-Credit-Cost (and the response body’s estimatedCost).

​
What happens when the bucket runs low

TriggerBehavior
Manual /scanHard fail — the API returns 429 AI_VISIBILITY_QUOTA_EXCEEDED with the requested cost and your remaining balance. No scan runs, no credits deducted.
Scheduled cron scanGraceful degrade — the orchestrator drops models in cost-descending order (claude → gemini → perplexity), keeping chatgpt as the most user-valuable fallback, until the scan fits remaining budget. The dropped models are recorded on the run row (models_dropped, degraded_reason). When even chatgpt-only doesn’t fit, the scan is skipped entirely and next_scan_at is pushed out 24h.
You can detect a degraded scan in the dashboard by checking ai_visibility_runs.models_dropped — it’s empty when the full requested set ran, otherwise it lists the silently-removed models so you can prompt the user to upgrade.

​
Tier limits on models[]

The PUT endpoint enforces a per-plan cap on how many models you can enable simultaneously:
PlanMonthly AI Visibility creditsAllowed models
Free0— (AI Visibility unavailable)
Indie3,0001
Starter8,0002
Growth20,0004 (all)
Pro50,0004 (all)
Enterprise150,0004 (all)
If you submit models: ["chatgpt", "claude"] on the Indie plan, the API returns 403 TIER_LIMIT_EXCEEDED and your settings stay unchanged. A practical recommendation:
  • Start with ["chatgpt"]. It’s the dominant assistant by usage and gives you the most signal per credit.
  • Add perplexity when you want web-grounded comparisons (Perplexity returns citations alongside the answer — useful for understanding why the assistant picked an app).
  • Add claude and gemini when you have evidence your audience uses them. Note that claude is the most expensive at 15 credits/call — the scheduler will drop it first when budget gets tight.

​
Code examples

# Manual scan
curl -X POST "https://api.appeeky.com/v1/ai-visibility/1234567890/scan" \
  -H "X-API-Key: YOUR_API_KEY"

# Read settings
curl "https://api.appeeky.com/v1/ai-visibility/1234567890/settings?country=us" \
  -H "X-API-Key: YOUR_API_KEY"

# Switch to weekly scans on chatgpt + perplexity
curl -X PUT "https://api.appeeky.com/v1/ai-visibility/1234567890/settings?country=us" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "models": ["chatgpt", "perplexity"], "scanCadenceDays": 7 }'

# Pause AI Visibility for this app
curl -X PUT "https://api.appeeky.com/v1/ai-visibility/1234567890/settings?country=us" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

​
Credits

EndpointCostBucket
POST /scanDynamic — Σ(model credit cost) × prompts_count. Returned in X-Credit-Cost.AI Visibility
GET /settings1 creditAI Visibility
PUT /settingsFree—
All AI Visibility endpoints meter against api_plans.ai_visibility_monthly_credits. The middleware sets X-AiVisibility-Limit and X-AiVisibility-Remaining headers on the response so dashboards can render the current bucket state.

​
Errors

StatusCodeWhen
400NO_PROMPTSApp has no active prompts — run bootstrap first
400INVALID_APP_IDMissing or non-numeric app ID
403TIER_LIMIT_EXCEEDEDmodels[] exceeds your plan’s max, or AI Visibility is unavailable on your plan
401—Missing or invalid API key / JWT
429AI_VISIBILITY_QUOTA_EXCEEDEDInsufficient AI Visibility credits — top up, downgrade your model selection, or wait for the quota to reset

​
See also