Skai (Kenshoo) Meta Ad Groups API

openapi: 3.2.0
info:
  title: Skai Meta Ad Groups API
  description: '# Overview

    Skai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.'
  version: 1.0.0
  x-logo:
    url: https://grid.kenshoo.com/resources-frontend/latest/kenshoo_logo/skai-logo-devportal.svg
    backgroundColor: '#FFFFFF'
    altText: Skai
servers:
- url: https://services.kenshoo.com
security:
- BearerAuth: []
tags:
- name: Meta Ad Groups
  description: 'Manage dimension tags on Meta ad groups.


    > **Scope:** This section covers applying and removing Skai dimension labels on Meta ad groups.


    Publishers:

    Meta'
paths:
  /api/v2/ad_groups:
    get:
      tags:
      - Meta Ad Groups
      summary: Get Ad Groups
      description: 'Get ad groups API call allows you to retrieve ad group information.

        The result is a list of ad group objects that can be paged through using the returned next_page/previous_page values.'
      parameters:
      - $ref: '#/components/parameters/ksV2'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/adGroupIds'
      - $ref: '#/components/parameters/limit'
      responses:
        200:
          $ref: '#/components/responses/getFacebookAdGroupEntitySuccessResponse'
        400:
          $ref: '#/components/responses/getAdGroupBadRequest'
      operationId: getApiV2AdGroups
      x-operation-id-source: derived
    put:
      tags:
      - Meta Ad Groups
      summary: Edit an existing ad group
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/EditFacebookAdgroup'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: putApiV2AdGroups
      x-operation-id-source: derived
    post:
      tags:
      - Meta Ad Groups
      summary: Create a new ad group
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/CreateFacebookAdgroup'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
      operationId: postApiV2AdGroups
      x-operation-id-source: derived
  /api/v1/ad_groups/tags:
    get:
      tags:
      - Meta Ad Groups
      summary: Get Ad Groups tags
      description: 'Get ad group tags API call allows you to retrieve a tags assigned to ad group.

        The result is a list of ad group tags assignment objects that can be paged through using the returned next_page/previous_page values.'
      operationId: getAdGroupTags
      parameters:
      - $ref: '#/components/parameters/ksV2'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/adGroupIds'
      - $ref: '#/components/parameters/limit'
      responses:
        200:
          $ref: '#/components/responses/getEntityTagsSuccessResponse'
        400:
          $ref: '#/components/responses/getEntityTagsBadRequest'
    put:
      tags:
      - Meta Ad Groups
      summary: Edit Ad Group tags
      operationId: updateAdGroupTags
      parameters:
      - $ref: '#/components/parameters/ksV2'
      requestBody:
        $ref: '#/components/requestBodies/editEntityTagsRequest'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    facebookAdgroupBudget:
      type: object
      properties:
        budget:
          type: number
          description: Ad group budget in the profile's currency
        type:
          type: string
          description: Budget type
          enum:
          - DAILY
          - LIFETIME
        pacing_types:
          type: array
          description: Budget pacing types
          items:
            type: string
            enum:
            - STANDARD
            - NO_PACING
            - DAY_PARTING
            - DISABLED
        spend_limit:
          $ref: '#/components/schemas/facebookSpendLimit'
        caps:
          oneOf:
          - $ref: '#/components/schemas/facebookImpressionCaps'
      description: Adgroup budget
    AdGroupDTO:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the ad group
        channel_ad_group_id:
          type: string
          description: Publisher ID of the ad group
        name:
          type: string
          description: Ad group name
        campaign_id:
          type: integer
          description: Skai ID of the campaign
        channel_campaign_id:
          type: string
          description: Publisher ID of the campaign
        profile_id:
          type: integer
          description: Skai ID of the profile
        channel_type:
          type: string
          description: Ad group channel type
          enum:
          - Google
          - Microsoft
          - Universal
          - Yandex
          - Baidu
          - YahooJapan
          - YahooGemini
          - Pinterest
          - Amazon
          - Facebook
          - Walmart
        search_bid:
          type: integer
          description: Default search bid in the profile's currency
        bidding_method:
          $ref: '#/components/schemas/AdgroupBiddingMethod'
        start_date:
          type: string
          description: Ad group start date
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Ad group end date
          format: yyyy-MM-dd
        status:
          $ref: '#/components/schemas/AdgroupStatus'
        budget:
          type: integer
          description: Ad group budget in the profile's currency
        budget_type:
          $ref: '#/components/schemas/AdgroupBudgetType'
    EditFacebookAdgroup:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the ad group
        name:
          type: string
          description: Ad group name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBid'
        targeting:
          oneOf:
          - $ref: '#/components/schemas/facebookTargeting'
        schedule:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupSchedule'
        ad_group_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupType'
      description: The properties for the edited ad group
      example:
      - id: 100
        name: new name
        status: ACTIVE
    tag:
      type: object
      properties:
        name:
          type: string
          description: Tag name
        category:
          type: string
          description: Category name
    ErrorField:
      type: object
      properties:
        fieldName:
          type: string
          description: The error field
        error:
          type: string
          description: Error message
        parameters:
          type: object
          additionalProperties:
            type: string
          description: Error additional properties
    facebookAdgroupSchedule:
      type: object
      properties:
        start_time:
          type: string
          description: Adgroup start time
        end_time:
          type: string
          description: Adgroup end time
        specific_time:
          $ref: '#/components/schemas/facebookAdgroupScheduling'
      description: Adgroup schedule
    facebookImpressionCaps:
      type: object
      properties:
        daily_impression_cap:
          type: integer
          description: Daily impression cap
        lifetime_impression_cap:
          type: integer
          description: Lifetime impression cap
      description: Impression caps
    AdgroupBiddingMethod:
      type: string
      description: Will inherit from the campaign's bidding method, if not included
      enum:
      - ManualCPC
      - ManualCPM
      - ENHANCED_CPC
      - TARGET_CPA
      - TARGET_SPEND
      - TARGET_ROAS
    facebookTargeting:
      type: object
      properties:
        targeting_id:
          type: integer
          description: Targeting ID
      description: Targeting
    facebookAdgroupType:
      type: object
      properties:
        promoted_object:
          $ref: '#/components/schemas/facebookPromotedObject'
        frequency_spec:
          $ref: '#/components/schemas/facebookFrequencySpec'
        attribution_spec:
          type: array
          description: Attribution spec
          items:
            $ref: '#/components/schemas/facebookAttributionSpec'
        conversion_location:
          type: string
          description: Conversion location
          enum:
          - WEBSITE
          - APP
          - MESSENGER
          - APPLINKS_AUTOMATIC
          - WHATSAPP
          - SHOP_AUTOMATIC
          - UNDEFINED
          - INSTAGRAM_DIRECT
          - PHONE_CALL
          - MESSAGING_INSTAGRAM_DIRECT_MESSENGER
          - ON_AD
          - ON_POST
          - ON_VIDEO
          - ON_EVENT
          - ON_PAGE
      description: Adgroup type
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    FacebookAdGroupDTO:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the ad group
        channel_id:
          type: string
          description: Publisher ID of the ad group
        campaign_id:
          type: integer
          description: Skai ID of the campaign
        name:
          type: string
          description: Ad group name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBid'
        targeting:
          oneOf:
          - $ref: '#/components/schemas/facebookTargeting'
        schedule:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupSchedule'
        ad_group_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupType'
    AdgroupBudgetType:
      type: string
      enum:
      - DAILY
      - LIFETIME
    AdgroupStatus:
      type: string
      description: Status
      enum:
      - ACTIVE
      - PAUSED
      - DELETED
      - REVIEW
    facebookFrequencySpec:
      type: object
      properties:
        interval_days:
          type: integer
          description: Interval days
        max_frequency:
          type: integer
          description: Max frequency
        event:
          type: string
          description: Event
          enum:
          - IMPRESSIONS
          - VIDEO_VIEWS_2S
      description: Frequency spec
    facebookAdgroupBid:
      type: object
      properties:
        strategy:
          type: string
          description: Adgroup bid strategy
          enum:
          - UNDEFINED
          - LOWEST_COST_WITHOUT_CAP
          - LOWEST_COST_WITH_BID_CAP
          - TARGET_COST
          - COST_CAP
          - LOWEST_COST_WITH_MIN_ROAS
        billing_event:
          type: string
          description: Adgroup billing event
          enum:
          - IMPRESSIONS
          - LINK_CLICKS
          - APP_INSTALLS
          - PAGE_LIKES
          - OFFER_CLAIMS
          - POST_ENGAGEMENT
          - VIDEO_VIEWS
          - TWO_SECOND_CONTINUOUS_VIDEO_VIEWS
          - THRUPLAY
        optimization_goal:
          type: string
          description: Adgroup optimization goal
          enum:
          - NONE
          - APP_INSTALLS
          - CLICKS
          - ENGAGED_USERS
          - EXTERNAL
          - EVENT_RESPONSES
          - IMPRESSIONS
          - LINK_CLICKS
          - OFFER_CLAIMS
          - OFFSITE_CONVERSIONS
          - PAGE_ENGAGEMENT
          - PAGE_LIKES
          - POST_ENGAGEMENT
          - REACH
          - SOCIAL_IMPRESSIONS
          - VIDEO_VIEWS
          - LEAD_GENERATION
          - APP_EVENTS
          - CONVERSION_EVENTS
          - BRAND_AWARENESS
          - STORE_VISITS
          - VALUE
          - LANDING_PAGE_VIEWS
          - AD_RECALL_LIFT
          - TWO_SECOND_CONTINUOUS_VIDEO_VIEWS
          - OFFLINE_CONVERSIONS
          - THRUPLAY
          - DERIVED_EVENTS
          - CONVERSATIONS
          - STORE_SALES
          - INCREMENTAL_OFFSITE_CONVERSIONS
          - ONSITE_CONVERSIONS
          - APP_INSTALLS_AND_OFFSITE_CONVERSIONS
        bid_amount:
          type: number
          description: Adgroup bid amount
        roas_average_floor:
          type: integer
          description: Adgroup ROAS average floor
      description: Adgroup bid
    facebookAdgroupScheduling:
      type: object
      properties:
        days:
          type: array
          description: Scheduling days
          items:
            type: integer
        start_minute:
          type: integer
          description: Scheduling start minute
        end_minute:
          type: integer
          description: Scheduling end minute
      description: Adgroup scheduling
    facebookPromotedObject:
      type: object
      properties:
        page_id:
          type: integer
          description: Page ID
        product_catalog_id:
          type: integer
          description: Product catalog ID
      description: Promoted object
    editEntityTagsRequest:
      required:
      - id
      - operation_type
      - tags
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the entity
        tags:
          type: array
          description: Tags
          items:
            $ref: '#/components/schemas/tag'
        operation_type:
          $ref: '#/components/schemas/operationType'
      description: The properties for editing entity tags
      example:
      - id: 100
        tags:
        - name: tag1
          category: cat
        - name: tag2
          category: dog
        operation_type: ATTACH
    operationType:
      type: string
      description: Operation type
      enum:
      - ATTACH
      - DETACH
    facebookAttributionSpec:
      type: object
      properties:
        window_days:
          type: integer
          description: Window days
        event:
          type: string
          description: Event
          enum:
          - CLICK_THROUGH
          - VIEW_THROUGH
      description: Attribution spec
    CreateFacebookAdgroup:
      required:
      - campaign_id
      - name
      - schedule
      - status
      - targeting
      type: object
      properties:
        campaign_id:
          type: integer
          description: Skai ID of the campaign
        name:
          type: string
          description: Ad group name
        status:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupStatus'
        budget:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBudget'
        bid:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupBid'
        targeting:
          oneOf:
          - $ref: '#/components/schemas/facebookTargeting'
        schedule:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupSchedule'
        ad_group_type:
          oneOf:
          - $ref: '#/components/schemas/facebookAdgroupType'
      description: The properties for the newly created ad group
      example:
      - campaign_id: 232608652
        name: name
        status: PAUSED
        schedule:
          start_time: 2026-01-01 00:00
          end_time: 2026-01-14 23:59
        targeting:
          targeting_id: 123
    getEntityTagsApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/getEntityTagsResponse'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    facebookAdgroupStatus:
      type: string
      description: Status
      enum:
      - ACTIVE
      - PAUSED
      - DELETED
      - ARCHIVED
      - WITH_ISSUES
      - IN_PROCESS
      - CAMPAIGN_PAUSED
    facebookSpendLimit:
      type: object
      properties:
        min:
          type: number
          description: Minimum spend limit
        max:
          type: number
          description: Maximum spend limit
      description: Budget spend limit
    getAdGroupApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/AdGroupDTO'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    getFacebookAdGroupApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/FacebookAdGroupDTO'
        paging:
          $ref: '#/components/schemas/Paging'
        error_message:
          type: string
          readOnly: true
    Paging:
      type: object
      properties:
        previous_page:
          type: string
          readOnly: true
        next_page:
          type: string
          readOnly: true
    getEntityTagsResponse:
      type: object
      properties:
        id:
          type: integer
          description: Skai ID of the entity
        tags:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/tag'
  responses:
    getAdGroupBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getAdGroupApiResponse'
          example:
            status: FAILED
            entities: []
            paging: null
            error_message: The value in page_id is invalid
    getEntityTagsSuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getEntityTagsApiResponse'
          example:
          - id: 100
            tags:
            - name: tag1
              category: cat
            - name: tag2
              category: dog
    BadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: name
                error: ILLEGAL_NAME
    getFacebookAdGroupEntitySuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getFacebookAdGroupApiResponse'
          example:
          - status: SUCCESS
            entities:
            - id: 100
              name: new name
              status: ACTIVE
              targeting:
                targeting_id: 123
              schedule:
                start_time: 2026-01-01 00:00
                end_time: 2026-01-14 23:59
              campaign_id: 1
            paging:
              previous_page: null
              next_page: MQ==
            error_message: null
    EntitySuccessResponse:
      description: The entity operations succeeded
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 1234
              success: true
              errors: []
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
    getEntityTagsBadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getEntityTagsApiResponse'
          example:
            status: FAILED
            entities: []
            paging: null
            error_message: The value in page_id is invalid
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: ServerError
                error: Unexpected error occurred.
                parameters: {}
  parameters:
    adGroupIds:
      name: ids
      in: query
      description: 'Filter by ad group ID.

        Returns ad groups whose IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 500
        type: array
        items:
          type: string
    pageId:
      name: page_id
      in: query
      description: 'Allows you to traverse pages by using the values for "next_page" and "previous_page" included under "paging" in the response.

        To return the first page, do not include page_id in the request.

        '
      required: false
      style: form
      explode: true
      schema:
        type: string
      example: Mg==
    limit:
      name: limit
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: integer
        format: int32
    ksV2:
      name: ks
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: social
  requestBodies:
    EditFacebookAdgroup:
      description: The ad group details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EditFacebookAdgroup'
      required: true
    editEntityTagsRequest:
      description: The entity tags edit request details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/editEntityTagsRequest'
      required: true
    CreateFacebookAdgroup:
      description: The ad group details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateFacebookAdgroup'
      required: true
x-tagGroups:
- name: Reporting
  tags:
  - Available Columns
  - Synchronous Reports
  - Asynchronous Reports
- name: Bulk Operations
  tags:
  - Jobs
  - Bulk Update
- name: AI & MCP
  tags:
  - MCP
- name: Objects
  tags:
  - Profile
  - Campaigns
  - Ad Groups
  - Ads
  - Product Groups
  - Portfolios
  - Meta Campaigns
  - Meta Ad Groups
  - Meta Ads
  - Columns