Skai (Kenshoo)

Skai (Kenshoo) Ad Groups API

Create, update, and retrieve ad groups. > **Scope:** This API covers common ad group attributes — name, bid, status, and targeting basics. > For the full range of ad group settings use [Bulk Update (One File)](#tag/Bulk-Update). Publishers: Search Social (excl. Meta) Retail Media

GitHub OpenAPI
Business capability
Digital Marketing Management BC-400.60

Operations 3

GET /api/v1/ad_groups Get Ad Groups #
PUT /api/v1/ad_groups Edit an existing ad group #
POST /api/v1/ad_groups Create a new ad group #

Documentation

📖
Documentation
https://developers.skai.io/
📖
APIReference
https://developers.kenshoo.com/
📖
GettingStarted
https://developers.skai.io/#section/Authentication
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/authentication/skai-kenshoo-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/rate-limits/skai-kenshoo-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/openapi/skai-kenshoo-ad-groups-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/conventions/skai-kenshoo-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/errors/skai-kenshoo-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/skai-kenshoo/refs/heads/main/data-model/skai-kenshoo-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/skai-kenshoo-ad-groups-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

skai-kenshoo-ad-groups-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Skai 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: Ad Groups
  description: 'Create, update, and retrieve ad groups.


    > **Scope:** This API covers common ad group attributes — name, bid, status, and targeting basics.

    > For the full range of ad group settings use Bulk Update (One File).


    Publishers:

    Search

    Social (excl. Meta)

    Retail Media'
paths:
  /api/v1/ad_groups:
    get:
      tags:
      - Ad Groups
      summary: Get Ad Groups
      description: 'Get ad groups API call allows you to retrieve ad group information. You can filter by multiple fields, such as the profile ID and channel type, or request specific ad groups by their IDs.

        The result is a list of ad group objects that can be paged through using the returned next_page/previous_page values.'
      operationId: getAdGroups
      parameters:
      - $ref: '#/components/parameters/ks'
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/adGroupIds'
      - $ref: '#/components/parameters/channelAdGroupIds'
      - $ref: '#/components/parameters/adGroupCampaignIds'
      - $ref: '#/components/parameters/adGroupChannelCampaignIds'
      - $ref: '#/components/parameters/adGroupProfileId'
      - $ref: '#/components/parameters/adGroupChannelTypes'
      - $ref: '#/components/parameters/adGroupStatuses'
      responses:
        200:
          $ref: '#/components/responses/getAdGroupEntitySuccessResponse'
        400:
          $ref: '#/components/responses/getAdGroupBadRequest'
    put:
      tags:
      - Ad Groups
      summary: Edit an existing ad group
      description: 'Update one or more ad groups. Editable attributes are documented in the request body schema below.


        **Need more attributes?** Use Bulk Update (One File) for the full attribute set.'
      operationId: updateAdGroups
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/EditAdgroup'
      responses:
        200:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
      - Ad Groups
      summary: Create a new ad group
      description: 'Create one or more ad groups. Supported attributes are documented in the request body schema below.


        **Need more attributes?** Use Bulk Update (One File) to create ad groups with the full range of settings.'
      operationId: createAdGroups
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/CreateAdgroup'
      responses:
        201:
          $ref: '#/components/responses/EntitySuccessResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    ks:
      name: ks
      in: query
      description: The KS to refer the request to. You can find this ID in the Skai platform under _Administration_ -> _About Skai_ -> _Server ID_
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: '1234'
    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
    adGroupStatuses:
      name: statuses
      in: query
      description: 'Filter by status.

        Returns the ad groups whose statuses are included in the list.

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
          - Active
          - Approved
          - Paused
          - Deleted
          - Failed
          - Review
          - ToPause
          - ToDelete
          - FailedToPause
          - FailedToDelete
          - Unknown
          - Scheduled
          - Expired
          - Pending
          - Disapproved
    adGroupChannelTypes:
      name: channel_types
      in: query
      description: 'Filter by channel type.

        Returns the ad groups whose channel types are included in the list.

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
          - Google
          - Microsoft
          - Universal
          - Yandex
          - Baidu
          - YahooJapan
          - YahooGemini
          - Pinterest
          - Amazon
          - Facebook
          - Walmart
    adGroupChannelCampaignIds:
      name: channel_campaign_ids
      in: query
      description: 'Filter by channel campaign ID.

        Returns the ad groups whose channel campaign IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 200
        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==
    adGroupCampaignIds:
      name: campaign_ids
      in: query
      description: 'Filter by campaign ID.

        Returns the ad groups whose campaign IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 200
        type: array
        items:
          type: string
    channelAdGroupIds:
      name: channel_ad_group_ids
      in: query
      description: 'Filter by channel ad group ID.

        Returns the ad groups whose channel ad group IDs are included in your list.

        '
      required: false
      style: form
      explode: true
      schema:
        maxItems: 500
        type: array
        items:
          type: string
    adGroupProfileId:
      name: profile_id
      in: query
      description: 'Filter by profile ID.

        Returns the ad groups whose profile ID equals your profile ID.

        '
      required: false
      style: form
      explode: true
      schema:
        type: string
  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
    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
    EntitySuccessResponse:
      description: The entity operations succeeded
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 1234
              success: true
              errors: []
    getAdGroupEntitySuccessResponse:
      description: The operation was completed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getAdGroupApiResponse'
          example:
            status: SUCCESS
            entities:
            - id: 15324
              channel_ad_group_id: '1674257480'
              name: name
              campaign_id: 106
              channel_campaign_id: '60600800'
              profile_id: 12
              channel_type: Google
              search_bid: 1.0
              bidding_method: NOT_SET
              status: ACTIVE
              start_date: '2026-01-01'
              end_date: '9999-12-30'
              budget: 100.0
              budget_type: DAILY
            paging:
              previous_page: null
              next_page: MQ==
            error_message: null
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
    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: {}
  schemas:
    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'
    PinterestAdgroupExtensions:
      type: object
      properties:
        delivery_method:
          type: string
          description: Delivery method
          enum:
          - STANDARD
          - ACCELERATED
        conversion_parameters:
          $ref: '#/components/schemas/AdgroupConversionParams'
        targeting_parameters:
          $ref: '#/components/schemas/PinterestTargetingParams'
      description: For Pinterest Shopping campaigns only
    CreateAdgroup:
      required:
      - campaign_id
      - name
      type: object
      properties:
        name:
          type: string
          description: New ad group name
        campaign_id:
          type: integer
          description: The ID of the campaign this ad group is created in
        search_bid:
          type: integer
          description: Default search bid in the profile's currency
        status:
          $ref: '#/components/schemas/AdgroupStatus'
        start_date:
          type: string
          description: Ad group start date. If not specified, will start immediately. If specified, must be in the future.
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Ad group end date. If specified, must be in the future and later than the campaign start date.
          format: yyyy-MM-dd
        bidding_method:
          $ref: '#/components/schemas/AdgroupBiddingMethod'
        budget:
          type: integer
          description: Budget, in the profile's currency
        budget_type:
          $ref: '#/components/schemas/AdgroupBudgetType'
        pinterest_ad_group_extensions:
          $ref: '#/components/schemas/PinterestAdgroupExtensions'
      description: The properties for the newly created ad group
      example:
      - name: adgroup example
        campaign_id: 1234
        search_bid: 12.2
        status: ACTIVE
        start_date: '2026-01-01'
        end_date: '2026-12-31'
        bidding_method: ManualCPC
        budget: 50.1
        budget_type: LIFETIME
        pinterest_ad_group_extensions:
          delivery_method: STANDARD
          conversion_parameters:
            conversion_tag_id: my tag id
            conversion_event: CHECKOUT
            conversion_attribution_window: WIN_30_30_1
            conversion_avg_cpa: 7.7
          targeting_parameters:
            genders:
            - FEMALE
            - MALE
            - UNSPECIFIED
            ages:
            - AGE_50_54
            - AGE_18_24
            - AGE_25_34
            - AGE_21
            - AGE_45_49
            - AGE_35_44
            - AGE_65
            - AGE_55_64
            devices:
            - ANDROID_MOBILE
            - ANDROID_TABLET
            - IPAD
            - IPHONE
            - WEB
            - WEB_MOBILE
            placements: ALL
            countries:
            - US
    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
    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
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    AdgroupBudgetType:
      type: string
      enum:
      - DAILY
      - LIFETIME
    AdgroupStatus:
      type: string
      description: Status
      enum:
      - ACTIVE
      - PAUSED
      - DELETED
      - REVIEW
    EditAdgroup:
      required:
      - campaign_id
      - id
      type: object
      properties:
        id:
          type: integer
          description: The ad group ID
        name:
          type: string
          description: The new name of the ad group
        campaign_id:
          type: integer
          description: The ID of the campaign of this ad group
        search_bid:
          type: integer
          description: Default search bid in the profile's currency
        status:
          $ref: '#/components/schemas/AdgroupStatus'
        start_date:
          type: string
          description: Ad group start date. If not specified, will start immediately. If specified, must be in the future.
          format: yyyy-MM-dd
        end_date:
          type: string
          description: Ad group end date. If specified, must be in the future and later than the campaign start date.
          format: yyyy-MM-dd
        bidding_method:
          $ref: '#/components/schemas/AdgroupBiddingMethod'
        budget:
          type: integer
          description: Budget, in the profile's currency
        budget_type:
          $ref: '#/components/schemas/AdgroupBudgetType'
      description: The properties for the edited ad group
      example:
      - id: 1111
        name: adgroup example
        campaign_id: 1234
        search_bid: 12.2
        status: ACTIVE
        start_date: '2026-01-01'
        end_date: '2026-12-31'
        bidding_method: ManualCPC
        budget: 50.1
        budget_type: LIFETIME
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    AdgroupConversionParams:
      type: object
      properties:
        conversion_tag_id:
          type: string
          description: The tag ID
        conversion_event:
          type: string
          description: Conversion event
          enum:
          - CHECKOUT
          - SIGNUP
          - LEAD
          - APP_INSTALL
          - ADD_TO_CART
        conversion_attribute_window:
          type: string
          description: Attribution window
          enum:
          - WIN_30_30_1
          - WIN_7_7_1
          - WIN_7_0_0
          - WIN_1_1_1
          - WIN_1_0_0
        conversion_averaget_cpa:
          type: number
          description: Average CPA
      description: Conversion parameters
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    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
    Paging:
      type: object
      properties:
        previous_page:
          type: string
          readOnly: true
        next_page:
          type: string
          readOnly: true
    PinterestTargetingParams:
      type: object
      properties:
        genders:
          type: string
          description: Genders
          enum:
          - FEMALE
          - MALE
          - UNSPECIFIED
        ages:
          type: string
          description: Ages
          enum:
          - AGE_18_24
          - AGE_21
          - AGE_25_34
          - AGE_35_44
          - AGE_45_49
          - AGE_50_54
          - AGE_55_64
          - AGE_65
        devices:
          type: string
          description: Devices
          enum:
          - ANDROID_MOBILE
          - ANDROID_TABLET
          - IPAD
          - IPHONE
          - WEB
          - WEB_MOBILE
        placements:
          type: string
          description: Placements
          enum:
          - ALL
          - SEARCH
          - BROWSE
          - OTHER
        country_names:
          type: array
          description: Countries
          items:
            type: string
      description: Pinterest-specific targeting parameters
  requestBodies:
    CreateAdgroup:
      description: The ad group details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAdgroup'
      required: true
    EditAdgroup:
      description: The ad group details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EditAdgroup'
      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