# 3007-Ad-App Creatives

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /ad/app-creatives:
    post:
      summary: 3007-Ad-App Creatives
      deprecated: false
      description: >-
        Query ad creatives by app.


        **Credits**: Charged per platform at 200 credits each. If `platform` is
        empty, all 8 platforms are counted (1600 credits total). No credits are
        charged when no data is returned.


        **Date rules**: `start` and `end` must be provided together (format
        `yyyy-MM-dd`). If both are omitted, defaults to today. Providing only
        one of them, or start > end, returns a parameter error.


        **Sort field `order`**: `START_DATE` (default) / `END_DATE` / `DAYS` /
        `EXPOSURE`.


        **Sort direction `sortOrder`**: `ASC` / `DESC` (default DESC).


        **Limit `limit`**: Currently only `TOP_200` is supported.


        **Platform `platform` values**: facebook / instagram / audience_network
        / messenger / threads / AdMob / YouTube / tiktok.
      operationId: 3007_Ad_App_Creatives
      tags:
        - II. List of Interfaces/3. ASA Services
      parameters: []
      requestBody:
        content:
          application/json:
            schema: &ref_0
              $ref: '#/components/schemas/AdAppCreativesParam'
              description: ''
            example:
              region:
                - YE
                - VN
                - UZ
              appId: com.newleaf.app.android.victor
              start: '2026-01-01'
              end: '2026-07-28'
              platform:
                - facebook
                - instagram
                - audience_network
                - messenger
                - AdMob
                - YouTube
                - threads
                - tiktok
              order: EXPOSURE
              sortOrder: DESC
              limit: TOP_200
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiBaseVOAdAppCreativesVO'
              example:
                requestParam:
                  region:
                    - YE
                    - VN
                    - UZ
                  appId: com.newleaf.app.android.victor
                  start: '2026-01-01'
                  end: '2026-07-28'
                  platform:
                    - facebook
                    - instagram
                    - audience_network
                    - messenger
                    - AdMob
                    - YouTube
                    - threads
                    - tiktok
                  order: EXPOSURE
                  sortOrder: DESC
                  limit: TOP_200
                result:
                  appId: com.newleaf.app.android.victor
                  icon: https://image3.foxdata.com/gp-proxy/example-icon
                  title: Example App
                  Ads:
                    - adId: '1234567890'
                      adThumb:
                        adId: '1234567890'
                        collationCount: 3
                        startDate: '2026-03-01'
                        endDate: '2026-07-10'
                        days: 132
                        details:
                          - type: VIDEO
                            size: 1024000
                            height: 1920
                            width: 1080
                            videoUrl: https://example.com/video.mp4
                            imageUrl: https://example.com/preview.jpg
                      regions:
                        - VN
                        - YE
                      exposure: 15800
                      exposureChange: 320
                      sponsor:
                        id: sponsor_001
                        name: Example Advertiser
                        igFollowers: 12000
                        fbFollowers: 8500
                      distribution:
                        - region: VN
                          ageRange: 18-24
                          gender: male
                          exposure: 5200
                      tiktok: null
                creditsCost:
                  requestCredits: 0
                  baseCredits: 1600
                  extraCredits: 0
                  totalCostCredits: 1600
                next: null
          headers: {}
          x-apifox-name: ''
      security:
        - apikey-header-x-openapi-key: []
      x-apifox-folder: II. List of Interfaces/3. ASA Services
      x-apifox-status: released
      x-run-in-apifox: https://app.apifox.com/web/project/4128055/apis/api-493798532-run
