openapi: 3.0.3
info:
  title: Creative Testing API
  description: >-
    API reference for the Creative Testing API, including creatives, prediction
    jobs management, prediction and webhook endpoints.
  version: 1.0.0-beta
servers:
  - url: /
tags:
  - name: Creatives
    description: ' Creatives provides a complete set of API endpoints for handling creative assets across their entire lifecycle.'
  - name: Prediction_jobs
    description: >-
      Prediction Jobs provides a complete set of API endpoints for managing the
      entire lifecycle of prediction tasks.
  - name: Predictions
    description: >-
      The Prediction endpoints provide access to detailed analysis results for
      completed prediction jobs. They allow you to retrieve attention metrics
      and tailored platform recommendations to help optimize creative
      performance across different audiences and channels.
  - name: Webhook
    description: >-
      The Webhook endpoints allow developers to set up automated notifications
      from the Amplified system, delivering real-time updates on prediction job
      status changes directly to a specified callback URL provided by the
      caller.
paths:
  /api/v1/creatives:
    get:
      tags:
        - Creatives
      summary: Get all creatives
      description: >-
        Returns all registered creative assets and their metadata for easy
        tracking and management.
      operationId: getCreatives
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creatives'
    post:
      tags:
        - Creatives
      summary: Create a creative by given a downloadable URL
      description: >-
        Registers a new creative by providing a downloadable URL, enabling quick
        onboarding with optional targeting details for prediction jobs.
      operationId: addCreative
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creatives_body'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreativeDownloadableURL'
        '400':
          description: Invalid input
  /api/v1/creatives/{creativeId}:
    get:
      tags:
        - Creatives
      summary: Find creative by ID
      description: Retrieves metadata for a specific creative using its `creativeId`.
      operationId: getCreativeById
      parameters:
        - name: creativeId
          in: path
          description: The unique identifier (UUID) of the creative you want to retrieve.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655445555
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creative'
        '400':
          description: Invalid ID supplied
        '404':
          description: Creative not found
  /api/v1/creatives/{creativeId}/file:
    delete:
      tags:
        - Creatives
      summary: Delete a creative file
      description: >-
        Removes the file associated with a specific creative, identified by
        creativeId.
      operationId: deleteCreativeFile
      parameters:
        - name: creativeId
          in: path
          description: >-
            The unique identifier (UUID) of the creative whose file should be
            deleted.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655445555
      responses:
        '200':
          description: Indicates the creative file was successfully deleted.
        '400':
          description: Invalid creative ID value.
  /api/v1/creatives/upload-video:
    post:
      tags:
        - Creatives
      summary: Create a creative by uploading a file
      description: >-
        Creates a new creative by uploading a video file directly (mp4 or mov,
        ≤5MB) with optional targeting details for prediction jobs.
      operationId: uploadFile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/creatives_upload_video_body'
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: 'The video file to upload (maximum size: 5 MB).'
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creative'
  /api/v1/prediction-jobs:
    get:
      tags:
        - Prediction_jobs
      summary: Get all prediction jobs
      description: >-
        Retrieves a list of all prediction jobs created in the system, including
        their details, statuses, and associated creatives. This endpoint gives
        developers a full overview of active, completed, and historical
        prediction tasks for better tracking and management.
      operationId: getPredictionJobs
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionJobs'
    post:
      tags:
        - Prediction_jobs
      summary: Create a prediection job
      description: >-
        Creates a new prediction job for a specified creative, allowing you to
        analyze attention performance across selected demographics, platforms,
        and formats.
      operationId: CreatePredictionJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/prediction_jobs_body'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionJobWithCreativeWithoutJobs'
        '400':
          description: Invalid input
  /api/v1/prediction-jobs/{predictionJobId}:
    get:
      tags:
        - Prediction_jobs
      summary: Find prediction job by ID
      description: >-
        Retrieves detailed metadata and status for a specific prediction job
        using its predictionJobId.
      operationId: getPredictionJobById
      parameters:
        - name: predictionJobId
          in: path
          description: >-
            The unique identifier (UUID) of the prediction job you want to
            retrieve.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655446666
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionJobWithCreativeWithoutJobs'
        '400':
          description: Invalid ID supplied
        '404':
          description: Prediction Job not found
    delete:
      tags:
        - Prediction_jobs
      summary: Delete predction job by ID
      description: Deletes a specific prediction job identified by predictionJobId.
      operationId: deletePredictionJob
      parameters:
        - name: predictionJobId
          in: path
          description: >-
            The unique identifier (UUID) of the prediction job you want to
            delete.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655446666
      responses:
        '200':
          description: The prediction job was successfully deleted.
        '400':
          description: Invalid ID supplied
        '404':
          description: Prediction Job not found
  /api/v1/predictions/{predictionJobId}/attentions:
    get:
      tags:
        - Predictions
      summary: Get attention data
      description: >-
        Retrieves second-by-second attention predictions for a specific
        prediction job, detailing how active, passive, and no-attention levels
        shift over time.</br></br><Strong>Attention score:</Strong> overall
        attention score of the creative on the given platform_formats. It
        measures how well an ad holds audience attention over time, while giving
        more emphasis on attention captured early where people are most
        engaged.</br></br><Strong>Benchmark:</Strong> score of the given
        platform_formats for comparison. </br></br><strong>Go
        signal:</strong></br>Fix indicates that your creative performs below the
        benchmark for the specified platform formats.</br></br>Good indicates
        that your creative meets or exceeds performance expectations for the
        specified platform formats.</br></br>Excellent indicates that your
        creative ranks within the top 20% of the specified platform formats.
        </br></br><strong>Attention seconds and decay:</strong></br>Example of a
        visualised attention seconds prediction and attention decay returned via
        the endpoint:![Creative Testing Integration Flow](/img/decay.jpg)
      operationId: getAttentionPredictionById
      parameters:
        - name: predictionJobId
          in: path
          description: >-
            The unique identifier (UUID) of the prediction job you want to
            query.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655445555
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attentions'
        '400':
          description: Invalid creative id or job status
  /api/v1/predictions/{predictionJobId}/recommendations:
    get:
      tags:
        - Predictions
      summary: Get recommendations
      description: >-
        Retrieves media recommendations and creative recommendations for a
        specific prediction job, helping guide media placement and creative
        optimization.These recommendations are based on the predicted attention
        performance of the creative across different configurations. If only one
        viable platform exists, only the recommended_platform is given. If two
        viable platforms exist, both recommended_platform and
        reconsider_platform are given.
      operationId: getRecommendationPredictionById
      parameters:
        - name: predictionJobId
          in: path
          description: >-
            The unique identifier (UUID) of the prediction job you want
            recommendations for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655445555
        - name: brand_size
          in: query
          description: >-
            The size of the brand or advertiser for contextualizing
            recommendations.
          required: true
          style: form
          explode: true
          schema:
            type: string
            enum:
              - category_leader
              - challenger
              - small
        - name: first_brand_moment
          in: query
          description: >-
            The timestamp (in seconds) when the brand first appears in the
            creative.
          required: true
          style: form
          explode: true
          schema:
            type: number
        - name: campaign_objective
          in: query
          description: >-
            The main goal or objective of the campaign. You can choose from
            `upper_funnel` (Awareness and brand building), `mid_funnel`
            (Reinforcement and consideration), or `lower_funnel` (Performance
            and conversion).
          required: true
          style: form
          explode: true
          schema:
            type: string
            enum:
              - upper_funnel
              - mid_funnel
              - lower_funnel
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recommendations'
        '400':
          description: Invalid job id supplied
        '404':
          description: Prodiction job not found or not ready yet
  /webhook_url:
    post:
      tags:
        - Webhook
      summary: Webhook
      operationId: receiveUpdates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_url_body'
        required: true
      responses:
        '200':
          description: Notification received successfully.
        '400':
          description: Invalid input.
