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

# ASO Decision Brief

> Orchestrated ASO summary — audit, opportunities, storefront readiness, optional intent clusters, multi-country

```
GET /v1/aso/brief/:appId
```

Returns a **decision-oriented package** for ASO: it runs the same work as a full [ASO audit](/docs/aso-audit) and [keyword opportunities](/docs/aso-opportunities) in parallel, adds a **storefront readiness** score (creative + metadata + ASO blend), optionally **semantic intent clusters** on opportunity keywords, and supports **multi-country** briefs. Use the individual endpoints when you need full raw reports.

Details on intent clustering: [ASO Intent Clusters](/docs/aso-intent-clusters).

***

## 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 (ignored when `countries` is set)                                                                                                                                                                     |
| countries         | string | —       | Comma-separated ISO codes (e.g. `us,gb,de`) for **per-country** briefs; see multi-country below                                                                                                                        |
| fresh             | bool   | `false` | If `true` or `1`, forces a fresh re-analysis (slower)                                                                                                                                                                  |
| intentClusters    | bool   | `false` | If `true` or `1`, group opportunity keywords into **semantic intent clusters** (**+2 credits**)                                                                                                                        |
| semanticExpansion | bool   | `false` | If `true` or `1`, expand the brief's strongest opportunity keywords through embedding similarity and surface \~30 fresh keyword candidates the audit/opportunities pipeline didn't already know about (**+2 credits**) |

***

## Response (single country)

| Section               | Description                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary`             | One-line `headline`, ASO score, grade, keyword stats                                                                                                                       |
| `storefrontReadiness` | **0–100** combined score: ASO core, creative (visuals + screenshot count from audit), metadata fit; `gradeLabel` + `summary`                                               |
| `intentClusters`      | Present when `intentClusters=1`: clusters with `label`, `keywords`, `avgOpportunityScore`, `prioritizeClusterId`, or `skipped` + `reason` if clustering cannot be returned |
| `prioritizedActions`  | Audit + opportunities + optional **intent** action (“Prioritize this intent group…”)                                                                                       |
| `opportunitiesTop`    | Up to 10 opportunity rows                                                                                                                                                  |
| `meta`                | `warnings` if clustering skipped or failed                                                                                                                                 |

***

## Multi-country

Use **`?countries=us,gb,de`** (same rules as [keyword ranks](/docs/get-keyword-ranks) / `countries` list).\
Response shape:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "913335252",
    "countries": ["de", "gb", "us"],
    "results": {
      "us": { "...": "same shape as single-country brief" },
      "gb": { },
      "de": { }
    }
  }
}
```

**Credits:** base **5** × **number of countries** in `countries` (minimum 1). **+2** when `intentClusters=1` (flat add-on for the whole request).

***

## Code examples

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Single storefront + optional intent clusters
  curl "https://api.appeeky.com/v1/aso/brief/913335252?country=us&intentClusters=1" \
    -H "X-API-Key: YOUR_API_KEY"

  # Multi-country
  curl "https://api.appeeky.com/v1/aso/brief/913335252?countries=us,gb,de" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({
    countries: "us,gb",
    intentClusters: "true",
  });
  const res = await fetch(
    `https://api.appeeky.com/v1/aso/brief/913335252?${params}`,
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  if (data.results) console.log(Object.keys(data.results));
  else console.log(data.storefrontReadiness.score);
  ```
</CodeGroup>

***

## Credits

* **5 × (country multiplier)** — multiplier is the number of valid `countries` codes, or **1** when only `country` is used (same model as [keyword metrics](/docs/keyword-metrics) / ranks).
* **+2** when `intentClusters=1` (intent clustering add-on).

See [Rate limits](/docs/rate-limits). Response header `X-Credit-Cost` reflects the final charge.

***

## Errors

| Status | Code               | When                                               |
| ------ | ------------------ | -------------------------------------------------- |
| 400    | INVALID\_APP\_ID   | Missing or non-numeric app ID                      |
| 400    | INVALID\_COUNTRIES | `countries` set but no valid codes                 |
| 404    | APP\_NOT\_FOUND    | App unavailable or no data for a requested country |
| 401    | —                  | Missing or invalid API key                         |
| 429    | —                  | Insufficient monthly credits                       |

***

<Tip>
  **MCP:** `aso_brief` — use `countries` and `intent_clusters` arguments. See [MCP Server](/docs/mcp).
</Tip>