---
title: "Look up detailed App Store metadata for up to 10 apps"
method: POST
path: "/v1/apps/lookup"
tags: ["Data"]
---

# Look up detailed App Store metadata for up to 10 apps

`POST /v1/apps/lookup`

## Request

- Base URL: `https://api.asoskill.com`
- URL: `https://api.asoskill.com/v1/apps/lookup`
- Auth: HTTP bearer

Returns platform-specific metadata for one to ten App Store IDs. A successful response costs one credit.

## Request body

- AppLookupRequest
  - `appIds` string[], required
  - `storefront` string: Two-letter App Store storefront code; normalized to uppercase
  - `platform` 'iphone' | 'ipad' | 'mac' | 'appletv' | 'watch' | 'vision'

## Response `200`

App details; costs one credit for the complete request

- AppLookupResponse
  - `storefront` string, required
  - `platform` 'iphone' | 'ipad' | 'mac' | 'appletv' | 'watch' | 'vision', required
  - `apps` AppDetails[], required
    - `appId` string, required
    - `developer` string, required
    - `iconUrl` string, uri, required
    - `name` string, required
    - `subtitle` string, nullable, required
    - `categories` string[], required
    - `rating` AppRating, required
      - `average` number, required
      - `count` integer, required
      - `one` integer, required
      - `two` integer, required
      - `three` integer, required
      - `four` integer, required
      - `five` integer, required
    - `categoryRanking` CategoryRanking, required
      - `chart` string, required
      - `category` string, required
      - `position` integer, required
    - `currentVersionNumber` string, required
    - `currentVersionReleasedAt` string, date-time, required
    - `versionHistory` VersionHistoryItem[], required
      - `versionDisplay` string, required
      - `releaseTimestamp` string, date-time, required
    - `screenshots` string[], required
    - `description` string, required
    - `paid` boolean, required
  - `missingAppIds` string[], required
  - `cache` 'hit' | 'refresh' | 'stale', required
  - `fetchedAt` string, date-time, required
  - `requestId` string, required

## Other responses

- `400`: The request body or parameters are invalid; no credit is consumed
- `401`: The bearer credential is missing, invalid, expired, or revoked; no credit is consumed
- `402`: No promotional or paid credits remain; no credit is consumed
- `409`: A concurrent credit reservation could not be completed; no credit is consumed and the request may be retried
- `429`: Request capacity or a rate allowance was exceeded; no credit is consumed. Respect Retry-After when present, otherwise retry with exponential backoff and jitter.
- `500`: Unexpected processing failure; any reserved credit is restored
- `502`: An upstream App Store service failed; any reserved credit is restored
- `503`: ASO Skill or an upstream service is temporarily unavailable; any reserved credit is restored. Retry after the indicated delay when provided.

---

[API](https://skmtc.dev/asoskill/apis/aso-skill-developer-api.md) · [All operations](https://skmtc.dev/asoskill/apis/aso-skill-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asoskill/apis/aso-skill-developer-api/revisions/c9808e5357cf?raw)