components:
  schemas:
    PredictionJob_Response:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655441111
          description: The unique identifier of the prediction job.
        creative_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: >-
            The unique identifier of the associated creative asset this
            prediction job is linked to.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the prediction job was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the prediction job was last updated, reflecting
            its latest status change or modification.
        webhook_url:
          type: string
          format: url
          example: https://www.company.com/webhook_url
          description: >-
            The callback URL provided by the API caller to receive asynchronous
            updates on the prediction job’status.
        status:
          type: string
          description: >-
            The current status of the prediction job, indicating its state in
            the processing pipeline.
          example: in-progress
          enum:
            - pending
            - in-progress
            - completed
            - failed
        platform_formats:
          type: array
          description: >-
            A list of platform and format configurations applied to this
            prediction job, detailing which format the creative is evaluated on
            (e.g., platform type, ad format, skippable settings).
          items:
            $ref: '#/components/schemas/creatives_platformFormats'
        genders:
          type: array
          description: The target gender or genders for this prediction job.
          nullable: true
          items:
            type: string
            enum:
              - male
              - female
          example:
            - male
            - female
        countries:
          type: array
          description: >-
            The list of country codes (ISO format) specifying the target
            geographic regions for the prediction job.
          nullable: true
          items:
            type: string
            enum:
              - AU
              - UK
              - US
              - DE
              - SA
              - AE
              - NZ
              - PL
              - CA
              - FR
              - BE
          example:
            - AU
            - US
            - UK
        age_groups:
          type: array
          description: The age group(s) targeted in the prediction job.
          nullable: true
          items:
            type: string
            enum:
              - 18-24
              - 25-34
              - 35-44
              - 45-54
              - 55+
          example:
            - 18-24
            - 25-34
    PredictionJob:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655441111
          description: The unique identifier of the prediction job.
        creative_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: >-
            The unique identifier of the associated creative asset this
            prediction job is linked to.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the prediction job was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the prediction job was last updated, reflecting
            its latest status change or modification.
        webhook_url:
          type: string
          format: url
          example: https://www.company.com/webhook_url
          description: >-
            The callback URL provided by the API caller to receive asynchronous
            updates on the prediction job’status.
        status:
          type: string
          description: >-
            The current status of the prediction job, indicating its state in
            the processing pipeline.
          example: in-progress
          enum:
            - pending
            - in-progress
            - completed
            - failed
        platform_formats:
          type: array
          nullable: true
          description: >-
            A list of platform and format configurations applied to this
            prediction job, detailing which format the creative is evaluated on
            (e.g., platform type, ad format, skippable settings).
          items:
            $ref: '#/components/schemas/creatives_platformFormats'
        genders:
          type: array
          description: >-
            Specifies the target genders for which the creative should be
            evaluated on(optional). If no argument is given, the data across all
            available genders will be returned. If multiple genders are
            provided, data will be aggregated across all selected genders.
          nullable: true
          items:
            type: string
            enum:
              - male
              - female
          example:
            - male
            - female
        countries:
          type: array
          description: >-
            A list of country codes specifying the geographic regions targeted
            for evaluation(optional). If no argument is given, the data across
            all available countries will be returned. If multiple country codes
            are provided, data will be aggregated across all selected regions.
          nullable: true
          items:
            type: string
            enum:
              - AU
              - UK
              - US
              - DE
              - SA
              - AE
              - NZ
              - PL
              - CA
              - FR
              - BE
          example:
            - AU
            - US
            - UK
        age_groups:
          type: array
          description: >-
            Defines the age groups the creative should be assessed
            against(optional).If no argument is given, the data across all
            available countries will be returned. If multiple age_groups s are
            provided, data will be aggregated across all selected age_groups.
          nullable: true
          items:
            type: string
            enum:
              - 18-24
              - 25-34
              - 35-44
              - 45-54
              - 55+
          example:
            - 18-24
            - 25-34
    PredictionJobWithCreativeWithoutJobs:
      allOf:
        - $ref: '#/components/schemas/PredictionJob'
        - type: object
          properties:
            creative:
              $ref: '#/components/schemas/CreativeWithoutJobs'
    PredictionJobs:
      type: array
      items:
        $ref: '#/components/schemas/PredictionJobWithCreativeWithoutJobs'
    Attention:
      type: object
      properties:
        platform:
          type: string
          example: youtube
          description: The platform where The attention performance is evaluated.
        format:
          type: string
          example: pre-roll
          description: The format where The attention performance is evaluated.
        skippable:
          type: boolean
          example: true
          description: >-
            This attribute only compatible with youtube pre-roll
            format(true/false) and must remain null for all other formats.
        attention_score:
          type: number
          format: float
          example: 68
          description: ' Overall attention score of the creative on the given platform_formats.It measures how well an ad holds audience attention over time, while giving more emphasis on attention captured early where people are most engaged.'
        attention_score_benchmark:
          type: number
          format: float
          example: 60
          description: Benchmark score of the given platform_formats for comparison.
        go_signal:
          type: string
          enum:
            - fix
            - good
            - excellent
          description: >-
            Fix indicates that your creative performs below the benchmark for
            the specified platform formats. <br /><br />Good indicates that your
            creative meets or exceeds performance expectations for the specified
            platform formats.<br /><br />Excellent indicates that your creative
            ranks within the top 20% of the specified platform formats.
        attention_seconds:
          $ref: '#/components/schemas/Attention_attention_seconds'
        attention_decay:
          type: array
          description: >-
            Second-by-second attention proportion data indicating how much of
            the audience is active, passive, or not paying attention at each
            second.
          items:
            $ref: '#/components/schemas/Attention_attentions'
    Attentions:
      type: object
      properties:
        predicted_at:
          type: string
          format: date-time
          description: The timestamp when the prediction results were generated.
        creative:
          description: Metadata for the associated creative.
          $ref: '#/components/schemas/CreativeWithOneJob'
        attentions:
          type: array
          items:
            $ref: '#/components/schemas/Attention'
    Element:
      type: object
      properties:
        label:
          type: string
          example: Food
        element_attention_score:
          type: number
          example: 0.4
    Elements:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655443333
        predicted_at:
          type: string
          format: date-time
        creative:
          $ref: '#/components/schemas/CreativeWithOneJob'
        elements:
          type: array
          items:
            $ref: '#/components/schemas/Element'
    Recommendations:
      type: object
      properties:
        predicted_at:
          type: string
          format: date-time
          description: The timestamp when the recommendations were generated.
        creative:
          $ref: '#/components/schemas/CreativeWithOneJob'
          description: ''
        recommended_platform:
          $ref: '#/components/schemas/Recommendations_recommended_platform'
          description: ''
        supplementary_platform:
          $ref: '#/components/schemas/Recommendations_supplementary_platform'
          description: ''
        reconsider_platform:
          $ref: '#/components/schemas/Recommendations_reconsider_platform'
          description: ''
        creative_recommendations:
          $ref: '#/components/schemas/Recommendations_Creative'
          description: ''
    Creative:
      allOf:
        - $ref: '#/components/schemas/CreativeWithoutJobs'
        - type: object
          properties:
            prediction_jobs:
              type: array
              items:
                $ref: '#/components/schemas/PredictionJob'
    CreativeDownloadableURL:
      allOf:
        - $ref: '#/components/schemas/CreativeWithoutJobs'
        - type: object
          properties:
            prediction_jobs:
              type: array
              items:
                $ref: '#/components/schemas/PredictionJob'
            downloadable_url:
              type: string
              example: https://www.amplified.co/creatives/my_creative_video.mp4
              description: >-
                A public URL where the creative file can be accessed and
                downloaded if applicable.
    Creative_Response:
      allOf:
        - $ref: '#/components/schemas/CreativeWithoutJobs'
        - type: object
          properties:
            prediction_jobs:
              type: array
              items:
                $ref: '#/components/schemas/PredictionJob_Response'
    CreativeWithOneJob:
      allOf:
        - $ref: '#/components/schemas/CreativeWithoutJobs'
        - type: object
          properties:
            prediction_job:
              $ref: '#/components/schemas/PredictionJob'
    CreativeWithoutJobs:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: The unique identifier assigned to the creative asset.
        file_name:
          type: string
          example: my_creative_video.mp4
          description: >-
            The name of the uploaded or registered creative file, typically
            including its file extension (e.g., .mp4).
        downloadable_url:
          type: string
          nullable: true
          example: https://www.amplified.co/creatives/my_creative_video.mp4
          description: >-
            A public URL where the creative file can be accessed and downloaded
            if applicable.
        file_source:
          type: string
          example: external_downloadable_link
          description: >-
            The source of the creative file, indicating how it was provided —
            either as an external downloadable link, a direct upload, or stored
            in Amplified’s internal bucket.
          enum:
            - external_downloadable_link
            - direct_upload
            - amplified_bucket
        file_size:
          type: number
          format: integer
          example: 10000
          description: The size of the creative file in bytes.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp indicating when the creative asset was first created
            in the system.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp indicating the last time the creative asset’s record
            was updated.
        status:
          type: string
          description: >-
            The current processing status of the creative. ready_to_use means
            the creative asset has been pre_processed and ready for job
            creation.
          enum:
            - uploaded
            - pending
            - downloading
            - downloaded
            - pre_processing
            - ready_to_use
            - failed_to_download
            - invalid
            - file_deleted
    Creatives_Response:
      type: array
      items:
        $ref: '#/components/schemas/Creative_Response'
    Creatives:
      type: array
      items:
        $ref: '#/components/schemas/Creative'
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string
      xml:
        name: '##default'
    creatives_platformFormats:
      type: object
      properties:
        platform:
          type: string
          example: youtube
          oneOf:
            - const: general_web
              description: >-
                This platform is compatible with outstream_video and pre-roll
                formats.
            - const: instagram
              description: This platform is compatible with feed and stories formats.
            - const: pinterest
              description: >-
                This platform is compatible with max_width_video and
                standard_video formats.
            - const: snapchat
              description: This platform is compatible with commercial formats.
            - const: tiktok
              description: This platform is compatible with in-feed format.
            - const: youtube
              description: This platform is compatible with pre-roll format.
        format:
          type: string
          example: pre-roll
          enum:
            - feed
            - in-stream
            - stories
            - outstream_video
            - pre-roll
            - max_width_video
            - standard_video
            - commercial
            - in-feed
        skippable:
          type: array
          items:
            type: boolean
            nullable: true
            example: false
          description: >-
            This attribute only compatible with youtube pre-roll
            format(true/false) and must remain null for all other formats.
    creatives_body:
      type: object
      properties:
        downloadable_url:
          type: string
          description: >-
            A public URL where the creative file can be accessed and downloaded.
            This link must be reachable over the internet to allow the system to
            fetch and process the creative asset. The ad length must follow the
            guidence: . The file format must be .mp4 or .mov.The file FPS should
            not exceed 60 and file size must <=3GB. 
          nullable: false
          example: https://www.amplified.co/creatives/my_creative_video.mp4
        webhook_url:
          type: string
          description: >-
            The callback URL provided by the API caller to receive asynchronous
            updates on the prediction job’status, such as completion or errors.
          nullable: false
          example: https://www.company.com/webhook_url
        platform_formats:
          type: array
          description: >-
            A list of platform and format configurations applied to this
            prediction job, detailing which media the creative is evaluated on
            (platform, format, skippable settings).<br />If no argument is
            given, all viable platform formats will be assessed according to the
            creative aspect ratio. [Aspect ratio for each format
            reference](/docs/intro#5-aspect-ratio--viable-formats) 
          nullable: true
          items:
            $ref: '#/components/schemas/creatives_platformFormats'
        genders:
          type: array
          description: >-
            Specifies the target genders for which the creative should be
            evaluated on(optional). If no argument is given, the data across all
            available genders will be returned. If multiple genders are
            provided, data will be aggregated across all selected genders.
          nullable: true
          items:
            type: string
            enum:
              - male
              - female
          example:
            - male
            - female
        countries:
          type: array
          nullable: true
          description: >-
            A list of country codes specifying the geographic regions targeted
            for evaluation(optional). If no argument is given, the data across
            all available countries will be returned. If multiple country codes
            are provided, data will be aggregated across all selected regions.
          items:
            type: string
            enum:
              - AU
              - UK
              - US
              - DE
              - SA
              - AE
              - NZ
              - PL
              - CA
              - FR
              - BE
          example:
            - AU
            - US
            - UK
        age_groups:
          type: array
          description: >-
            Defines the age groups the creative should be assessed
            against(optional).If no argument is given, the data across all
            available countries will be returned. If multiple age_groups s are
            provided, data will be aggregated across all selected age_groups.
          nullable: true
          items:
            type: string
            enum:
              - 18-24
              - 25-34
              - 35-44
              - 45-54
              - 55+
          example:
            - 18-24
            - 25-34
    creatives_upload_video_body:
      type: object
      properties:
        webhook_url:
          type: string
          description: >-
            The callback URL provided by the API caller to receive asynchronous
            updates on the prediction job’status, such as completion or errors.
          nullable: false
          example: https://www.company.com/webhook_url
        platform_formats:
          type: array
          description: >-
            A list of platform and format configurations applied to this
            prediction job, detailing which media the creative is evaluated on
            (e.g., platform type, ad format, skippable settings).<br />If no
            argument is given, all viable platform formats will be assessed
            according to the creative aspect ratio.[Aspect ratio for each format
            reference](/docs/intro#5-aspect-ratio--viable-formats)
          nullable: true
          items:
            $ref: '#/components/schemas/creatives_platformFormats'
        genders:
          type: array
          description: >-
            Specifies the target genders for which the creative should be
            evaluated on(optional). If no argument is given, the data across all
            available genders will be returned. If multiple genders are
            provided, data will be aggregated across all selected genders.
          nullable: true
          items:
            type: string
            enum:
              - male
              - female
          example:
            - male
            - female
        countries:
          type: array
          description: >-
            A list of country codes specifying the geographic regions targeted
            for evaluation(optional). If no argument is given, the data across
            all available countries will be returned. If multiple country codes
            are provided, data will be aggregated across all selected regions.
          nullable: true
          items:
            type: string
            enum:
              - AU
              - UK
              - US
              - DE
              - SA
              - AE
              - NZ
              - PL
              - CA
              - FR
              - BE
          example:
            - AU
            - US
            - UK
        age_groups:
          type: array
          description: >-
            Defines the age groups the creative should be assessed
            against(optional).If no argument is given, the data across all
            available countries will be returned. If multiple age_groups s are
            provided, data will be aggregated across all selected age_groups.
          nullable: true
          items:
            type: string
            enum:
              - 18-24
              - 25-34
              - 35-44
              - 45-54
              - 55+
          example:
            - 18-24
            - 25-34
    prediction_jobs_body:
      type: object
      properties:
        creative_id:
          type: string
          description: >-
            The unique identifier of the creative you want to run a prediction
            on.
          example: 550e8400-e29b-41d4-a716-446655445555
        webhook_url:
          type: string
          description: >-
            The callback URL provided by the API caller to receive asynchronous
            updates on the prediction job’status.
          nullable: false
          example: https://www.company.com/webhook_url
        platform_formats:
          type: array
          description: >-
            A list of platform and format configurations applied to this
            prediction job, detailing which media the creative is evaluated on
            (e.g., platform type, ad format, skippable settings).<br />If no
            argument is given, all viable platform formats will be assessed
            according to the creative aspect ratio. [Aspect ratio for each
            format reference](/docs/intro#5-aspect-ratio--viable-formats)
          nullable: true
          items:
            $ref: '#/components/schemas/creatives_platformFormats'
        genders:
          type: array
          description: >-
            Specifies the target genders for which the creative should be
            evaluated on(optional). If no argument is given, the data across all
            available genders will be returned. If multiple genders are
            provided, data will be aggregated across all selected genders.
          nullable: true
          items:
            type: string
            enum:
              - male
              - female
          example:
            - male
            - female
        countries:
          type: array
          description: >-
            A list of country codes specifying the geographic regions targeted
            for evaluation(optional). If no argument is given, the data across
            all available countries will be returned. If multiple country codes
            are provided, data will be aggregated across all selected regions.
          nullable: true
          items:
            type: string
            enum:
              - AU
              - UK
              - US
              - DE
              - SA
              - AE
              - NZ
              - PL
              - CA
              - FR
              - BE
          example:
            - AU
            - US
            - UK
        age_groups:
          type: array
          description: >-
            Defines the age groups the creative should be assessed
            against(optional).If no argument is given, the data across all
            available countries will be returned. If multiple age_groups s are
            provided, data will be aggregated across all selected age_groups.
          nullable: true
          items:
            type: string
            enum:
              - 18-24
              - 25-34
              - 35-44
              - 45-54
              - 55+
          example:
            - 18-24
            - 25-34
    webhook_url_body:
      type: object
      properties:
        prediction_job_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655446666
          description: >-
            The unique ID of the prediction job that triggered the webhook
            update.
        creative_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655445555
          description: The unique ID of the creative associated with the prediction job.
        webhook_url:
          type: string
          description: >-
            The callback URL (provided by the API caller) where the update
            notification is sent.
        timestamp:
          type: string
          description: The exact time when the event or status update occurred.
          format: date-time
        event:
          type: string
          description: The type of event triggering the webhook
          example: prediction_job_status_update
        status:
          type: string
          description: The status of the prediction job
          example: prediction_result_ready
        message:
          type: string
          description: Messages about the update
        error:
          type: string
          description: Error message when something goes wrong
    Attention_attention_seconds:
      type: object
      properties:
        active:
          type: number
          example: 5
          description: >-
            Predicted active attention seconds of the creative on the given
            platform_formats. Active means the audience eye gaze would be on the
            ads.
        passive:
          type: number
          example: 3
          description: >-
            Predicted passive attention seconds of the creative on the given
            platform_formats. Passive means the audience eye gaze would be on
            the screen but not on the ads.
        none:
          type: number
          example: 2
          description: >-
            Predicted non attention seconds of the creative on the given
            platform_formats. Non means the audience eye gaze is not on the
            screen.
    Attention_attention_proportion_item:
      type: object
      properties:
        active:
          type: number
          description: >-
            how much of the audience is actively paying attention at each
            second.
        passive:
          type: number
          description: >-
            how much of the audience is passively paying attention at each
            second.
        none:
          type: number
          description: how much of the audience is not paying attention at each second.
    Attention_attentions:
      type: object
      properties:
        second_sequence:
          type: integer
          example: 1
          description: >-
            Indicates the time point (in seconds) of the creative where the
            attention measurement applies. For example, 1 refers to the start
            (first second), 2 refers to the next second, and so on — allowing
            second-by-second tracking of attention changes throughout the
            creative.
        attention_proportion:
          $ref: '#/components/schemas/Attention_attention_proportion_item'
      example:
        - second_sequence: 1
          attention_proportion:
            active: 60
            passive: 30
            none: 10
        - second_sequence: 2
          attention_proportion:
            active: 55
            passive: 30
            none: 15
        - second_sequence: 3
          attention_proportion:
            active: 57
            passive: 32
            none: 11
        - second_sequence: 4
          attention_proportion:
            active: 42
            passive: 44
            none: 14
        - second_sequence: 5
          attention_proportion:
            active: 37
            passive: 45
            none: 18
        - second_sequence: 6
          attention_proportion:
            active: 25
            passive: 66
            none: 19
    Recommendations_recommended_platform:
      type: object
      description: >-
        Best-fit platform, format skippabilty and explanations based on
        prediction.
      properties:
        platform:
          type: string
          example: youtube
        format:
          type: string
          example: pre-roll
        skippable:
          type: boolean
          example: true
        description:
          type: string
          example: >-
            With 5 seconds of Active Attention, youtube pre-roll skippable
            delivers the strongest potential for a category leader to drive
            brand-building goals. More than 5/10 of the ad is actively viewed,
            ensuring the message is absorbed before users scroll, skip, or
            disengage.
    Recommendations_supplementary_platform:
      type: object
      description: Secondary platform where the creative is also expected to perform well.
      properties:
        platform:
          type: string
          example: facebook
        format:
          type: string
          example: feed
        skippable:
          type: boolean
        description:
          type: string
          example: >-
            A strong companion to enhance reach and engagement is facebook feed.
            This format, with 3 seconds of Active Attention and 2 seconds of
            Passive Attention, serves as a dependable secondary option.
    Recommendations_reconsider_platform:
      type: object
      description: Channels where the creative is unlikely to perform.
      properties:
        platform:
          type: string
          example: pinterest
        format:
          type: string
          example: standard_video
        skippable:
          type: boolean
        description:
          type: string
          example: >-
            With just 1 seconds of Active Attention, this format falls short for
            mid-funnel campaigns, making it unsuitable regardless of brand
            scale. Better alternatives exist for driving engagement mid-funnel.
    Recommendations_Creative:
      type: object
      properties:
        branding:
          type: string
          example: >-
            Ineffective: Branding appearing after 4 sec significantly reduces
            impact in awareness campaigns. By this time, only 46% of viewers
            will still be engaged—urgent changes needed to maintain visibility.
        ad_length_and_format:
          type: string
          example: >-
            Strong: Youtube Pre-roll formats support ad lengths beyond 20
            seconds, which is good for storytelling and sustained engagement,
            making them ideal for upper-funnel brand-building campaigns for
            leader brands. Reinforce branding earlier for better retention.