components:
  schemas:
    AdAppCreativesParam:
      type: object
      properties:
        region:
          type: array
          description: Country/region codes, e.g. YE, VN, UZ, US
          items:
            type: string
          examples:
            - - YE
              - VN
              - UZ
        appId:
          type: string
          description: App ID (App Store numeric ID or Google Play package name)
          examples:
            - com.newleaf.app.android.victor
        start:
          type: string
          description: >-
            Start date in yyyy-MM-dd. Must be provided together with end.
            Defaults to today if both are omitted.
          examples:
            - '2026-01-01'
        end:
          type: string
          description: End date in yyyy-MM-dd. Must be provided together with start.
          examples:
            - '2026-07-28'
        platform:
          type: array
          description: >-
            Ad platforms. Empty means all 8 platforms. Allowed values: facebook
            / instagram / audience_network / messenger / threads / AdMob /
            YouTube / tiktok
          items:
            type: string
            enum:
              - facebook
              - instagram
              - audience_network
              - messenger
              - threads
              - AdMob
              - YouTube
              - tiktok
          examples:
            - - facebook
              - instagram
              - audience_network
              - messenger
              - AdMob
              - YouTube
              - threads
              - tiktok
        order:
          type: string
          description: 'Sort field. Default: START_DATE'
          default: START_DATE
          enum:
            - START_DATE
            - END_DATE
            - DAYS
            - EXPOSURE
          x-apifox-enum:
            - value: START_DATE
              name: START_DATE
              description: Ad start date
            - value: END_DATE
              name: END_DATE
              description: Ad end date
            - value: DAYS
              name: DAYS
              description: Running days
            - value: EXPOSURE
              name: EXPOSURE
              description: Exposure
          examples:
            - EXPOSURE
        sortOrder:
          type: string
          description: 'Sort direction. Default: DESC'
          default: DESC
          enum:
            - ASC
            - DESC
          x-apifox-enum:
            - value: ASC
              name: ASC
              description: Ascending
            - value: DESC
              name: DESC
              description: Descending
          examples:
            - DESC
        limit:
          type: string
          description: 'Result limit. Default: TOP_200 (currently only TOP_200 is supported)'
          default: TOP_200
          enum:
            - TOP_200
          x-apifox-enum:
            - value: TOP_200
              name: TOP_200
              description: Return top 200
          examples:
            - TOP_200
      required:
        - appId
      x-apifox-orders:
        - region
        - appId
        - start
        - end
        - platform
        - order
        - sortOrder
        - limit
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    OpenApiBaseVOAdAppCreativesVO:
      type: object
      properties:
        requestParam: *ref_0
        result:
          $ref: '#/components/schemas/AdAppCreativesVO'
          description: Your response.
        creditsCost:
          $ref: '#/components/schemas/OpenApiPointCostVO'
          description: >-
            Credits cost info. Charged per platform at 200 credits each; if
            platform is empty, 8 platforms are counted (1600); 0 when no data.
        next:
          $ref: '#/components/schemas/PaginationInfo'
          description: Next page info
      x-apifox-orders:
        - requestParam
        - result
        - creditsCost
        - next
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    PaginationInfo:
      type: object
      properties:
        taskId:
          type: string
          description: Task ID
        pageKey:
          type: string
          description: Page Key
        totalCount:
          type: integer
          description: Total Count
          format: int64
        totalPages:
          type: integer
          description: Total Pages
          format: int64
      x-apifox-orders:
        - taskId
        - pageKey
        - totalCount
        - totalPages
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    OpenApiPointCostVO:
      type: object
      properties:
        requestCredits:
          type: integer
          description: ''
        baseCredits:
          type: integer
          description: ''
        extraCredits:
          type: integer
          description: ''
        totalCostCredits:
          type: integer
          description: ''
      x-apifox-orders:
        - requestCredits
        - baseCredits
        - extraCredits
        - totalCostCredits
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdAppCreativesVO:
      type: object
      properties:
        appId:
          type: string
          description: App ID
        icon:
          type: string
          description: App icon URL
        title:
          type: string
          description: App name
        Ads:
          type: array
          description: Ad creatives list (JSON field name is Ads)
          items:
            $ref: '#/components/schemas/AdAppCreativesVO.AdItem'
      x-apifox-orders:
        - appId
        - icon
        - title
        - Ads
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdAppCreativesVO.AdItem:
      type: object
      properties:
        adId:
          type: string
          description: Ad ID
        adThumb:
          $ref: '#/components/schemas/AdThumbVO'
          description: >-
            Creative thumbnail info (includes
            collationCount/startDate/endDate/days/details)
        regions:
          type: array
          description: Targeting regions
          items:
            type: string
        exposure:
          type: integer
          format: int64
          description: Exposure
        exposureChange:
          type: integer
          format: int64
          description: Exposure change
        sponsor:
          $ref: '#/components/schemas/AdSponsorVO'
          description: Advertiser info
        distribution:
          type: array
          description: Audience distribution
          items:
            $ref: '#/components/schemas/AdAppCreativesVO.Distribution'
        tiktok:
          $ref: '#/components/schemas/AdTiktokDetail'
          description: >-
            TikTok-specific creative fields (returned only for TikTok ads; may
            be null for other channels)
      x-apifox-orders:
        - adId
        - adThumb
        - regions
        - exposure
        - exposureChange
        - sponsor
        - distribution
        - tiktok
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdTiktokDetail:
      type: object
      properties:
        adTitle:
          type: string
          description: Ad title
        brandName:
          type: string
          description: Brand name
        industryId:
          type: integer
          format: int64
          description: Industry ID
        industry:
          type: string
          description: Industry
        objectives:
          type: array
          description: Campaign objectives
          items:
            type: object
            properties:
              id:
                type: integer
              value:
                type: string
            x-apifox-orders:
              - id
              - value
            x-apifox-ignore-properties: []
        keywords:
          type: array
          description: Keyword insights
          items:
            type: string
        tagIds:
          type: array
          description: Tag IDs
          items:
            type: integer
            format: int64
        tags:
          type: array
          description: Tags
          items:
            type: object
            properties:
              tagId:
                type: integer
                format: int64
              tagName:
                type: string
            x-apifox-orders:
              - tagId
              - tagName
            x-apifox-ignore-properties: []
        performance:
          type: object
          description: Ad performance metrics
          properties:
            like:
              type: integer
            comment:
              type: integer
            share:
              type: integer
            cost:
              type: integer
            ctr:
              type: number
            ctrPercentile:
              type: number
            conversionRatePercentile:
              type: number
            clickCntPercentile:
              type: number
            convertCntPercentile:
              type: number
            showCntPercentile:
              type: number
          x-apifox-orders:
            - like
            - comment
            - share
            - cost
            - ctr
            - ctrPercentile
            - conversionRatePercentile
            - clickCntPercentile
            - convertCntPercentile
            - showCntPercentile
          x-apifox-ignore-properties: []
        summary:
          type: object
          description: Creative summary
          properties:
            hasSummary:
              type: boolean
            highlightText:
              type: string
          x-apifox-orders:
            - hasSummary
            - highlightText
          x-apifox-ignore-properties: []
        curves:
          type: object
          description: Engagement time curves
          properties:
            retainCtr:
              type: object
              x-apifox-orders: []
              properties: {}
              x-apifox-ignore-properties: []
            retainCvr:
              type: object
              x-apifox-orders: []
              properties: {}
              x-apifox-ignore-properties: []
            clickCnt:
              type: object
              x-apifox-orders: []
              properties: {}
              x-apifox-ignore-properties: []
            convertCnt:
              type: object
              x-apifox-orders: []
              properties: {}
              x-apifox-ignore-properties: []
            playRetainCnt:
              type: object
              x-apifox-orders: []
              properties: {}
              x-apifox-ignore-properties: []
          x-apifox-orders:
            - retainCtr
            - retainCvr
            - clickCnt
            - convertCnt
            - playRetainCnt
          x-apifox-ignore-properties: []
      x-apifox-orders:
        - adTitle
        - brandName
        - industryId
        - industry
        - objectives
        - keywords
        - tagIds
        - tags
        - performance
        - summary
        - curves
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdAppCreativesVO.Distribution:
      type: object
      properties:
        region:
          type: string
          description: Region
        ageRange:
          type: string
          description: Age range
        gender:
          type: string
          description: Gender
        exposure:
          type: integer
          format: int64
          description: Exposure
      x-apifox-orders:
        - region
        - ageRange
        - gender
        - exposure
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdSponsorVO:
      type: object
      properties:
        id:
          type: string
          description: Advertiser ID
        name:
          type: string
          description: Advertiser name
        igFollowers:
          type: integer
          format: int64
          description: Instagram followers
        fbFollowers:
          type: integer
          format: int64
          description: Facebook followers
      x-apifox-orders:
        - id
        - name
        - igFollowers
        - fbFollowers
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    AdThumbVO:
      type: object
      properties:
        adId:
          type: string
          description: Ad ID
        collationCount:
          type: integer
          description: Related ad count
        startDate:
          type: string
          description: Ad start date, yyyy-MM-dd
        endDate:
          type: string
          description: Ad end date, yyyy-MM-dd; null means still active
          nullable: true
        days:
          type: integer
          description: Running days
        details:
          type: array
          description: Creative details (image/video)
          items:
            $ref: '#/components/schemas/CreativesDetail'
      x-apifox-orders:
        - adId
        - collationCount
        - startDate
        - endDate
        - days
        - details
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
    CreativesDetail:
      type: object
      properties:
        type:
          type: string
          description: Creative type
          enum:
            - VIDEO
            - IMAGE
        size:
          type: integer
          format: int64
          description: File size
        height:
          type: integer
          format: int64
          description: Height
        width:
          type: integer
          format: int64
          description: Width
        videoUrl:
          type: string
          description: Video URL
        imageUrl:
          type: string
          description: Image URL
      x-apifox-orders:
        - type
        - size
        - height
        - width
        - videoUrl
        - imageUrl
      x-apifox-ignore-properties: []
      x-apifox-folder: ''
  securitySchemes:
    apikey-header-x-openapi-key:
      type: apiKey
      in: header
      name: x-openapi-key
servers:
  - url: https://api.foxdata.com/apiv1/open-api
    description: Api Server
security:
  - apikey-header-x-openapi-key: []

```