Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Skai Campaigns API
description: "# Overview\nSkai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.\n\n## Choosing the Right API\n\n| What you want to do | API to use | Scale | Notes |\n|---|---|---|---|\n| Pull performance data, metrics, or any reportable field | [Reporting](#tag/Synchronous-Reports) or [Async Reporting](#tag/Asynchronous-Reports) | Unlimited | Primary data access API — the main Skai value-prop |\n| Discover what columns and metrics are available | [Available Columns](#operation/getAvailableColumns) | — | Full list of reportable fields per entity type |\n| Create or update campaigns, keywords, bids, budgets, targeting, and more — at scale | [Bulk Update (One File)](#tag/Bulk-Update) | Millions of rows | Supports Skai's main entity types and hundreds of attributes; all publishers except Meta |\n| Create/update a small number of campaigns or ad groups (common attributes only) | [Campaigns](#tag/Campaigns) / [Ad Groups](#tag/Ad-Groups) / [Ads](#tag/Ads) | Thousands | Limited attribute set — use Bulk Update for full control |\n| Manage Meta (Facebook/Instagram) entities | [Meta Campaigns](#tag/Meta-Campaigns) / [Meta Ad Groups](#tag/Meta-Ad-Groups) / [Meta Ads](#tag/Meta-Ads) | Thousands | Meta-specific tag and attribution management |\n| Use Skai from an AI coding assistant (Claude, Cursor, ChatGPT, Windsurf) | [MCP Integration](#tag/MCP) | — | Full reporting access via natural language |\n\nSkai APIs are RESTful and language agnostic. Authentication uses Bearer tokens over HTTPS.\n\n## What Data Can I Access?\n\nSkai aggregates advertising data across three publisher categories:\n\n| Publisher category | Examples |\n|---|---|\n| **Search** | Google Ads, Microsoft Ads, Yahoo Japan, Baidu, and others |\n| **Social (excl. Meta)** | Pinterest, Snapchat, TikTok, LinkedIn, Reddit, and others |\n| **Social (Meta)** | Facebook, Instagram |\n| **Retail Media** | Amazon Ads, Walmart, Instacart, Kroger, Target, and 100+ others |\n\n**Reportable entity types:**\n\n| Entity | Description | Publishers |\n|---|---|---|\n| `CAMPAIGN` | Campaign-level data | All |\n| `ADGROUP` | Ad group / ad set level | All |\n| `KEYWORD` | Keyword-level performance and settings | Search, Retail Media |\n| `AD` | Individual ad creatives | All |\n| `PRODUCT_ASSET` | Product-level data for shopping and retail media (called \"Products\" in the Skai UI) | Retail Media, Search Shopping |\n| `PRODUCT_TARGETING` | Product targeting entities — ASINs, categories, and product attributes | Retail Media |\n| `PORTFOLIO` | Portfolio-level budget aggregations and pacing | All |\n\n**Available metric categories per entity:**\n\n- **Performance** — Impressions, Clicks, Cost, Conversions, Revenue, ROAS, CTR, CPC, and more\n- **Attributes** — Names, statuses, budgets, bids, targeting settings, and publisher-specific fields\n- **Account-configured** — Dimensions (custom tagging labels), Conversion events (publisher, pixel, and 3rd-party), Custom Metrics (formula-based calculations your team defines)\n\nUse [Available Columns](#operation/getAvailableColumns) to see the complete column list for any entity — including full descriptions and types. A static reference is embedded in that endpoint's documentation.\n\n\n## Authentication\nThe Skai API uses the Bearer authentication scheme.\nThe first step is to generate a *refresh token* (once), which you can then exchange for a temporary *access token*, programmatically, before making an API call.\n\n> Note: The user you use to generate your *refresh token* will determine the token's permissions. API access is allowed for users with Standard role or higher.\nIt is recommended that you create and use a specialized user for your API requests.\n\n\n#### Step 1: Get a Refresh Token\nYou only need to do this once, for each API user you plan to use. \n\nLog into [this page](https://login.kenshoo.com/api/dev/refresh-token) in order to get your *refresh token* and *client ID*. The user you log in with will be the user accessing the API. \nPlease store your refresh token in a secure place. While it is not possible to recover a refresh token, you can generate a new one. The refresh token does not expire.\n\n\n#### Step 2: Generating an Access Token\nBefore making API calls, your code uses the permanent *refresh token* to generate a temporary *access token*.\n\nMake a call to /api/v1/token (as shown below) with your *refresh token* and *client ID* to generate an *access token*:\n\n curl -X POST -d \"refresh_token=<YourToken>&client_id=<Your Client Id>\" \\\n https://services.kenshoo.com/api/v1/token\n\nNote: the client_id and refresh token should be sent in the POST request body, as the refresh token is confidential and should not be sent as url param.\nthe API will reject refresh tokens sent in url params.\n\nGet token for specific agency context:\nIn case your API user is assigned to multi accounts (agencies), you should explicitly specify in the get access-token request which agency context you would like to receive the token for.\nJust add to the request mentioned above another form param called *agency_id*, and pass the relevant agency ID like this:\n \n curl -X POST -d \"refresh_token=<YourToken>&client_id=<Your Client Id>&agency_id=<Your Agency Id>\" \\\n https://services.kenshoo.com/api/v1/token\n\nToken expiration:\nPlease check for token expiration before sending another API request , you have 2 options:\n\n1. Call the API and get 401 status code indicating authentication failed.\n2. Consider the *expires_in* field of the token to issue a new access token.\n\nThe response will return a JSON containing the token and time for expiration in seconds.\nIt is recommended to use the token expiration time and reuse tokens while they are still valid, to prevent rate limit issues with generating new tokens too often.\n\n {\"email\":\"my.user@skai.io\",\"expires_in\":21600,\"access_token\":\"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaGxvbWkuY29oZW5Ac2thaS5pbyIsImV4cCI6MTcxNDU2NjgxMSwiaXNzIjoiaHR0cDovL2tlbnNob28uY29tL2xvZ2luLXNlcnZlciIsInVzZXJpZCI6MzU5NDMsImFnZW5jeUlkIjoxNSwibmFtZSI6IlNobG9taSBDb2hlbiIsInJvbGVzIjpbIktlbnNob28gQWRtaW4iLCJTa2FpIERldmVsb3BlciJdLCJhZ2VuY3lfcm9sZXMiOlt7ImFnZW5jeUlkIjoxNSwicm9sZSI6IktlbnNob28gQWRtaW4ifV0sImJpbGxpbmdJZCI6OTIwMzEsImFwaWMiOiI5MjAzMSIsIm9yaSI6ImFwaSIsImFsbG93ZWRfYXBwcyI6W119.R3tHoaecUrMGzijnF5suo9SVsffXWbWxdMv5fdB3Jx8\"}\n\n\n\n\n\n#### Step 3: Making an API call\nWith any API call to all Skai APIs, you must send a valid *access token* in the Authorization header when making requests. For example:\n\n curl -H \"Authorization: Bearer <token>\" -X POST \\\n https://services.kenshoo.com/api/v1/campaigns\n\n\n## Rate Limits\nAPI calls are limited per user, to the following:\n - 60 requests per minute\n - 2,000 requests per hour\n\nWhen you meet the limit, you receive the following 429 HTTP error: “API rate limit exceeded”.\nWhen calling any API endpoint the response headers will show the limits relevant to this user, and the number of remaining calls you can make within the current minute/hour.\n\n\n## Reporting Best Practices\n\n- **Filter for non-zero data:** For performance reports, filter to rows where a key metric (e.g., impressions > 0) to reduce report size and speed up generation.\n- **Scope structure reports:** Apply a filter like \"Last updated > X days ago\" to retrieve only recently changed entities.\n- **Use Async for large datasets:** If your report may return more than a few thousand rows, use [Async Analysis Reports](#tag/Asynchronous-Reports) and poll for results rather than the synchronous endpoint.\n\n\n## Group by and Segmentation\n### Understanding Group by and Segmentation\nWhen querying the /api/v1/reports/async/analysis and /reports endpoints, the breakdown_type parameter\ndetermines how data is structured.\n- FLAT: Returns unsegmented data without any grouping.\n- GROUP: Allows data segmentation based on specified columns (e.g., by date).\n- SEGMENT: Enables segmentation by date and an additional column, such as CampaignId.\n\n### How Group by works\nWhen using \"breakdown_type\": \"GROUP\", the group_bys parameter defines how the data is grouped. For instance:\n\"group_bys\": [ { \"name\": \"Day\", \"group\": \"TimeSegment\" } ]\n This groups data only by date, meaning campaign details won’t be included, similar to what is displayed in the grid export.\n\n| Conv. | Cost | Day |\n|-------|------|------------|\n| 2 | 100 | 09/29/2024 |\n| 3 | 200 | 09/28/2024 |\n\n### Using SEGMENT for Additional Grouping\nTo segment data by both date and another column (e.g., CampaignId), use \"breakdown_type\": \"SEGMENT\", specifying only the date column under group_bys while including the additional column in fields. Example:\n\"breakdown_type\": \"SEGMENT\",\n\"group_bys\": [ { \"name\": \"Day\", \"group\": \"TimeSegment\" } ],\n\"fields\": [ { \"name\": \"CampaignId\", \"group\": \"ATTRIBUTES\" } ]\n\nThis ensures data is segmented by day while preserving campaign details.\n\n| Campaign ID | Conv. | Cost | Day |\n|-------------|-------|------|------------|\n| 25000 | 1 | 50 | 09/29/2024 |\n| 25001 | 1 | 50 | 09/29/2024 |\n| 25000 | 2 | 150 | 09/28/2024 |\n| 25001 | 1 | 50 | 09/28/2024 |\n"
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: Campaigns
description: 'Create, update, and retrieve campaigns.
> **Scope:** This API covers common campaign attributes — name, budget, bid, status, dates, and campaign type.
> For the full range of campaign settings (targeting, extensions, dimension labels, and publisher-specific fields)
> use [Bulk Update (One File)](#tag/Bulk-Update), which handles millions of rows across all non-Meta publishers.
<dl>
<span>Publishers:</span>
<span style="color: white; padding: 8px; background-color: #4CAF50;" >Search</span>
<span style="color: white; padding: 8px; background-color: #2196F3;" >Social (excl. Meta)</span>
<span style="color: white; padding: 8px; background-color: #A29A22;" >Retail Media</span>
</dl>
'
paths:
/api/v1/campaigns:
get:
tags:
- Campaigns
summary: Get campaigns
description: 'Get campaigns API call allows you to retrieve campaign information. You can filter by multiple fields, such as the profile ID and channel type, or request specific campaigns by their IDs.
The result is a list of campaign objects that can be paged through using the returned next_page/previous_page values.
'
operationId: getCampaigns
parameters:
- $ref: '#/components/parameters/ks'
- $ref: '#/components/parameters/pageId'
- $ref: '#/components/parameters/campaignIds'
- $ref: '#/components/parameters/channelCampaignIds'
- $ref: '#/components/parameters/profileId'
- $ref: '#/components/parameters/channelTypes'
- $ref: '#/components/parameters/campaignStatuses'
responses:
200:
$ref: '#/components/responses/GetCampaignEntitySuccessResponse'
400:
$ref: '#/components/responses/GetCampaignBadRequest'
put:
tags:
- Campaigns
summary: Edit an existing campaign
description: 'Update one or more campaigns. Editable attributes are documented in the request body schema below.
**Need more attributes?** Use [Bulk Update (One File)](#tag/Bulk-Update) for bulk edits with the full attribute set.'
operationId: updateCampaigns
parameters:
- $ref: '#/components/parameters/ks'
requestBody:
$ref: '#/components/requestBodies/editCampaigns'
responses:
200:
$ref: '#/components/responses/EntitySuccessResponse'
400:
$ref: '#/components/responses/BadRequest'
500:
$ref: '#/components/responses/InternalServerError'
post:
tags:
- Campaigns
summary: Create a new campaign
description: 'Create one or more campaigns. Supported attributes are documented in the request body schema below (name, budget, bid, status, dates, campaign type).
**Need more attributes?** Use [Bulk Update (One File)](#tag/Bulk-Update) to create campaigns with the full range of settings including targeting, extensions, dimension labels, and publisher-specific fields.'
operationId: createCampaigns
parameters:
- $ref: '#/components/parameters/ks'
requestBody:
$ref: '#/components/requestBodies/createCampaigns'
responses:
201:
$ref: '#/components/responses/EntitySuccessResponse'
400:
$ref: '#/components/responses/BadRequest'
500:
$ref: '#/components/responses/InternalServerError'
components:
parameters:
campaignStatuses:
name: statuses
in: query
description: 'Filter by status.
Returns campaigns 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
- Suspended
- PausedBudgetDepleted
channelTypes:
name: channel_types
in: query
description: 'Filter by channel type.
Returns the campaigns 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
channelCampaignIds:
name: channel_campaign_ids
in: query
description: 'Filter by channel campaign ID.
Returns the campaigns whose channel campaign IDs are included in your list.
'
required: false
style: form
explode: true
schema:
maxItems: 500
type: array
items:
type: string
profileId:
name: profile_id
in: query
description: 'Filter by profile ID.
Returns the campaigns whose profile ID equals your profile ID.
'
required: false
style: form
explode: true
schema:
type: string
campaignIds:
name: ids
in: query
description: 'Filter by campaign ID.
Returns the campaigns whose campaign 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==
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'
requestBodies:
editCampaigns:
description: The campaigns to update
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/editCampaign'
required: true
createCampaigns:
description: The campaigns to create
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/createCampaign'
required: true
schemas:
Paging:
type: object
properties:
previous_page:
type: string
readOnly: true
next_page:
type: string
readOnly: true
ApiResponse:
type: object
properties:
status:
$ref: '#/components/schemas/ApiResponseStatus'
entities:
type: array
items:
$ref: '#/components/schemas/EntityResponse'
editCampaign:
required:
- id
type: object
properties:
id:
type: integer
description: Skai ID of the campaign
channel_account_id:
type: integer
description: Skai ID of the publisher account
campaign_name:
type: string
description: Campaign name
budget:
type: number
description: Campaign budget in the profile's currency
budget_type:
type: string
description: Budget type
enum:
- DEFAULT
- DAILY_FOR_ADGROUP
- MONTHLY_FOR_CAMPAIGN
- LIFETIME
search_bid:
type: number
description: Default search bid in the profile's currency
content_bid:
type: number
description: Default content bid in the profile's currency
status:
type: string
description: Campaign status
enum:
- ACTIVE
- PAUSED
- DELETED
- REVIEW
order_line:
type: string
description: Order line of the campaign
start_date:
type: string
description: Campaign start date. If specified, must be in the future.
format: yyyy-MM-dd
end_date:
type: string
description: Campaign end date. If specified, must be in the future and later than the campaign start date.
format: yyyy-MM-dd
tracking_level:
type: string
description: Campaign tracking level
enum:
- NONE
- PROFILE_DEFAULT
- CAMPAIGN
- ADS
- KEYWORDS
- ADS_AND_KEYWORDS
shopping_settings:
$ref: '#/components/schemas/shoppingSettings'
default_geographical_targeting:
type: string
description: Geographical targeting inheritance options
enum:
- INHERIT_FROM_PROFILE
- ENTIRE_WORLD
description: The properties for the updated campaign
example:
channel_account_id: '14411'
campaign_name: Edit Campaign
budget: '153000.0'
search_bid: '1.0'
content_bid: '1.0'
start_date: '2026-01-01'
end_date: '3000-09-28'
campaign_type: SHOPPING_STANDARD
shopping_settings:
merchant_id: '8740'
sales_country: US
priority: LOW
GetCampaignApiResponse:
type: object
properties:
status:
$ref: '#/components/schemas/ApiResponseStatus'
entities:
type: array
readOnly: true
items:
$ref: '#/components/schemas/CampaignDTO'
paging:
$ref: '#/components/schemas/Paging'
error_message:
type: string
readOnly: true
shoppingSettings:
type: object
properties:
merchant_id:
type: number
description: Merchant center account ID
sales_country:
type: string
description: Country of sale for the shopping campaign
priority:
type: string
description: Priority of the shopping campaign
enum:
- LOW
- MEDIUM
- HIGH
- SMART_SHOPPING_CAMPAIGN
description: Campaign shopping settings
createCampaign:
required:
- campaign_name
- channel_account_id
type: object
properties:
channel_account_id:
type: integer
description: Skai ID of the publisher account
campaign_name:
type: string
description: Campaign name
budget:
type: number
description: Campaign budget in the profile's currency
budget_type:
type: string
description: Budget type
enum:
- DEFAULT
- DAILY_FOR_ADGROUP
- MONTHLY_FOR_CAMPAIGN
- LIFETIME
search_bid:
type: number
description: Default search bid in the profile's currency
content_bid:
type: number
description: Default content bid in the profile's currency
status:
type: string
description: Campaign status
enum:
- ACTIVE
- PAUSED
- DELETED
- REVIEW
default: ACTIVE
order_line:
type: string
description: Order line of the campaign
start_date:
type: string
description: Campaign start date. If not specified, will start immediately. If specified, must be in the future.
format: yyyy-MM-dd
end_date:
type: string
description: Campaign end date. If specified, must be in the future and later than the campaign start date.
format: yyyy-MM-dd
tracking_level:
type: string
description: Campaign tracking level
enum:
- NONE
- PROFILE_DEFAULT
- CAMPAIGN
- ADS
- KEYWORDS
- ADS_AND_KEYWORDS
default: PROFILE_DEFAULT
campaign_type:
type: string
description: Campaign type
enum:
- TEXT_CAMPAIGN
- SMART_SHOPPING
- SHOPPING_STANDARD
default: TEXT_CAMPAIGN
shopping_settings:
$ref: '#/components/schemas/shoppingSettings'
default_geographical_targeting:
type: string
description: Geographical targeting inheritance options
enum:
- INHERIT_FROM_PROFILE
- ENTIRE_WORLD
default: INHERIT_FROM_PROFILE
description: The properties for the created campaign
example:
channel_account_id: '14411'
campaign_name: New Campaign
budget: '153000.0'
search_bid: '1.0'
content_bid: '1.0'
start_date: '2026-01-01'
end_date: '3000-09-28'
campaign_type: SHOPPING_STANDARD
shopping_settings:
merchant_id: '8740'
sales_country: US
priority: LOW
ApiResponseStatus:
type: string
readOnly: true
enum:
- SUCCESS
- FAILED
- PARTIAL_SUCCESS
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
CampaignDTO:
type: object
properties:
id:
type: integer
description: Skai ID of the campaign
channel_campaign_id:
type: string
description: Publisher ID of the campaign
channel_account_id:
type: integer
description: Skai ID of the publisher account
profile_id:
type: integer
description: Skai ID of the profile
channel_type:
type: string
description: Campaign channel type
enum:
- Google
- Microsoft
- Universal
- Yandex
- Baidu
- YahooJapan
- YahooGemini
- Pinterest
- Amazon
- Facebook
- Walmart
campaign_name:
type: string
description: Campaign name
budget:
type: number
description: Campaign budget in the profile's currency
budget_type:
type: string
description: Budget type
enum:
- DEFAULT
- DAILY_FOR_ADGROUP
- MONTHLY_FOR_CAMPAIGN
- LIFETIME
search_bid:
type: number
description: Default search bid in the profile's currency
content_bid:
type: number
description: Default content bid in the profile's currency
status:
type: string
description: Campaign status
enum:
- ACTIVE
- PAUSED
- DELETED
- REVIEW
default: ACTIVE
order_line:
type: string
description: Order line of the campaign
start_date:
type: string
description: Campaign start date
format: yyyy-MM-dd
end_date:
type: string
description: Campaign end date
format: yyyy-MM-dd
tracking_level:
type: string
description: Campaign tracking level
enum:
- NONE
- PROFILE_DEFAULT
- CAMPAIGN
- ADS
- KEYWORDS
- ADS_AND_KEYWORDS
default: PROFILE_DEFAULT
campaign_type:
type: string
description: Campaign type
enum:
- TEXT_CAMPAIGN
- SMART_SHOPPING
- SHOPPING_STANDARD
default: TEXT_CAMPAIGN
shopping_settings:
$ref: '#/components/schemas/shoppingSettings'
EntityResponse:
type: object
properties:
id:
type: integer
format: int64
success:
type: boolean
errors:
type: array
items:
$ref: '#/components/schemas/ErrorField'
responses:
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: []
GetCampaignEntitySuccessResponse:
description: The operation was completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetCampaignApiResponse'
example:
status: SUCCESS
entities:
- id: 18204
channel_campaign_id: '7247592'
profile_id: 96
channel_account_id: 718
channel_type: Google
campaign_name: name
budget: 1000.0
budget_type: DEFAULT
search_bid: 0.0
content_bid: 0.0
status: DELETED
order_line: null
start_date: '2026-01-01'
end_date: '9999-12-31'
tracking_level: KEYWORDS
campaign_type: null
shopping_settings: {}
paging:
previous_page: null
next_page: MQ==
error_message: null
GetCampaignBadRequest:
description: Bad request (usually indicates validation failure for client input)
content:
application/json:
schema:
$ref: '#/components/schemas/GetCampaignApiResponse'
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: {}
ApiResponse:
$ref: '#/components/schemas/ApiResponse'
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