Run an App Audit - prioritised ASO actions, metadata rewrites and findings with evidence (first one free).

POSThttps://api.appgoat.ai/v1/apps/{app}/audit

100+ credits100 (the first audit of an organization is free)operationId runAppAudit

Refreshes the listing, tags recent reviews, probes ~20 search terms (popularity, difficulty, the app's rank, relevance), compares competitors, then writes a prioritised report: report.actions (what to do first, with the evidence and a playbook), report.metadata (title / subtitle / keyword-field rewrites within the character limits) and report.findings (deterministic checks with numbers). Every statement in the narrative is checked against the measured facts; unsupported ones are dropped. Takes 1-3 minutes: with wait=true (default) the call blocks up to ~25 s, then answers 202 with the audit id; poll GET /v1/audits/{id} (free). The shareable page is url (appgoat.ai/r/..., not indexed). An audit of the same app, country and mode from the last 24 h is returned again for 0 credits unless fresh=true. Failed audits are never charged: one that fails within wait costs 0, one that fails after the 202 is refunded automatically (the refund shows on the same request in your usage logs).

Request

curl -X POST "https://api.appgoat.ai/v1/apps/com.spotify.music/audit" \
  -H "x-api-key: $APPGOAT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"country":"us","mode":"full","wait":true,"fresh":false,"free_only":false,"white_label":false,"label":"string"}'

const res = await fetch("https://api.appgoat.ai/v1/apps/com.spotify.music/audit", {
  method: 'POST',
  headers: {
    "x-api-key": process.env.APPGOAT_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({"country":"us","mode":"full","wait":true,"fresh":false,"free_only":false,"white_label":false,"label":"string"}),
});
const { data, meta } = await res.json();

import os, requests

res = requests.post(
    "https://api.appgoat.ai/v1/apps/com.spotify.music/audit",
    headers={"x-api-key": os.environ["APPGOAT_API_KEY"]},
    json={"country":"us","mode":"full","wait":True,"fresh":False,"free_only":False,"white_label":False,"label":"string"}
)
body = res.json()

Path parameters

appstringrequired

Any app identifier: App Store id (284882215, id284882215), Play package (com.spotify.music), Apple bundle id (com.spotify.client), store URL (URL-encoded), apple:<id> / play:<id>, or a name (spotify).

Query parameters

store"apple" | "play"

Disambiguates {app} (a bundle id vs a Play package, or a name).

Request body

JSON.

countrystring

One storefront.

mode"full" | "lite"

lite = cached data, fewer reviews and keywords (cheaper and faster for us; same price).

waitboolean

freshboolean

Run again even if a recent audit exists.

free_onlyboolean

Only run when it is the free first audit (402 free_audit_used otherwise).

white_labelboolean

Studio: the report page carries your branding (brand name, logo, accent colour, CTA, footer; set them in the dashboard under Settings → Report branding) instead of AppGoat's. 402 plan_limit on other plans. Re-using a recent audit applies the branding to it for 0 credits.

labelstring | null

Your label for the audit list, e.g. the client or prospect name.

Response

200 with data: Audit. See the envelope for meta.

idstring

slugstring

urlstring

Shareable report page (not indexed by search engines).

status"queued" | "running" | "batched" | "done" | "failed"

storeStore

app_idstring

countrystring

mode"full" | "lite"

titlestring | null

icon_urlstring | null

scoreinteger | null

white_labelboolean

The report page carries your branding.

brandingany

labelstring | null

reportany

findingsFinding[]

Available as soon as the facts are gathered.

factsobject

Only with include=facts: listing, ratings, reviews, keywords (probe), competitors, localization, changes, gaps.

credits_chargedinteger

freeboolean

This was the organization's free first audit.

errorstring | null

created_atstring

finished_atstring | null

Example

{
  "data": {
    "id": "aud_3fK9aQ2mXc81LpRt",
    "slug": "string",
    "url": "https://appgoat.ai",
    "status": "queued",
    "store": "apple",
    "app_id": "324684580",
    "country": "us",
    "mode": "full",
    "title": "Spotify: Music and Podcasts",
    "icon_url": "string",
    "score": 1,
    "white_label": false,
    "branding": null,
    "label": "string",
    "report": null,
    "findings": [
      {
        "id": "string",
        "type": "striking_distance",
        "section": "metadata",
        "severity": "high",
        "title": "#14 for \"habit tracker adhd\" (not in the title or subtitle)",
        "evidence": {},
        "fix": "string",
        "playbook": "string"
      }
    ],
    "facts": {},
    "credits_charged": 1,
    "free": false,
    "error": "string",
    "created_at": "2026-10-22T10:00:00Z",
    "finished_at": "2026-10-22T10:00:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9981,
    "request_id": "req_123"
  }
}

Status codes

200

The finished audit (or a recent one re-used).

202

Still running; poll GET /v1/audits/{data.id}.

400invalid_param

A parameter is missing or invalid (error.param names it).

401invalid_api_key

Missing or invalid API key.

402insufficient_creditsplan_limit

insufficient_credits (the call costs more than you have left; nothing was done) or plan_limit (a feature of a higher plan).

404app_not_found

Nothing matches {app}, or the store does not have it.

429rate_limited

Too many requests per second for your plan.