Kwai Ads
Kwai is the only connector on the platform without automatic login. There is no authorise button: credentials are issued by Kwai, over email, and typed into caOS. That is why the most important step happens off screen.
Start
Connectthe only one that asks for a credential
Here it is the client who acts, on their own platform: only they can request the credentials from Kwai. You cannot do it for them, and no button in caOS replaces that request. What you do is receive the three values and paste them in.
Ask the client's Kwai Ads contact for three items: Client ID, Client Secret and Refresh Token. They are the same three any data platform asks for, and they arrive in Kwai's email reply.
Ask for the authorisation as channel advertiser developer, stating that the data will be shared with caOS. This detail decides whether the connection works on its own. Kwai issues credentials in more than one type, and only that type can list the accounts by the caOS identifier. A credential issued as agency developer does connect, but needs one extra field, explained under When it fails.
On the new source screen, choose Kwai Ads, paste the three values and give the login a name. On confirm, caOS tests the credential against Kwai before storing anything: a refused credential never becomes a record.
What success looks like: the accounts for that credential appear in the list, with name, currency and legal name, already linked to a tag named after the login.
Your credential, and what happens to it
Kwai is the platform's exception. On every other connector the credential renews itself forever. Here the Refresh Token lasts 360 days and does not renew: the client has to request a new one from Kwai, over email, replying on the same onboarding thread.
Swapping the value costs nothing and loses nothing: the new value goes into Credentials · Renew token, without re-registering the client and without losing the accounts already linked. An expired credential shows up in the list with a token expired badge.
Your credential is encrypted end to end. It is encrypted before it is stored, and the key does not live in the database, so even database access does not reveal it. Nobody at caOS, and not you either, can read the credential back after it is saved. The screen only shows that it exists and is valid.
Only the metrics you asked for are read. caOS does not write to your ad account in order to extract data, and it stores no personal data about who saw the ad. Processing follows Brazilian data protection law (LGPD), and deletion is yours: revoking the connection erases the stored credential.
Reference
Metrics and dimensionswhat each field means
Kwai names its fields in its own way: an impression is called exposure, and video metrics start with photo. It is worth reading the table before building your first report.
Core metrics9 of 99
| API field | What it is | Where it shows up |
|---|---|---|
| cost | Spend, in the currency's smaller unit. | Spend in Pacer and Xtractor, already converted. See the note on units below. |
| exposure | How many times the ad was shown. | This is Kwai's impressions field. The name does not help. |
| click | Clicks on the ad. | Clicks. Singular, no s. |
| photoThruPlayCnt | ThruPlay: watched the whole video, or at least several seconds. | This is what the team defined as Kwai's video view. It is not a 100% completion. |
| photo25percentPlayCnt | Reached 25% of the video. Also 50 and 75. | Use it for a retention curve. |
| photoAvgPlayTime | Average watch time. | Good for comparing creatives against each other. |
| ctr | Clicks ÷ impressions. | CTR. Pacer recomputes it from the sums. |
| cpm | Cost per thousand impressions. | CPM, also recomputed. |
| cpc | Cost per click. | CPC, also recomputed. |
Dimensions4
| API field | What it is | Where it shows up |
|---|---|---|
| date | The day of the row. | Performance always comes daily. |
| account_id | The ad account. | Comes with the legal name and the currency. |
| campaign_id | The campaign. | There is also an ad group level and a creative level. |
| creative_id | The creative, which on Kwai is the ad itself. | Kwai has no ad level separate from the creative. |
Report parameters
The fields above say what comes back. These parameters say how: they decide the grain of the row, the period it covers and what counts as a conversion. Two reports from the same account showing different numbers almost always differ here.
| Parameter | What it changes | Values |
|---|---|---|
| report endpoint | The level of each row. | One address per level: account, campaign, ad group, creative, video, audience and app. It is not a parameter, it is the call that changes. |
| timeRange | The period. | Comes from the source. Kwai returns the day already aligned to the account time zone. |
| granularity | The aggregation. | Daily. Kwai offers no hourly cut in the reports caOS uses. |
| cost unit | How the value arrives. | Converted by caOS before writing. See the unit note above before querying the API yourself. |
Everything you can pull
The tables above are what most reports use, but you are not stuck with them. The full Kwai catalogue has 16 tables and 766 fields, and you choose what goes in when you build the source. What is marked used by default is what the example source uses; the rest is available just the same.
The list below comes from the Xtractor catalogue itself, the same one the new source screen reads. If a field is here, the screen offers it.
creative_effect_daily104 fields
accountId, creativeId, creativeName, unitId, campaignId, photoId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
unit_effect_daily102 fields
accountId, unitId, unitName, campaignId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
app_target_effect_daily101 fields
accountId, appId, countryCode, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
campaign_effect_daily101 fields
accountId, campaignId, campaignName, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
population_analysis_effect_daily101 fields
accountId, countryCode, osType, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
photo_effect_daily100 fields
accountId, photoId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
account_effect_daily used by default99 fields
accountId, time, cost, exposure, click, ctr, cpm, cpc, action, cvr, cpa, play3s, play5s, playFinished, play3sRate, costPerformancePlay3s, play5sRate, costPerformancePlay5s, photoThruPlayCnt, costPhotoThruPlay, photoThruPlayRate, photo25percentPlayCnt, costPhoto25percentPlay, photo25percentPlayRate, photo50percentPlayCnt, costPhoto50percentPlay, photo50percentPlayRate, photo75percentPlayCnt, costPhoto75percentPlay, photo75percentPlayRate, photoAvgPlayTime, activation, costPerActivation, activationRate, appLaunch, costPerAppLaunch, appLaunchRate, uniqueAppLaunch, costUniqueAppLaunch, firstReengageRate, pageView, costPerPageView, pageViewRate, uniquePageView, costUniquePageView, firstPageViewRate, registration, costPerRegistration, registrationRate, addToCar, costPerAddToCart, addToCartRate, purchase, purchaseRate, costPurchase, uniquePurchase, costUniquePurchase, purchase24hValue, totalDayOneRetention, costPerDayOneRetention, dayOneRetentionRate, totalDayOneRetentionPlatformAttribution, costPerDayOneRetentionPlatformAttribution, dayOneRetentionRatePlatformAttribution, keyInAppAction, costKeyInAppAction, uniqueKeyInAppAction, costUniqueKeyInAppAction, uniqueKeyInAppEventFirst, uniqueKeyInAppEventSecond, uniqueKeyInAppEventThird, firstAdViewCnt, costFirstAdView, firstAdViewRate, firstAdClickCnt, costFirstAdClick, firstAdClickRate, adView, costAdView, adViewRate, adClick, costAdClick, adClickRate, adView24hValue, firstDeposit, costFirstDeposit, firstDepositRate, creditApproval, costCreditApproval, creditApprovalRate, loanApplication, costLoanApplication, loanApplicationRate, loanCredit, costLoanCredit, loanCreditRate, loanDisbursal, costLoanDisbursal, loanDisbursalRate
apps12 fields
accountId, appId, appName, appIconUrl, appPlatform, appMarketLink, appPackageName, tracingType, trackingProvider, impressionUrl, clickUrl, createTime
audiences8 fields
accountId, orientationId, orientationName, populationType, status, coverNum, recordSize, createTime
avatars7 fields
accountId, avatarId, avatarType, description, avatarUrl, usedCount, createTime
units7 fields
accountId, unitId, unitName, campaignId, bidType, status, createTime
campaigns6 fields
accountId, campaignId, campaignName, marketingGoal, status, createTime
playables6 fields
accountId, playableId, playableName, thumbnailUrl, playableUrl, createTime
interaction_addons5 fields
accountId, materialId, materialName, materialType, createTime
pixels4 fields
accountId, pixelId, name, createTime
account_list3 fields
accountId, accountName, corporationName
You convert nothing. The value reaches your destination already in the account currency: caOS converts before writing. This matters because the source unit is an open question: Kwai's documentation says cost fields arrive in cents, and the conversion we use, validated against real data from two accounts, divides by 1,000,000. Anyone querying the API outside caOS should check the result against a known day of spend rather than trusting either number.
Kwai does not expose reach. There is no reach and no frequency anywhere in the API, unlike Meta and TikTok. A report that depends on reach has to treat Kwai separately.
Output
Where the data landsa spreadsheet and a warehouse are different jobs
Google Sheets
For building a report by hand
Tick spend, exposure (which is impressions), click and the campaign name. The field names are Kwai's own, so it is worth renaming the columns in your report.
For video, the field the team uses as a view is the ThruPlay one, not completion.
BigQuery
For modelling on top
16 datasets. Performance comes daily, and you choose the level: account, campaign, ad group, creative, video or audience analysis.
Alongside come the structure tables: campaigns, ad groups, creatives, apps, audiences, pixels and the account list.
Trust
Data freshnesswhy yesterday's number still moves
Ad platforms rewrite the past. A conversion attributed days later, revised spend, a corrected row: Tuesday's number changes on Thursday. If the extraction only ever brought the newest day, your spreadsheet would freeze at the first value and drift away from the platform with nobody noticing.
So caOS re-reads the last 30 days on every sync and rewrites what changed. Older history stays in the destination and is not touched. In practice: what sits in your spreadsheet or your warehouse is what the platform says today, not what it said on the day of the first load.
Detail
Good to knowwhat usually raises questions
Kwai keeps a single access token alive per application. If the same credential is used by another tool at the same time, one knocks the other out. In practice the platform handles this, but it explains intermittent failures when the same credential is in use outside caOS.
The creative is the ad. Kwai has no separate ad level, so the creative identifier is what plays the role of the ad identifier.
Support
When it failsthe message and what to do
“Kwai does not accept the caOS Corp ID on this credential.” This is not an invalid credential: it means it was issued as agency developer, and that type lists accounts by its own identifier. The screen then reveals the Agent ID field, a number that came in the same Kwai email as the credentials. Fill it in and confirm again. Data access is not affected.
“Kwai refused this refresh token.” The pasted value is not the most recent one, or is not paired with this Client ID. Check the newest email from Kwai.
“Kwai refused the Client ID + Secret pair.” The problem is not the token, which was never even tested. The whole credential has to be reissued.
“Nothing to register: every account already belongs to an active credential.” This client is already connected. If you meant to renew the token, use Renew token on the existing credential; if you meant to replace it, revoke the old one first.
Revoking a credential erases the stored Client ID, Secret and Refresh Token, and unlinks the accounts. Have the three values in hand before revoking.