{"info":{"title":"Euka API","version":"1.0.0","description":"Customer-facing API for brand-owned sales, collabs, creator, and store data. Create an OpenAPI key in the Euka app from Settings > Integrations > OpenAPI keys, then pass it as Authorization: Bearer euka_openapi_...."},"servers":[{"url":"/api/v1"}],"openapi":"3.1.1","paths":{"/ping":{"get":{"operationId":"ping","summary":"Ping","description":"Check whether the Euka API is reachable.","tags":["System"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"},"version":{"type":"string"},"time":{"type":"string"}},"required":["status","version","time"]}}}}}}},"/me":{"get":{"operationId":"getCurrentOpenApiKey","summary":"Current key","description":"Returns metadata for the OpenAPI key used in the Authorization header.","tags":["Authentication"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"ownerManagerId":{"type":"string"},"name":{"type":"string"},"brandAccessMode":{"enum":["all","selected"],"type":"string"},"brandIds":{"type":"array","items":{"type":"string"}}},"required":["keyId","ownerManagerId","name","brandAccessMode","brandIds"]}}}}},"security":[{"openApiKey":[]}]}},"/brands":{"get":{"operationId":"listBrands","summary":"List brands","description":"Returns brands this OpenAPI key can access.","tags":["Brands"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","name","slug","createdAt"]}}}}}},"security":[{"openApiKey":[]}]}},"/stores":{"get":{"operationId":"listStores","summary":"List stores","description":"Returns stores under the brands this OpenAPI key can access.","tags":["Stores"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"type":"string"},"shopId":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","name","code","region","shopId","createdAt"]}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/performance-overview":{"post":{"operationId":"getDashboardPerformanceOverview","summary":"Performance overview","description":"Read Dashboard Performance metrics, prior-period changes, latest available dates, and data availability notes. Every *Difference field is the percent change from the preceding period of equal length; for a rate that is a relative change, not percentage points. allAccountVideoViews counts views earned during the dates by every shop-linked video, whatever its post date; avgViewsPerVideo is the lifetime views so far (mostly shoppable-video impressions) of affiliate videos posted in the range, per video, so the two answer different questions. postRate.value is completed ÷ (completed + unfulfilled) × 100 over samples shipped in the range; TikTok marks a sample unfulfilled only after its posting deadline, so the rate reads high while postRate.pending is large.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"videoGmvThreshold":{"type":"number","description":"Minimum creator-video revenue counted as a converting video. Defaults to 1."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"impressions":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Affiliate shoppable-video impressions at store scope; creator-video views under product or campaign scope."},"impressionsDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"impressionsPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"allAccountVideoViews":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Views earned during the selected dates by every video linked to the shop, seller-owned and affiliate, whatever its post date. From TikTok Shop daily video analytics."},"allAccountVideoViewsDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Percentage change in all-account video views when stored coverage spans both periods."},"allAccountVideoViewsPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"videoViewsDataThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Latest ingested TikTok video-view activity date."},"totalAffiliateGMV":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Affiliate GMV for the selected view: GMV from affiliate accounts' videos and LIVE, excluding showcase sales. Filtered views use Product Analytics VIDEO plus LIVE GMV. TikTok keeps only recent days: when performanceRangeCoverage.isTruncated is true, this total covers only effectiveRange, so state that range alongside the figure."},"totalAffiliateGMVDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"totalAffiliateGMVPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"affiliateCommission":{"anyOf":[{"type":"object","properties":{"current":{"type":"number","description":"Estimated commission on affiliate orders created in the selected dates, in currency."},"previous":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Null when the preceding period could not be read in full."},"currency":{"type":"string","description":"Currency of current and previous; always USD."}},"required":["current","previous","currency"]},{"type":"null"}],"default":null,"description":"Estimated creator, Shop Ads, and partner commission by order creation time for full current and preceding selected periods. US/GMT-8, shop-wide only; excludes bonuses. Order lines TikTok returns without any commission amount are left out and reported in sourceWarnings. GMV may end at an earlier finalized date, so do not derive a commission rate from these totals. May differ from Affiliate Center totals."},"affiliatePerformanceIncomplete":{"type":"boolean","default":false,"description":"Indicates incomplete Affiliate reporting for the selected range."},"affiliateFunnelOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"TikTok Shop orders used to calculate Affiliate Average Order Value."},"affiliateFunnelOrdersDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length).","default":null},"affiliateFunnelOrdersPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"affiliateFunnelGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"GMV used to calculate Affiliate Average Order Value: Total GMV in the All Products, All Campaigns view and Affiliate GMV in filtered views."},"totalOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Checkout orders for the same Dashboard view as Total GMV."},"totalOrdersDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"totalOrdersPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"totalShopGMV":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Total GMV, or Product Analytics all-channel GMV in filtered views."},"totalShopGMVDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"totalShopGMVPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"shopLiveGMV":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop LIVE GMV for the All Products, All Campaigns view when its currency is consistent."},"shopLiveGMVDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"shopLiveGMVPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"performanceDataThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Latest finalized date included in Total GMV, Orders, Average Order Value, Shop LIVE GMV, Seller GMV, and Affiliate GMV: the earlier of TikTok's Shop Performance and affiliate video and LIVE ready dates. With product or campaign filters, Product Performance's ready date."},"performanceRangeCoverage":{"anyOf":[{"type":"object","properties":{"requestedRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive requested start date."},"endDate":{"type":"string","description":"Inclusive requested end date."}},"required":["startDate","endDate"],"description":"The dates the request asked for."},"effectiveRange":{"anyOf":[{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive first readable date: the requested start, or the retention start when that is later."},"endDate":{"type":"string","description":"Inclusive last date, the same as the requested end."}},"required":["startDate","endDate"]},{"type":"null"}],"description":"The part of the requested dates inside TikTok’s retention window (180 days for Shop Performance, 178 for Product Performance and Affiliate GMV). Null when none of it is."},"isTruncated":{"type":"boolean","description":"Whether retention cut off the start of the requested dates, so effectiveRange starts later than requestedRange."}},"required":["requestedRange","effectiveRange","isTruncated"],"description":"Requested range and the range queryable from the active TikTok performance source after retention limits. The effective end does not imply provider freshness or gap-free data."},{"type":"null"}],"default":null,"description":"Dates the performance figures cover. Without filters, Total GMV, Orders, Seller GMV and Affiliate GMV share one start, so this is TikTok Shop Performance coverage, or Affiliate GMV coverage when that starts later. With product/campaign filters, Product Performance coverage."},"shopPerformanceLatestAvailableDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok's latest ready Shop Performance date in the shop's local timezone."},"shopPerformanceCurrentRangeComplete":{"type":"boolean","description":"Whether the selected start is within TikTok Shop Performance retention and the readiness date covers the selected end date."},"orderDays":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Number of finalized reporting dates included in Orders."},"gmvFiltered":{"type":"boolean","description":"Indicates that product or campaign filters define Total GMV."},"filteredGmvUnavailable":{"type":"boolean","description":"Indicates that Total GMV is unavailable for the selected product or campaign filters."},"hasAdsApiConfig":{"type":"boolean","description":"Whether the store has an active TikTok Ads connection."},"shopGmvError":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Availability note for Total GMV and Orders."},"sourceWarnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code."},"metrics":{"type":"array","items":{"type":"string"},"description":"Affected Dashboard metric keys."},"primarySource":{"type":"string","description":"Dashboard data source for the affected metrics."},"message":{"type":"string","description":"User-readable availability explanation."}},"required":["code","metrics","primarySource","message"],"additionalProperties":{}},"description":"Availability notes for affected Dashboard metrics."},"videoConvRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage of posted creator videos meeting the revenue threshold. Null when no creator video was posted in the range."},"videoConvRateDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"videoConvRatePrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"videoConvRateTotalVideos":{"type":"number","description":"Posted creator videos in the selected range."},"videoConvRatePreviousTotalVideos":{"type":"number","description":"Posted creator videos in the preceding equal-length period."},"videoConvRateConvertingVideos":{"type":"number","description":"Posted creator videos meeting the revenue threshold."},"creatorsReached":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Unique creators contacted through Euka messages or invites."},"creatorsReachedDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"creatorsReachedPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"activeCreators":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Unique creators who posted a creator video in the selected range."},"activeCreatorsDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"activeCreatorsPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"avgViewsPerVideo":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views so far (mostly shoppable-video impressions) of affiliate videos posted in the selected dates, divided by those videos."},"avgViewsPerVideoDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"avgViewsPerVideoPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"revenuePerCreator":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Creator-video attributed revenue divided by unique creators who posted."},"revenuePerCreatorDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"revenuePerCreatorPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"fulfillmentRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Samples shipped in the period divided by sample requests created in the period, expressed as a ratio from 0 to 1. Null when no sample was requested in the period."},"fulfillmentRateDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"fulfillmentRatePrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"samplesApproved":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Requests created in the period that have reached approval or a later stage."},"samplesApprovedDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"samplesApprovedPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"messagesSent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Initial Euka conversation messages sent in the selected period."},"messagesSentDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"messagesSentPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"samplesShippedTotal":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sample requests whose shipped time falls in the selected period."},"samplesShippedDifference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"samplesShippedTotalPrevious":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"postRate":{"type":"object","properties":{"shipped":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Samples shipped in the selected period."},"completed":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Selected-period shipped samples whose current status is Completed."},"unfulfilled":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Selected-period shipped samples whose current status is Content Unfulfilled."},"pending":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Selected-period shipped samples not yet Completed or Content Unfulfilled. value leaves them out, so it is provisional while this is large."},"previousShipped":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Samples shipped in the preceding equal-length period."},"previousCompleted":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Preceding-period shipped samples whose current status is Completed."},"previousUnfulfilled":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Preceding-period shipped samples whose current status is Content Unfulfilled."},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Completed divided by resolved samples (Completed + Content Unfulfilled), expressed as a percentage from 0 to 100. Pending samples are excluded, and TikTok marks a sample Content Unfulfilled only after its posting deadline, so recent ranges read high."},"difference":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"previousValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."}},"required":["shipped","completed","previousShipped","previousCompleted","value","difference"],"additionalProperties":{},"description":"Post Rate for samples shipped in the selected period, with the counts behind it and the preceding period’s. Every field is null when the counts are unavailable; sourceWarnings then says so."}},"required":["impressions","impressionsDifference","totalAffiliateGMV","totalAffiliateGMVDifference","totalOrders","totalOrdersDifference","totalShopGMV","totalShopGMVDifference","shopLiveGMV","shopLiveGMVDifference","shopPerformanceLatestAvailableDate","shopPerformanceCurrentRangeComplete","orderDays","gmvFiltered","filteredGmvUnavailable","hasAdsApiConfig","shopGmvError","sourceWarnings","videoConvRate","videoConvRateDifference","videoConvRateTotalVideos","videoConvRatePreviousTotalVideos","videoConvRateConvertingVideos","creatorsReached","creatorsReachedDifference","activeCreators","activeCreatorsDifference","avgViewsPerVideo","avgViewsPerVideoDifference","revenuePerCreator","revenuePerCreatorDifference","fulfillmentRate","fulfillmentRateDifference","samplesApproved","samplesApprovedDifference","messagesSent","messagesSentDifference","samplesShippedTotal","samplesShippedDifference","postRate"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/performance-series":{"post":{"operationId":"getDashboardPerformanceSeries","summary":"Performance series","description":"Read daily Dashboard trends for GMV, orders, videos, outreach, samples, and ad spend.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sampleRequests":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Deprecated and always absent; read sample_requests in analyticsAggregated."},"shippedSampleRequests":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Deprecated and always absent; read samples_shipped in analyticsAggregated."},"videoPosted":{"type":"array","items":{"type":"object","properties":{"posted_date":{"type":"string","description":"When the video was posted, in UTC, as YYYY-MM-DD HH:MM:SS."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The video’s lifetime attributed revenue to date, in the shop’s currency; 0 when it has none."}},"required":["posted_date"]},"description":"Creator videos posted in the selected dates (Pacific), one row per video, newest first; group by posted date for daily counts."},"performances":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Dashboard reporting date."},"total_gmv":{"type":"number","description":"Affiliate GMV for the date."},"total_orders":{"type":"number","description":"Checkout orders for the date."},"total_shop_gmv":{"type":"number","description":"Shop or filtered all-channel GMV for the date."}},"required":["date","total_gmv"],"additionalProperties":{}}},{"type":"null"}],"description":"Daily Affiliate GMV, Total GMV, and order values."},"analyticsAggregated":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Pacific activity date."},"messages_sent":{"type":"number","description":"Initial conversation messages sent."},"messages_replied":{"type":"number","description":"Initial messages with a reply."},"followups_sent":{"type":"number","description":"Follow-up messages sent."},"target_invites":{"type":"number","description":"Target Collaboration invites sent."},"sample_requests":{"type":"number","description":"Sample requests created."},"samples_shipped":{"type":"number","description":"Sample requests shipped."},"emails_sent":{"type":"number","description":"Campaign emails sent."},"emails_opened":{"type":"number","description":"Sent emails with an open event."}},"required":["date","messages_sent","messages_replied","followups_sent","target_invites","sample_requests","samples_shipped","emails_sent","emails_opened"],"additionalProperties":{}},"description":"Daily outreach, invitation, email, and sample activity."},"dailyAdCost":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Ads reporting date."},"ad_cost":{"type":"number","description":"GMV Max ad spend for the date across the store’s ad accounts, in their billing currency (adSpendCurrency in adsOverview)."}},"required":["date","ad_cost"]},"description":"Daily GMV Max spend, newest first, the same figures as adsOverview; days without spend are omitted. Empty without a TikTok Ads connection or when the filters match no products; sourceWarnings names days left out."}},"required":["videoPosted","performances","analyticsAggregated"],"additionalProperties":{},"description":"Daily series for the selected dates: creator videos, GMV and orders, outreach and sample activity, and ad spend."},"hasAdsApiConfig":{"type":"boolean","description":"Whether the store has an active TikTok Ads connection."},"sourceWarnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code."},"metrics":{"type":"array","items":{"type":"string"},"description":"Affected Dashboard metric keys."},"primarySource":{"type":"string","description":"Dashboard data source for the affected metrics."},"message":{"type":"string","description":"User-readable availability explanation."}},"required":["code","metrics","primarySource","message"],"additionalProperties":{}},"description":"Availability notes for affected Dashboard trends."},"filteredGmvUnavailable":{"type":"boolean","description":"Indicates that Total GMV is unavailable for the selected product or campaign filters."},"affiliatePerformanceIncomplete":{"type":"boolean","default":false,"description":"Indicates incomplete Affiliate reporting for the range."},"performanceDataThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Latest finalized date included in daily Total GMV, Orders, and Affiliate GMV: the earlier of TikTok's Shop Performance and affiliate video and LIVE ready dates. With product or campaign filters, Product Performance's ready date."},"performanceRangeCoverage":{"anyOf":[{"type":"object","properties":{"requestedRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive requested start date."},"endDate":{"type":"string","description":"Inclusive requested end date."}},"required":["startDate","endDate"],"description":"The dates the request asked for."},"effectiveRange":{"anyOf":[{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive first readable date: the requested start, or the retention start when that is later."},"endDate":{"type":"string","description":"Inclusive last date, the same as the requested end."}},"required":["startDate","endDate"]},{"type":"null"}],"description":"The part of the requested dates inside TikTok’s retention window (180 days for Shop Performance, 178 for Product Performance and Affiliate GMV). Null when none of it is."},"isTruncated":{"type":"boolean","description":"Whether retention cut off the start of the requested dates, so effectiveRange starts later than requestedRange."}},"required":["requestedRange","effectiveRange","isTruncated"],"description":"Requested range and the range queryable from the active TikTok performance source after retention limits. The effective end does not imply provider freshness or gap-free data."},{"type":"null"}],"default":null,"description":"Dates the performance figures cover. Without filters, Total GMV, Orders, Seller GMV and Affiliate GMV share one start, so this is TikTok Shop Performance coverage, or Affiliate GMV coverage when that starts later. With product/campaign filters, Product Performance coverage."}},"required":["data","hasAdsApiConfig","sourceWarnings","filteredGmvUnavailable"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/campaign-breakdown":{"post":{"operationId":"getDashboardCampaignBreakdown","summary":"Campaign breakdown","description":"Read campaign-level video revenue, revenue per creator, average views per video, videos posted, sample activity, creators reached, and response rate.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"videos_data":{"type":"array","items":{"type":"object","properties":{"campaign_id":{"type":"string","description":"Euka outreach campaign id, as a string."},"campaign_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Campaign name. Null when it could not be found."},"revenue":{"type":"number","description":"Creator-video attributed revenue for the campaign."},"revenue_per_creator":{"type":"number","description":"Creator-video revenue divided by unique creators."},"average_views_per_video":{"type":"number","description":"Creator-video views divided by videos posted."},"videos_posted":{"type":"number","description":"Creator videos posted for the campaign."}},"required":["campaign_id","campaign_name","revenue","revenue_per_creator","average_views_per_video","videos_posted"],"additionalProperties":{}},"description":"One row per outreach campaign with creator videos posted in the selected dates (Pacific). Revenue and views are those videos’ lifetime totals to date, revenue in the shop’s currency."},"samples_data":{"anyOf":[{},{"type":"null"}],"description":"Per-campaign sample activity for the selected range."},"creators_reached_data":{"type":"array","items":{"type":"object","properties":{"campaign_id":{"type":"string","description":"Euka outreach campaign id, as a string."},"campaign_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Campaign name. Null when it could not be found."},"creators_reached":{"type":"number","description":"Unique creators contacted by message or invite."},"response_rate":{"type":"number","description":"Unique creators who replied or accepted divided by creators reached, expressed as a ratio from 0 to 1."}},"required":["campaign_id","campaign_name","creators_reached","response_rate"],"additionalProperties":{}},"description":"One row per outreach campaign that contacted creators in the selected dates (Pacific)."}},"required":["videos_data","creators_reached_data"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/affiliate-funnel":{"post":{"operationId":"getDashboardAffiliateFunnel","summary":"Affiliate funnel","description":"Read creators reached, creators who posted, creators awaiting content after a sample was shipped, and samples shipped for the selected period.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unique":{"type":"number","description":"Unique creators reached by message or invite."},"posted":{"type":"number","description":"Unique creators who posted a creator video."},"unfulfilled":{"type":"number","description":"Unique creators with a shipped sample currently awaiting content."},"samplesShipped":{"type":"number","description":"Sample requests whose shipped time falls in the period."}},"required":["unique","posted","unfulfilled","samplesShipped"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/conversion-funnel":{"post":{"operationId":"getDashboardConversionFunnel","summary":"Conversion funnel","description":"Read Affiliate impressions, estimated product page views, items sold, daily funnel values, and current lifetime video views grouped by post date.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"conversionFunnel":{"type":"object","properties":{"impressions":{"type":"number","description":"Affiliate video impressions."},"pdp_impressions":{"type":"number","description":"Estimated product-detail-page impressions from Affiliate impressions and click-through rate."},"checkout":{"type":"number","description":"TikTok Shop Affiliate items sold in the selected period."}},"required":["impressions","pdp_impressions","checkout"],"additionalProperties":{},"description":"Funnel totals for the selected dates."},"daily":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Daily Affiliate impression, PDP estimate, items-sold, and GMV values."},"dailyViews":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"Creator videos' lifetime views grouped by their posted date."}},"required":["conversionFunnel","daily","dailyViews"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/top-videos-by-revenue":{"post":{"operationId":"getDashboardTopVideosByRevenue","summary":"Top videos by revenue","description":"Rank creator videos posted in the selected dates by lifetime attributed revenue, with product and campaign filters, as the Dashboard Top Videos card does. It does not rank revenue earned inside the dates.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"filter":{"type":"object","properties":{"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Required creator-video posted-date range for dashboard top videos."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"fromCampaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids selected in the Performance tab. Defaults to All Campaigns."}},"required":["postedDateRange"],"description":"Creator-video posted-date range with product and campaign scope."},"limit":{"type":"number","default":5,"description":"Maximum videos to return. Defaults to 5; maximum is 50."}},"required":["brandId","filter"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"videos":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string","description":"Creator video id, the videoId the video tools take."},"creatorVideoPhotoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the video’s cover image. Null when Euka has none."},"creatorId":{"type":"string","description":"Creator’s Euka id, the creatorId get_creator_profile takes."},"creatorHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s TikTok handle, without the @. Null when unknown."},"creatorProfilePicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the creator’s profile picture; it may not load when Euka has no copy of it."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime revenue attributed to the creator video to date, in the shop’s currency."},"postedDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator-video posted timestamp."},"viewsCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok views of the creator video to date."},"likesCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok likes of the creator video to date."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"productTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the shop product tagged in the video. Null when it tags none of the shop’s products."},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Shop product id of the shop product tagged in the video. Null when it tags none of the shop’s products."},"productPhotoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of that product’s image; it may not load when Euka has no copy of it. Null when productId is null."},"sparkCodes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Spark codes recorded for the video in this shop, newest first; empty when none."},"usageRightsRequestId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The brand's usage rights request for the video: the one behind its live license, otherwise its latest open request."},"gmvMaxCost":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV Max ad spend on the video over the trailing year, in gmvMaxCurrency. Like every GMV Max field here, it comes from the video’s highest-ROI campaign, not a total across campaigns. Null when no GMV Max report covers the video."},"gmvMaxCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Currency of the GMV Max amounts: the ad account’s billing currency. Null when unknown."},"gmvMaxRoi":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ROI TikTok reported for the video’s highest-ROI GMV Max campaign: paid and organic sales divided by ad spend."},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product clicks from the video’s ads in its highest-ROI GMV Max campaign, trailing year."},"adConversionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad conversion rate TikTok reported for that campaign (orders divided by ad clicks), as a percentage from 0 to 100."},"costPerOrder":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad spend per ad order for that campaign, in gmvMaxCurrency."},"gmvOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Orders TikTok attributed to that campaign’s ads for the video."},"gmvGrossRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Gross revenue TikTok reported for that campaign’s ads for the video, in gmvMaxCurrency."},"adItemsSoldCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the video’s items sold because of ads: productClicks × adConversionRate, capped at its lifetime items sold. Can be fractional."},"adRoi":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of adSales divided by gmvMaxCost."},"adSalesPct":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the share of the video’s lifetime items sold that came from ads, as a ratio from 0 to 1."},"adSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the video’s lifetime revenue that came from ads (revenue × adSalesPct), in the shop’s currency."},"acos":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad cost per ad-driven item: gmvMaxCost divided by adItemsSoldCount, in gmvMaxCurrency."},"adReportSynced":{"type":"boolean","description":"Whether a GMV Max report covers the video. When false, the GMV Max fields and ad estimates are null."}},"required":["videoId","creatorVideoPhotoUrl","creatorId","creatorHandle","creatorProfilePicUrl","revenue","postedDate","viewsCount","likesCount","description","productTitle","productId","productPhotoUrl","sparkCodes","usageRightsRequestId","gmvMaxCost","gmvMaxRoi","productClicks","adConversionRate","costPerOrder","gmvOrders","gmvGrossRevenue","adItemsSoldCount","adRoi","adSalesPct","adSales","acos","adReportSynced"],"additionalProperties":{}},"description":"Creator videos posted in the selected dates, highest-ranked first, at most limit."},"page":{"type":"number","description":"Always 1: the ranking returns a single page."},"pageSize":{"type":"number","description":"The limit requested."}},"required":["videos","page","pageSize"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/top-products-by-all-channel-gmv":{"post":{"operationId":"getDashboardTopProductsByAllChannelGmv","summary":"Top products by all-channel GMV","description":"Rank products by TikTok Shop all-channel GMV for the selected sales dates, including GMV and items sold.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"salesDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive TikTok Shop sales reporting date range."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids applied after ranking. Defaults to All Products."},"limit":{"type":"number","default":5,"description":"Maximum ranked rows to return. Defaults to 5; maximum is 50."}},"required":["brandId","salesDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"TikTok Shop product id."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title. Null when Euka has no record of it."},"itemsSold":{"type":"number","description":"All-channel items sold."},"totalGmv":{"type":"number","description":"TikTok Product Analytics all-channel product GMV."}},"required":["productId","title","itemsSold","totalGmv"],"additionalProperties":{}},"description":"Products ranked by all-channel GMV for the sales dates, highest first, at most limit. Amounts are in the shop’s currency."}},"required":["products"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/top-creators-by-gmv":{"post":{"operationId":"getDashboardTopCreatorsByGmv","summary":"Top creators by GMV","description":"Rank up to the requested limit of creators by TikTok Shop Affiliate GMV for the selected sales reporting dates, including video count and prior-period change. postedDateRange uses startDate/endDate and filters daily sales, not video publication. If fewer rows are returned, report the actual count. Available in the All Products, All Campaigns store view.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"limit":{"type":"number","default":5,"description":"Maximum ranked rows to return. Defaults to 5; maximum is 50."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"affiliates":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string","description":"Creator’s TikTok handle, without the @."},"uidShop":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s Euka id, the creatorId get_creator_profile takes. Null when Euka has no profile for the handle."},"totalGmv":{"type":"number","description":"TikTok Shop Affiliate GMV for the date range."},"videoCount":{"type":"number","description":"Creator videos posted in the date range."},"revenueDelta":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."}},"required":["handle","uidShop","totalGmv","videoCount","revenueDelta"],"additionalProperties":{}},"description":"Creators ranked by TikTok Shop Affiliate GMV for the date range, highest first, at most limit. Empty when product or campaign filters are active (see unavailableUnderFilter)."},"unavailableUnderFilter":{"type":"boolean","description":"Indicates that product or campaign filters are active and this metric is available in the All Products, All Campaigns view."}},"required":["affiliates"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/livestream-gmv":{"post":{"operationId":"getDashboardLivestreamGmv","summary":"Livestream GMV","description":"Read TikTok Shop Affiliate LIVE GMV for the selected date range, including prior-period change. Available in the All Products, All Campaigns store view.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Affiliate LIVE GMV for the selected date range."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"previous":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"unavailableUnderFilter":{"type":"boolean","description":"Indicates that product or campaign filters are active and this metric is available in the All Products, All Campaigns view."}},"required":["current","delta"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/sample-approval-rate":{"post":{"operationId":"getDashboardSampleApprovalRate","summary":"Sample approval rate","description":"Read requested/approved sample counts, approval rate, and prior-period rate change for non-archived requests in the brand’s primary Dashboard store. postedDateRange uses startDate/endDate and filters request creation in America/Los_Angeles business dates, not approval time. Approved means currently past review, excluding canceled. Product filters take precedence over campaign filters.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Requests created in the period that have reached approval or a later stage, divided by requests created, expressed as a percentage from 0 to 100."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"previousRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"approved":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Requests created in the period that have reached approval or a later stage."},"requested":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sample requests created in the period."}},"required":["rate","delta"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/featured-products-count":{"post":{"operationId":"getDashboardFeaturedProductsCount","summary":"Featured products count","description":"Count products featured in creator videos posted in the period, including daily counts and prior-period change.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","description":"Distinct products featured in creator videos posted in the period."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"previousTotal":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"daily":{"type":"array","items":{"type":"number"},"description":"Distinct-product counts for returned activity days in ascending date order."}},"required":["total","delta","daily"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/ads-overview":{"post":{"operationId":"getDashboardAdsOverview","summary":"Ads overview","description":"Read GMV Max ad spend, attributed revenue, and orders for the selected and compared dates, plus daily data for ROAS: the same figures as the GMV Max page. Date, product, and campaign filters define the result.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"currency":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"adKpis":{"anyOf":[{"type":"object","properties":{"currentSpend":{"type":"number","description":"Ad spend in the selected dates."},"currentRevenue":{"type":"number","description":"Ads-attributed revenue in the selected dates."},"currentOrders":{"type":"number","description":"Ads-attributed orders in the selected dates."},"previousSpend":{"type":"number","description":"Ad spend in the compared dates; 0 with no comparison."},"previousRevenue":{"type":"number","description":"Ads-attributed revenue in the compared dates; 0 with no comparison."},"previousOrders":{"type":"number","description":"Ads-attributed orders in the compared dates; 0 with no comparison."},"currentRoas":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's own ROAS in the selected dates: ads revenue over spend in the ad account's currency. Read ROAS from here when money is converted: converted spend and revenue give a slightly different ratio. Null without spend."},"previousRoas":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's own ROAS in the compared dates, as currentRoas. Null without spend or with no comparison."}},"required":["currentSpend","currentRevenue","currentOrders","previousSpend","previousRevenue","previousOrders"]},{"type":"null"}],"description":"GMV Max totals for the selected and compared dates (compareTo), amounts in adSpendCurrency: the same figures as the GMV Max page, synced daily from TikTok with the days since the last sync read live (see freshness). Narrowed by product or campaign, they cover synced days only. All zero when those filters match no products."},"adSpendCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The currency every amount is in: the ad accounts' billing currency (accountCurrency), or the shop's when currency is shop and it could be converted. Null when the product or campaign filters match no products."},"accountCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ad accounts' billing currency, which TikTok reports in. Null when the filters match no products."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"dailyRoas":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Ads reporting date, YYYY-MM-DD in the ad account time zone."},"cost":{"type":"number","description":"Ad spend for the date."},"revenue":{"type":"number","description":"Ads-attributed revenue for the date."},"orders":{"type":"number","description":"Ads-attributed orders for the date."},"roas":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's own ROAS for the date: ads revenue over spend in the ad account's currency, so showing money in the shop's never moves it. Null without spend."}},"required":["date","cost","revenue","orders"]},"description":"GMV Max values per ads reporting date in the selected dates, oldest first, in adSpendCurrency; a date’s ROAS is revenue divided by cost. Dates without ad activity, and dates freshness says were left out, are omitted."},"previousDailyRoas":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Ads reporting date, YYYY-MM-DD in the ad account time zone."},"cost":{"type":"number","description":"Ad spend for the date."},"revenue":{"type":"number","description":"Ads-attributed revenue for the date."},"orders":{"type":"number","description":"Ads-attributed orders for the date."},"roas":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's own ROAS for the date: ads revenue over spend in the ad account's currency, so showing money in the shop's never moves it. Null without spend."}},"required":["date","cost","revenue","orders"]}},{"type":"null"}],"default":null,"description":"The same per-date GMV Max values for the compared dates (compareTo), oldest first; null with no comparison. Dates without ad activity are omitted. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"Which days the figures cover: synced through syncedThrough, the days after it read live from TikTok, or left out when TikTok could not be read or a product or campaign filter limits them to the daily sync (liveTail.status). Absent when the filters match no products."}},"required":["adKpis","dailyRoas"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/boosted-videos":{"post":{"operationId":"getDashboardBoostedVideos","summary":"Boosted videos","description":"Rank creator videos posted in the selected dates by their trailing-year GMV Max ad spend (not spend within those dates), with product filters, including ad spend, ROAS, revenue, views, and creator details. \"Boosted\" means ad spend here, not an active TikTok Creative Boost.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"limit":{"type":"number","default":50,"description":"Maximum videos to return, ranked by GMV Max ad spend. Defaults to 50; maximum is 100."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"videos":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string","description":"Creator video id, the videoId the video tools take."},"creatorVideoPhotoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the video’s cover image. Null when Euka has none."},"creatorId":{"type":"string","description":"Creator’s Euka id, the creatorId get_creator_profile takes."},"creatorHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s TikTok handle, without the @. Null when unknown."},"creatorProfilePicUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the creator’s profile picture; it may not load when Euka has no copy of it."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime revenue attributed to the creator video to date, in the shop’s currency."},"postedDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator-video posted timestamp."},"viewsCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok views of the creator video to date."},"likesCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok likes of the creator video to date."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"productTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title of the shop product tagged in the video. Null when it tags none of the shop’s products."},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Shop product id of the shop product tagged in the video. Null when it tags none of the shop’s products."},"productPhotoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of that product’s image; it may not load when Euka has no copy of it. Null when productId is null."},"sparkCodes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Spark codes recorded for the video in this shop, newest first; empty when none."},"usageRightsRequestId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The brand's usage rights request for the video: the one behind its live license, otherwise its latest open request."},"gmvMaxCost":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV Max ad spend on the video over the trailing year, in gmvMaxCurrency. Like every GMV Max field here, it comes from the video’s highest-ROI campaign, not a total across campaigns. Null when no GMV Max report covers the video."},"gmvMaxCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Currency of the GMV Max amounts: the ad account’s billing currency. Null when unknown."},"gmvMaxRoi":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ROI TikTok reported for the video’s highest-ROI GMV Max campaign: paid and organic sales divided by ad spend."},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product clicks from the video’s ads in its highest-ROI GMV Max campaign, trailing year."},"adConversionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad conversion rate TikTok reported for that campaign (orders divided by ad clicks), as a percentage from 0 to 100."},"costPerOrder":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad spend per ad order for that campaign, in gmvMaxCurrency."},"gmvOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Orders TikTok attributed to that campaign’s ads for the video."},"gmvGrossRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Gross revenue TikTok reported for that campaign’s ads for the video, in gmvMaxCurrency."},"adItemsSoldCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the video’s items sold because of ads: productClicks × adConversionRate, capped at its lifetime items sold. Can be fractional."},"adRoi":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of adSales divided by gmvMaxCost."},"adSalesPct":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the share of the video’s lifetime items sold that came from ads, as a ratio from 0 to 1."},"adSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s estimate of the video’s lifetime revenue that came from ads (revenue × adSalesPct), in the shop’s currency."},"acos":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad cost per ad-driven item: gmvMaxCost divided by adItemsSoldCount, in gmvMaxCurrency."},"adReportSynced":{"type":"boolean","description":"Whether a GMV Max report covers the video. When false, the GMV Max fields and ad estimates are null."}},"required":["videoId","creatorVideoPhotoUrl","creatorId","creatorHandle","creatorProfilePicUrl","revenue","postedDate","viewsCount","likesCount","description","productTitle","productId","productPhotoUrl","sparkCodes","usageRightsRequestId","gmvMaxCost","gmvMaxRoi","productClicks","adConversionRate","costPerOrder","gmvOrders","gmvGrossRevenue","adItemsSoldCount","adRoi","adSalesPct","adSales","acos","adReportSynced"],"additionalProperties":{}},"description":"Creator videos posted in the selected dates, highest-ranked first, at most limit."},"page":{"type":"number","description":"Always 1: the ranking returns a single page."},"pageSize":{"type":"number","description":"The limit requested."}},"required":["videos","page","pageSize"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/content-overview":{"post":{"operationId":"getDashboardContentOverview","summary":"Content overview","description":"Read posted videos and engagement trends at the requested interval. Product and creator filters apply to every metric; campaign filters apply to video counts.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"creatorScope":{"anyOf":[{"type":"object","properties":{"type":{"const":"all"}},"required":["type"],"description":"Include all creators."},{"type":"object","properties":{"type":{"const":"l3plus"}},"required":["type"],"description":"Include L3+ creators."},{"type":"object","properties":{"type":{"const":"discord"}},"required":["type"],"description":"Include creators linked through Discord."},{"type":"object","properties":{"type":{"const":"list"},"listId":{"type":"string","description":"Creator list id to include."}},"required":["type","listId"],"description":"Include creators from a creator list."},{"type":"object","properties":{"type":{"const":"segment"},"segmentId":{"type":"string","description":"Creator segment id to include."}},"required":["type","segmentId"],"description":"Include creators from a creator segment."}],"description":"Creator cohort. Defaults to All Creators."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."},"granularity":{"enum":["daily","weekly","monthly"],"type":"string","default":"monthly","description":"Trend bucket size for the content overview series."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"totals":{"type":"object","properties":{"videos":{"type":"number","description":"Creator videos attributed by posted date."},"views":{"type":"number","description":"Views attributed by engagement date."},"likes":{"type":"number","description":"Likes attributed by engagement date."},"comments":{"type":"number","description":"Comments attributed by engagement date."}},"required":["videos","views","likes","comments"],"additionalProperties":{},"description":"Totals for the selected dates: videos by posted date; views, likes and comments by the date they accrued."},"monthly":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"Trend bucket label."},"tiktok":{"type":"number","description":"Videos posted in the bucket."},"views":{"type":"number","description":"Views accrued in the bucket."},"likes":{"type":"number","description":"Likes accrued in the bucket."},"comments":{"type":"number","description":"Comments accrued in the bucket."}},"required":["month","tiktok","views","likes","comments"],"additionalProperties":{}},"description":"Trend buckets at the requested granularity."},"previous":{"anyOf":[{"type":"object","properties":{"totals":{"type":"object","properties":{"videos":{"type":"number","description":"Creator videos attributed by posted date."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Views attributed by engagement date; null when the compared period starts before the seller’s first engagement day."},"likes":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Likes attributed by engagement date; null when views is null."},"comments":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Comments attributed by engagement date; null when views is null."}},"required":["videos","views","likes","comments"],"description":"Totals for the compared period."},"monthly":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"Trend bucket label."},"tiktok":{"type":"number","description":"Videos posted in the bucket."},"views":{"type":"number","description":"Views accrued in the bucket."},"likes":{"type":"number","description":"Likes accrued in the bucket."},"comments":{"type":"number","description":"Comments accrued in the bucket."}},"required":["month","tiktok","views","likes","comments"],"additionalProperties":{}},"description":"Trend buckets of the compared period at the requested granularity, oldest first; the n-th bucket pairs with the n-th selected bucket."}},"required":["totals","monthly"]},{"type":"null"}],"default":null,"description":"The compared period (compareTo; by default the immediately preceding period of equal length). Null with no comparison."}},"required":["totals","monthly"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/creator-level-breakdown":{"post":{"operationId":"getDashboardCreatorLevelBreakdown","summary":"Creator level breakdown","description":"Count creators by their current 30-day platform-wide TikTok Shop GMV level using video, outreach, and sample activity in the selected period, and split each level's GMV into video, LIVE, and Showcase. The All Products, All Campaigns view also includes creators with TikTok Shop Affiliate GMV activity. The split exists only in that view: product or campaign filters leave it null. It does not add up to totalGmv, because TikTok does not split out every sale.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"creatorScope":{"anyOf":[{"type":"object","properties":{"type":{"const":"all"}},"required":["type"],"description":"Include all creators."},{"type":"object","properties":{"type":{"const":"l3plus"}},"required":["type"],"description":"Include L3+ creators."},{"type":"object","properties":{"type":{"const":"discord"}},"required":["type"],"description":"Include creators linked through Discord."},{"type":"object","properties":{"type":{"const":"list"},"listId":{"type":"string","description":"Creator list id to include."}},"required":["type","listId"],"description":"Include creators from a creator list."},{"type":"object","properties":{"type":{"const":"segment"},"segmentId":{"type":"string","description":"Creator segment id to include."}},"required":["type","segmentId"],"description":"Include creators from a creator segment."}],"description":"Creator cohort. Defaults to All Creators."},"campaignType":{"type":"string"}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"tier":{"type":"string","description":"Creator's current 30-day platform GMV tier, L1 through L7."},"range":{"type":"string","description":"Platform GMV range represented by the tier."},"creators":{"type":"number","description":"Distinct creators with video, outreach, or sample activity in the period; the All Products, All Campaigns view also includes creators with TikTok Shop Affiliate GMV activity."},"activeCreators":{"type":"number","description":"Distinct creators who posted a video in the period."},"videoCreators":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distinct creators with video GMV in the period. Null under product or campaign filters."},"liveCreators":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distinct creators with LIVE GMV in the period. Null under product or campaign filters."},"invitesSent":{"type":"number","description":"Target Collaboration invites and Open Collaboration messages sent."},"videos":{"type":"number","description":"Creator videos posted in the period."},"totalGmv":{"type":"number","description":"TikTok Shop Affiliate GMV, or creator-video attributed revenue when product or campaign filters are active."},"videoGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Affiliate GMV from videos. Null under product or campaign filters."},"liveGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Affiliate GMV from LIVEs. Null under product or campaign filters."},"showcaseGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Affiliate GMV from Showcase. Null under product or campaign filters."},"sampleRequests":{"type":"number","description":"Sample requests created in the period."},"samplesApproved":{"type":"number","description":"Requests created in the period that have reached approval or a later stage."},"samplesDelivered":{"type":"number","description":"Sample requests shipped in the period."},"samplesPosted":{"type":"number","description":"Period-created requests whose current status is Completed."}},"required":["tier","range","creators","activeCreators","videoCreators","liveCreators","invitesSent","videos","totalGmv","videoGmv","liveGmv","showcaseGmv","sampleRequests","samplesApproved","samplesDelivered","samplesPosted"],"additionalProperties":{}},"description":"Seven rows, L1 through L7, each totaling the selected period’s activity of creators at that level."},"unavailableUnderFilter":{"type":"boolean","description":"Indicates that product or campaign filters are active and the video, LIVE, and Showcase figures are available in the All Products, All Campaigns view."}},"required":["tiers"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/creator-outreach-funnel":{"post":{"operationId":"getDashboardCreatorOutreachFunnel","summary":"Creator outreach funnel","description":"Read creators at each outreach stage: Contacted, Requested Samples, Received Samples, Posted Content, and Drove Sales, with prior-period and conversion rates.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive Dashboard dates using startDate/endDate. The event follows the metric: video publication, sample request creation, or sales/ad reporting. Euka activity uses America/Los_Angeles calendar days; provider metrics retain their reporting dates. For last N days, start is N minus 1 calendar days before end."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Dashboard outreach campaign ids. Defaults to All Campaigns."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop seller product ids. Defaults to All Products."},"creatorScope":{"anyOf":[{"type":"object","properties":{"type":{"const":"all"}},"required":["type"],"description":"Include all creators."},{"type":"object","properties":{"type":{"const":"l3plus"}},"required":["type"],"description":"Include L3+ creators."},{"type":"object","properties":{"type":{"const":"discord"}},"required":["type"],"description":"Include creators linked through Discord."},{"type":"object","properties":{"type":{"const":"list"},"listId":{"type":"string","description":"Creator list id to include."}},"required":["type","listId"],"description":"Include creators from a creator list."},{"type":"object","properties":{"type":{"const":"segment"},"segmentId":{"type":"string","description":"Creator segment id to include."}},"required":["type","segmentId"],"description":"Include creators from a creator segment."}],"description":"Creator cohort. Defaults to All Creators."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"stages":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable stage key."},"label":{"type":"string","description":"Dashboard stage label."},"icon":{"type":"string","description":"Dashboard icon key."},"value":{"type":"number","description":"Unique creators at the stage."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percentage change from the compared period (compareTo; by default the immediately preceding period of equal length)."},"previousValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The same metric for the compared period. Null with no comparison, or when the compared period has no data."},"pctOfFirst":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Stage value divided by Contacted creators, expressed as a percentage from 0 to 100."},"convFromPrev":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Stage value divided by the preceding stage, expressed as a percentage from 0 to 100."}},"required":["key","label","icon","value","delta","pctOfFirst","convFromPrev"],"additionalProperties":{}},"description":"The five outreach stages in order: Contacted, Requested Samples, Received Samples, Posted Content, and Drove Sales, each counting unique creators in the selected period."}},"required":["stages"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/products-performance":{"post":{"operationId":"getDashboardProductsPerformance","summary":"Products performance","description":"Read TikTok Shop Product Analytics, current available inventory per product and per SKU, and Euka creator activity for each product in the selected sales period. Product Analytics includes all-channel traffic, add-to-cart, unique visitor, refund/tax/shipping metrics, GMV by channel, affiliate orders and clicks, and optional single-channel scoping via channel. When channel is set to a single channel, shared sales/traffic/unique-visitor/content fields reflect that channel, all-channel-only tax/shipping/refund fields are null, and named channel fields (affiliate*, seller*Gmv) retain their named channel values; unfiltered single-channel views scan up to the top 500 products by all-channel GMV (see channelScanTruncated).","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"productIds":{"type":"array","items":{"type":"string"},"description":"Only these TikTok Shop seller product ids, up to 50. Omitted: every product."},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive TikTok Shop sales reporting date range."},"pageSize":{"type":"number","default":10,"description":"Products per page. Defaults to 10; maximum 100."},"pageToken":{"type":"string","description":"Pagination cursor from a previous response."},"sortField":{"enum":["gmv","items_sold","orders"],"type":"string","default":"gmv","description":"Field to sort products by."},"sortOrder":{"enum":["ASC","DESC"],"type":"string","default":"DESC","description":"Sort direction."},"channel":{"enum":["all","sellerLive","sellerVideo","sellerProductCard","affiliate","affiliateLive","affiliateVideo","shopTab"],"type":"string","description":"Traffic channel to read and sort by. Defaults to 'all' for all-channel totals; picking a specific channel scopes shared sales, traffic, unique-visitor, and content metrics to that channel, nulls all-channel-only tax/shipping/refund fields, keeps named channel fields (affiliate*, seller*Gmv) as-is, and scans up to the top 500 products by all-channel GMV when unfiltered (channelScanTruncated indicates when more products exist)."},"includeChannels":{"type":"boolean","description":"When true, each returned product includes the 7-channel breakdown in channels (used for exports). Defaults to false."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period the per-product compared values come from. Omitted: no comparison."}},"required":["brandId","postedDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","description":"TikTok Shop product id. Pass it to productPerformanceDetail."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title. Null when Euka has no record of it."},"totalGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Product Analytics GMV for the product (all-channel, or the requested channel when channel is not all)."},"refundRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"All-channel Refunds divided by GMV for the product, expressed as a ratio from 0 to 1 when both values share a currency and GMV is positive. Null in single-channel views."},"affiliateGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV attributed to the affiliate channel for the product."},"affiliateOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Orders TikTok attributes to the affiliate channel for the product. Divided by affiliateProductClicks, it is the affiliate click-to-order rate."},"affiliateProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Product clicks TikTok attributes to the affiliate channel for the product, from every affiliate source, so it can be more than affiliateVideoProductClicks plus affiliateLiveProductClicks."},"affiliateVideoProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Product clicks from creators' videos for the product (Creator video in Seller Center)."},"affiliateLiveProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Product clicks from creators' LIVEs for the product (Creator LIVE in Seller Center)."},"sellerLiveGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Product Analytics seller LIVE GMV for the product."},"sellerVideoGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Product Analytics seller video GMV for the product."},"sellerProductCardGmv":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Product Analytics seller product-card GMV for the product."},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"All-channel items sold for the product."},"availableQuantity":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Current units available for ordering across every SKU and warehouse for the product. This point-in-time value is independent of the selected reporting range."},"skus":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"skuId":{"type":"string","description":"TikTok Shop SKU id. Pass it to skuPerformanceDetail."},"sellerSku":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The seller's own SKU code. Stock that several listings share is reported under each listing's SKU; group by sellerSku to count it once."},"salesAttributes":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Attribute name, such as Flavor."},"value":{"type":"string","description":"Attribute value, such as Strawberry."}},"required":["name","value"]}},{"type":"null"}],"description":"Variant attributes that distinguish this SKU. Null for a single-SKU product and when TikTok product details are unavailable."},"availableQuantity":{"type":"number","description":"Current units of this SKU available for ordering across every warehouse."}},"required":["skuId","sellerSku","salesAttributes","availableQuantity"]}},{"type":"null"}],"default":null,"description":"Current available stock for each of the product's SKUs, from the same snapshot as availableQuantity. Null when inventory is unavailable."},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"All-channel checkout orders for the product."},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"All-channel SKU orders for the product."},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product Analytics funnel impressions for the product."},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product Analytics click-through rate."},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product Analytics click-to-SKU-order rate."},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Product Analytics average SKU order value."},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"gmvInclTax":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"tax":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"shippingFees":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refunds":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refundedItems":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refundCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."},"channels":{"anyOf":[{"type":"object","properties":{"sellerLive":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"sellerVideo":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"sellerProductCard":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"affiliate":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"affiliateLive":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"affiliateVideo":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}},"shopTab":{"type":"object","properties":{"gmv":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Creator-posted content count TikTok reports on the affiliate channel for the selected period (from avg_daily_creator_posted_content, which returns an integer period sum rather than a per-day average)."}}}},"required":["sellerLive","sellerVideo","sellerProductCard","affiliate","affiliateLive","affiliateVideo","shopTab"]},{"type":"null"}],"default":null},"invitesSent":{"type":"number","description":"Target Collaboration invites linked to the product."},"samplesRequested":{"type":"number","description":"Sample requests created for the product in the range."},"samplesShipped":{"type":"number","description":"Sample requests shipped for the product in the range."},"videosPosted":{"type":"number","description":"Creator videos posted for the product in the range."},"compared":{"anyOf":[{"type":"object","properties":{"totalGmv":{"anyOf":[{"type":"number"},{"type":"null"}]},"refundRate":{"anyOf":[{"type":"number"},{"type":"null"}]},"affiliateGmv":{"anyOf":[{"type":"number"},{"type":"null"}]},"affiliateOrders":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"affiliateProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"affiliateVideoProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"affiliateLiveProductClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"sellerLiveGmv":{"anyOf":[{"type":"number"},{"type":"null"}]},"sellerVideoGmv":{"anyOf":[{"type":"number"},{"type":"null"}]},"sellerProductCardGmv":{"anyOf":[{"type":"number"},{"type":"null"}]},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}]},"orders":{"anyOf":[{"type":"number"},{"type":"null"}]},"skuOrders":{"anyOf":[{"type":"number"},{"type":"null"}]},"productImpressions":{"anyOf":[{"type":"number"},{"type":"null"}]},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}]},"ctor":{"anyOf":[{"type":"number"},{"type":"null"}]},"averageSkuOrderValue":{"anyOf":[{"type":"number"},{"type":"null"}]},"productClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"estimatedCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueProductImpressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueClicks":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtr":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"addToCartUsers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueAddToCartRate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"uniqueCtor":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"gmvInclTax":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"tax":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"shippingFees":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refunds":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refundedItems":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"refundCustomers":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newLiveCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"newVideoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"creatorPosts":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"invitesSent":{"anyOf":[{"type":"number"},{"type":"null"}]},"samplesRequested":{"anyOf":[{"type":"number"},{"type":"null"}]},"samplesShipped":{"anyOf":[{"type":"number"},{"type":"null"}]},"videosPosted":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["totalGmv","refundRate","affiliateGmv","sellerLiveGmv","sellerVideoGmv","sellerProductCardGmv","itemsSold","orders","skuOrders","productImpressions","ctr","ctor","averageSkuOrderValue","invitesSent","samplesRequested","samplesShipped","videosPosted"]},{"type":"null"}],"default":null,"description":"The same metrics for the compared period (compareTo), in currency. Null with no comparison, when the compared dates are older than TikTok keeps product data, or when TikTok reports nothing for the product in the compared period. Inventory is a current snapshot and has no compared value."}},"required":["productId","title","totalGmv","affiliateGmv","sellerLiveGmv","sellerVideoGmv","sellerProductCardGmv","itemsSold","orders","skuOrders","productImpressions","ctr","ctor","averageSkuOrderValue","invitesSent","samplesRequested","samplesShipped","videosPosted"],"additionalProperties":{}},"description":"This page of products, sorted by sortField. Amounts are in currency."},"nextPageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor for the next page."},"totalCount":{"type":"number","description":"Products available for the reporting range."},"latestAvailableDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Product Analytics' latest ready reporting date."},"inventoryAsOf":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Time the current inventory snapshot was retrieved."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Shared currency across the returned monetary fields."},"comparedBeforeRetention":{"type":"boolean","default":false,"description":"True when the compared period starts before the 178 days TikTok keeps product data, so every compared value is null."},"channelScanTruncated":{"type":"boolean","default":false,"description":"True when an unfiltered single-channel view stopped after scanning the top 500 products by all-channel GMV and TikTok reported more products, so totalCount, sorting, and rows cover only that top-500 subset."}},"required":["products","nextPageToken","totalCount","latestAvailableDate","currency"],"additionalProperties":{}}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/product-performance-detail":{"post":{"operationId":"getDashboardProductPerformanceDetail","summary":"Product performance detail","description":"Read one product's daily all-channel GMV, orders, items sold, sales channels, return outcomes, currency, and latest available reporting date.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"productId":{"type":"string","description":"TikTok Shop seller product id to inspect."},"salesDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive TikTok Shop sales reporting date range."}},"required":["brandId","productId","salesDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","description":"The TikTok Shop product id requested."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Currency for monetary fields."},"latestAvailableDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Product Analytics' latest ready reporting date."},"effectiveRange":{"anyOf":[{"type":"object","properties":{"start":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"end":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["start","end"]},{"type":"null"}],"description":"Part of the requested range with available TikTok Product Analytics data."},"summary":{"type":"object","properties":{"gmv":{"type":"number","description":"All-channel GMV for the effective range."},"orders":{"type":"number","description":"Checkout orders for the effective range."},"itemsSold":{"type":"number","description":"Items sold for the effective range."},"returned":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Returned items."},"canceled":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Canceled items."},"refunded":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Refunded items."},"replacements":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Replacement items."}},"required":["gmv","orders","itemsSold","returned","canceled","refunded","replacements"],"description":"Totals over effectiveRange, amounts in currency."},"channelBreakdown":{"type":"array","items":{"type":"object","properties":{"contentType":{"enum":["VIDEO","LIVE","PRODUCT_CARD"],"type":"string","description":"Sales channel: VIDEO (shoppable videos), LIVE (LIVE streams), or PRODUCT_CARD (the product card, outside videos and LIVE)."},"gmv":{"type":"number","description":"GMV attributed to the content type."},"itemsSold":{"type":"number","description":"Items sold through the content type."}},"required":["contentType","gmv","itemsSold"]},"description":"GMV and items sold by sales channel over effectiveRange, always one row each for VIDEO, LIVE, and PRODUCT_CARD."},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Shop reporting date."},"gmv":{"type":"number","description":"All-channel GMV for the date."},"orders":{"type":"number","description":"Checkout orders for the date."},"itemsSold":{"type":"number","description":"Items sold for the date."}},"required":["date","gmv","orders","itemsSold"]},"description":"One row per date from the effective range start through the latest available date; a date without sales is zero."}},"required":["productId","currency","latestAvailableDate","effectiveRange","summary","channelBreakdown","daily"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/sku-performance-detail":{"post":{"operationId":"getDashboardSkuPerformanceDetail","summary":"SKU performance detail","description":"Read one SKU's daily all-channel GMV, items sold, and SKU orders, with sales channels, currency, and latest available reporting date. Get skuId from productsPerformance skus. SKU orders count every order that includes the SKU, so an order with two SKUs counts once for each and SKU orders do not add up to checkout orders.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"skuId":{"type":"string","description":"TikTok Shop SKU id from productsPerformance skus."},"salesDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["startDate","endDate"],"description":"Inclusive TikTok Shop sales reporting date range."}},"required":["brandId","skuId","salesDateRange"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"skuId":{"type":"string","description":"The TikTok Shop SKU id requested."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Currency for monetary fields."},"latestAvailableDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Product Analytics' latest ready reporting date."},"effectiveRange":{"anyOf":[{"type":"object","properties":{"start":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"end":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."}},"required":["start","end"]},{"type":"null"}],"description":"Part of the requested range with available TikTok Product Analytics data."},"summary":{"type":"object","properties":{"gmv":{"type":"number","description":"All-channel GMV for the effective range."},"itemsSold":{"type":"number","description":"Items sold for the effective range."},"skuOrders":{"type":"number","description":"Orders that include the SKU, for the effective range."}},"required":["gmv","itemsSold","skuOrders"],"description":"Totals over effectiveRange, amounts in currency."},"channelBreakdown":{"type":"array","items":{"type":"object","properties":{"contentType":{"enum":["VIDEO","LIVE","PRODUCT_CARD"],"type":"string","description":"Sales channel: VIDEO (shoppable videos), LIVE (LIVE streams), or PRODUCT_CARD (the product card, outside videos and LIVE)."},"gmv":{"type":"number","description":"GMV attributed to the content type."},"itemsSold":{"type":"number","description":"Items sold through the content type."}},"required":["contentType","gmv","itemsSold"]},"description":"GMV and items sold by sales channel over effectiveRange, always one row each for VIDEO, LIVE, and PRODUCT_CARD."},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Shop reporting date."},"gmv":{"type":"number","description":"All-channel GMV for the date."},"itemsSold":{"type":"number","description":"Items sold for the date."},"skuOrders":{"type":"number","description":"Orders that include the SKU."}},"required":["date","gmv","itemsSold","skuOrders"]},"description":"One row per date from the effective range start through the latest available date; a date without sales is zero."}},"required":["skuId","currency","latestAvailableDate","effectiveRange","summary","channelBreakdown","daily"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/shop-health":{"post":{"operationId":"getDashboardShopHealth","summary":"Shop health","description":"Read the shop's current TikTok Shop Performance Score (SPS): overall score out of 5, tier, peer percentile, weighted dimension scores, and top issues. US-region shops only; the score uses TikTok's own evaluation window and is independent of Dashboard date filters.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."}},"required":["brandId"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unavailableReason":{"anyOf":[{"enum":["NOT_CONNECTED","UNSUPPORTED_REGION","NOT_SCORED","FETCH_FAILED"],"type":"string"},{"type":"null"}],"description":"Null when a score is available. Otherwise: shop not connected, non-US region, not enough recent orders to be scored, or the SPS request failed."},"spsScore":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok Shop Performance Score from 0 to 5, one decimal place."},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SPS tier: EXCELLENT, GOOD, POOR, CRITICAL, or NIL."},"tierText":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized tier label."},"peerPercentile":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The shop's percentile among peer shops, from 0 to 100."},"primaryCategoryName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The shop's primary category name."},"dimensions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Dimension name, e.g. \"Product satisfaction\"."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Dimension score from 0 to 5."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"EXCELLENT, GOOD, POOR, CRITICAL, or NIL."},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Dimension weight as a percent from 0 to 100. Weights vary per shop; always render the returned value."}},"required":["name","score","status","weight"]},"description":"Weighted SPS dimension scores."},"topIssueSummary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localized summary of the top SPS issues."},"topIssues":{"type":"array","items":{"type":"string"},"description":"Localized descriptions of the SPS issues contributing to the current score, ranked with the top issue first."},"updateTime":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Latest score refresh time as a Unix timestamp in seconds."}},"required":["unavailableReason","spsScore","tier","tierText","peerPercentile","primaryCategoryName","dimensions","topIssueSummary","topIssues","updateTime"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/affiliate-orders":{"post":{"operationId":"getDashboardAffiliateOrders","summary":"Affiliate orders","description":"List TikTok Shop affiliate orders created in the date range (the data behind Affiliate Center > Transactions > Affiliate orders). Each order lists its SKUs with product, creator, content type, settlement status, commission base, and the Standard, Shop Ads, and partner commission rates with estimated and actual amounts. Shops whose orders Euka stores (source \"stored\", refreshed daily) also get each line's commissionType, the organic / ads / partner split, and the commissionType and groupBy inputs; other shops are read live. Standard does not mean organic: without a Shop Ads rate, ad-driven orders are paid at Standard. Actual amounts are null until the SKU settles. Returns one page: pass nextPageToken with the same filters, and check totalCount before paging a large range. For the commission total, read affiliateCommission in the Performance overview. US-region shops only; at most three months per request.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD format."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD format."},"pageSize":{"type":"number","default":20,"description":"Orders per page. Defaults to 20; maximum 100."},"pageToken":{"type":"string","description":"Pagination cursor from a previous response."},"commissionType":{"enum":["STANDARD","SHOP_ADS","PARTNER"],"type":"string","description":"Only lines paid at this rate. Stored orders only."},"groupBy":{"enum":["creator","video","product"],"type":"string","description":"Return one row per creator, video or product with sales by type, largest first, instead of orders. Stored orders only."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string","description":"TikTok Shop order id."},"createdAt":{"type":"string","description":"Order creation time."},"skus":{"type":"array","items":{"type":"object","properties":{"skuId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Shop SKU id."},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Shop product id."},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"SKU quantity in the order."},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"SKU selling price."},"creatorUsername":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Username of the creator credited with the order."},"contentType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Content that produced the order, e.g. VIDEO, LIVE, SHOP, LINKSHARE."},"contentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok content id."},"settlementStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok settlement status, e.g. awaiting payment, to settle, SETTLED, INELIGIBLE (returned, refunded, or canceled)."},"standardCommissionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percent, e.g. 15.5 for 15.50%. Null when the seller set no such rate; on a stored read (source \"stored\") only the rate the line was paid at is set."},"shopAdsCommissionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percent, e.g. 15.5 for 15.50%. Null when the seller set no such rate; on a stored read (source \"stored\") only the rate the line was paid at is set."},"partnerCommissionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Percent, e.g. 15.5 for 15.50%. Null when the seller set no such rate; on a stored read (source \"stored\") only the rate the line was paid at is set."},"estimatedCommissionBase":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Selling price times quantity before refunds: the base commission is calculated on, not buyer payment or GMV."},"actualCommissionBase":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Commission base after returns and refunds. Null until the SKU settles."},"estimatedCommission":{"type":"object","properties":{"standard":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Standard commission paid to the creator."},"shopAds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Shop Ads commission paid to the creator."},"partner":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Commission paid to the affiliate partner."}},"required":["standard","shopAds","partner"],"description":"Amounts by commission type. Null when the type does not apply."},"actualCommission":{"type":"object","properties":{"standard":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Standard commission paid to the creator."},"shopAds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Shop Ads commission paid to the creator."},"partner":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Commission paid to the affiliate partner."}},"required":["standard","shopAds","partner"],"description":"Settled amounts by commission type. Null until the SKU settles."},"commissionType":{"anyOf":[{"enum":["STANDARD","SHOP_ADS","PARTNER"],"type":"string","description":"The rate TikTok paid the line at."},{"type":"null"}],"description":"The one rate TikTok paid the line at; null when it reports none or more than one."},"commissionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The rate of commissionType, in percent. Null when the line has no type."}},"required":["skuId","productId","quantity","price","creatorUsername","contentType","contentId","settlementStatus","standardCommissionRate","shopAdsCommissionRate","partnerCommissionRate","estimatedCommissionBase","actualCommissionBase","estimatedCommission","actualCommission","commissionType","commissionRate"]},"description":"The order’s affiliate SKU lines."}},"required":["orderId","createdAt","skus"]},"description":"One page of affiliate orders created in the date range, in TikTok’s order."},"nextPageToken":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor for the next page."},"totalCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's total_count for the date range, which TikTok defines as SKU orders. A stored read sends it on the first page only and null on later pages."},"currency":{"const":"USD","description":"Currency of every amount."},"source":{"enum":["stored","live"],"type":"string","description":"stored: read from the orders Euka stores daily, limited to coverage; live: read from TikTok, page by page. The type filter, split and groups need stored."},"coverage":{"anyOf":[{"type":"object","properties":{"from":{"type":"string","description":"First GMT-8 day whose orders are stored."},"through":{"type":"string","description":"Last GMT-8 day whose orders are stored."},"updatedAt":{"type":"string","description":"When the stored orders were last refreshed."},"historyLoading":{"type":"boolean","description":"True while Euka is still loading the three months before `through`."}},"required":["from","through","updatedAt","historyLoading"]},{"type":"null"}],"description":"Which days the stored read covers; null on a live read. Days outside it return no orders."},"split":{"anyOf":[{"type":"object","properties":{"standard":{"type":"object","properties":{"sales":{"type":"number","description":"Est. commission base: selling price times quantity before refunds."},"orders":{"type":"number","description":"Orders with at least one line of this type."},"lines":{"type":"number","description":"SKU lines of this type."},"estimatedCommission":{"type":"number","description":"Estimated commission on these lines."}},"required":["sales","orders","lines","estimatedCommission"]},"shopAds":{"type":"object","properties":{"sales":{"type":"number","description":"Est. commission base: selling price times quantity before refunds."},"orders":{"type":"number","description":"Orders with at least one line of this type."},"lines":{"type":"number","description":"SKU lines of this type."},"estimatedCommission":{"type":"number","description":"Estimated commission on these lines."}},"required":["sales","orders","lines","estimatedCommission"]},"partner":{"type":"object","properties":{"sales":{"type":"number","description":"Est. commission base: selling price times quantity before refunds."},"orders":{"type":"number","description":"Orders with at least one line of this type."},"lines":{"type":"number","description":"SKU lines of this type."},"estimatedCommission":{"type":"number","description":"Estimated commission on these lines."}},"required":["sales","orders","lines","estimatedCommission"]},"untypedLines":{"type":"number","description":"Lines with no single rate, left out of the three parts."}},"required":["standard","shopAds","partner","untypedLines"]},{"type":"null"}],"description":"Sales, orders and commission by the rate TikTok paid, over the whole date range and ignoring commissionType. Sent on the first page only; null on later pages and on a live read."},"groups":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"creatorUsername":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The creator; on a video row, the creator credited with it."},"contentType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"VIDEO, LIVE, SHOP and so on."},"contentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok content id of a video row."},"productId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok Shop product id of a product row."},"orders":{"type":"number","description":"Orders in the group."},"sales":{"type":"number","description":"Est. commission base of every line in the group."},"salesByType":{"type":"object","properties":{"standard":{"type":"number","description":"Est. commission base paid at the Standard rate."},"shopAds":{"type":"number","description":"Est. commission base paid at the Shop Ads rate."},"partner":{"type":"number","description":"Est. commission base paid at a Partner rate."}},"required":["standard","shopAds","partner"]},"estimatedCommission":{"type":"number","description":"Estimated commission on every line in the group."}},"required":["creatorUsername","contentType","contentId","productId","orders","sales","salesByType","estimatedCommission"]}},{"type":"null"}],"description":"One page of groups when groupBy is set; then orders is empty. Null otherwise."}},"required":["orders","nextPageToken","totalCount","currency","source","coverage","split","groups"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/creator-retention/summary":{"post":{"operationId":"getDashboardCreatorRetentionSummary","summary":"Creator retention summary","description":"Read active, new, returning, and churned creators with video, view, revenue, and preceding-period metrics. Dates are inclusive in the America/Los_Angeles analytics timezone.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"tier":{"enum":["all","l3plus"],"type":"string","default":"all","description":"Creator tier. L3+ uses the creator current 30-day platform-wide TikTok Shop GMV tier."},"creatorIds":{"type":"array","items":{"type":"string"},"description":"Optional creator uid_shop allow-list. When provided, it replaces the tier filter."},"productIds":{"type":"array","items":{"type":"string"},"description":"Optional TikTok Shop seller product ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Optional Euka outreach campaign ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"startDate":{"type":"string","description":"Inclusive YYYY-MM-DD date in the America/Los_Angeles analytics timezone."},"endDate":{"type":"string","description":"Inclusive YYYY-MM-DD date in the America/Los_Angeles analytics timezone."},"compareTo":{"anyOf":[{"type":"object","properties":{"type":{"const":"none"}},"required":["type"],"description":"No comparison: previous values and changes are not computed."},{"type":"object","properties":{"type":{"const":"previous_period"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same number of days right before the selected dates."},{"type":"object","properties":{"type":{"const":"same_period_last_year"},"matchDayOfWeek":{"type":"boolean","default":false,"description":"Shift by whole weeks so each compared day falls on the same weekday."}},"required":["type"],"description":"The same dates one year earlier."},{"type":"object","properties":{"type":{"const":"custom"},"startDate":{"type":"string","description":"Inclusive compared start date."},"endDate":{"type":"string","description":"Inclusive compared end date."}},"required":["type","startDate","endDate"],"description":"Any dates, of any length."}],"description":"Period that previous values and percentage changes compare against. Defaults to previous_period without matchDayOfWeek."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"activeCreators":{"type":"number","description":"Creators who posted at least one seller video in the period."},"newCreators":{"type":"number","description":"Active creators whose first seller video was posted in the period."},"returningCreators":{"type":"number","description":"Active creators who posted a seller video before the period."},"churnedCreators":{"type":"number","description":"Creators active in the preceding equal-length period but not the selected period."},"retentionRate":{"type":"number","description":"Share from 0 to 1 of preceding-period active creators who were also active in the selected period."},"totalVideos":{"type":"number","description":"Creator videos posted in the period."},"convertingVideos":{"type":"number","description":"Creator videos with positive attributed revenue."},"totalRevenue":{"type":"number","description":"TikTok Shop Affiliate GMV for unfiltered reads; creator-video attributed revenue when product or campaign filters are present."},"totalViews":{"type":"number","description":"Current lifetime views on videos posted in the period."},"avgRevenuePerCreator":{"type":"number","description":"totalRevenue divided by activeCreators, in the shop’s currency; 0 when no creator was active."},"avgVideosPerCreator":{"type":"number","description":"totalVideos divided by activeCreators; 0 when no creator was active."}},"required":["activeCreators","newCreators","returningCreators","churnedCreators","retentionRate","totalVideos","convertingVideos","totalRevenue","totalViews","avgRevenuePerCreator","avgVideosPerCreator"],"description":"Metrics for the requested dates."},"previous":{"type":"object","properties":{"activeCreators":{"type":"number","description":"Creators who posted at least one seller video in the period."},"newCreators":{"type":"number","description":"Active creators whose first seller video was posted in the period."},"returningCreators":{"type":"number","description":"Active creators who posted a seller video before the period."},"churnedCreators":{"type":"number","description":"Creators active in the preceding equal-length period but not the selected period."},"retentionRate":{"type":"number","description":"Share from 0 to 1 of preceding-period active creators who were also active in the selected period."},"totalVideos":{"type":"number","description":"Creator videos posted in the period."},"convertingVideos":{"type":"number","description":"Creator videos with positive attributed revenue."},"totalRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"totalRevenue for the compared period; null when it is store GMV and the compared period starts before the seller’s first TikTok Shop performance day."},"totalViews":{"type":"number","description":"Current lifetime views on videos posted in the period."},"avgRevenuePerCreator":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"totalRevenue divided by activeCreators for the compared period; 0 when no creator was active, null when totalRevenue is null."},"avgVideosPerCreator":{"type":"number","description":"totalVideos divided by activeCreators; 0 when no creator was active."}},"required":["activeCreators","newCreators","returningCreators","churnedCreators","retentionRate","totalVideos","convertingVideos","totalRevenue","totalViews","avgRevenuePerCreator","avgVideosPerCreator"],"description":"Metrics for the compared period (compareTo; by default the immediately preceding period of equal length), computed as if it were the selected period: churn and retention measure it against the equal-length period right before it. All zero with no comparison."},"periodDays":{"type":"number","description":"Days in the requested range, counting both ends."}},"required":["current","previous","periodDays"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/creator-retention/activity-over-time":{"post":{"operationId":"getDashboardCreatorRetentionActivityOverTime","summary":"Creator activity over time","description":"Read active, new, and returning creators with video, revenue, and order totals bucketed over an inclusive date range. Product and campaign filters select creators with matching videos in the requested window; the buckets then include all seller-video activity for that resolved creator scope.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"tier":{"enum":["all","l3plus"],"type":"string","default":"all","description":"Creator tier. L3+ uses the creator current 30-day platform-wide TikTok Shop GMV tier."},"creatorIds":{"type":"array","items":{"type":"string"},"description":"Optional creator uid_shop allow-list. When provided, it replaces the tier filter."},"productIds":{"type":"array","items":{"type":"string"},"description":"Optional TikTok Shop seller product ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Optional Euka outreach campaign ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"startDate":{"type":"string","description":"Inclusive YYYY-MM-DD date in the America/Los_Angeles analytics timezone."},"endDate":{"type":"string","description":"Inclusive YYYY-MM-DD date in the America/Los_Angeles analytics timezone."},"granularity":{"enum":["daily","weekly","monthly"],"type":"string","default":"weekly","description":"Activity bucket size."}},"required":["brandId","startDate","endDate"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"buckets":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","description":"Bucket start date."},"activeCreators":{"type":"number","description":"Creators who posted at least one seller video in the bucket."},"newCreators":{"type":"number","description":"Active creators whose first seller video was posted in the bucket."},"returningCreators":{"type":"number","description":"Active creators whose first seller video was posted before the bucket."},"videos":{"type":"number","description":"Seller videos posted in the bucket."},"revenue":{"type":"number","description":"Lifetime attributed revenue to date of the creator videos posted in the bucket, in the shop’s currency; not revenue earned during the bucket."},"orders":{"type":"number","description":"Items sold to date through the seller videos posted in the bucket (lifetime items, not orders)."}},"required":["bucket","activeCreators","newCreators","returningCreators","videos","revenue","orders"]},"description":"Activity per bucket, oldest first, by Pacific posting date; weekly buckets start on Monday. Buckets with no seller video posted are left out."}},"required":["buckets"]}}}}},"security":[{"openApiKey":[]}]}},"/dashboard/creator-retention/cohort":{"post":{"operationId":"getDashboardCreatorRetentionCohort","summary":"Creator cohort retention","description":"Read monthly creator retention cohorts based on each creator first seller video, with activity through the requested cohort end date. Product and campaign filters select creators with matching videos in the requested window before cohort history is calculated.","tags":["Dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"tier":{"enum":["all","l3plus"],"type":"string","default":"all","description":"Creator tier. L3+ uses the creator current 30-day platform-wide TikTok Shop GMV tier."},"creatorIds":{"type":"array","items":{"type":"string"},"description":"Optional creator uid_shop allow-list. When provided, it replaces the tier filter."},"productIds":{"type":"array","items":{"type":"string"},"description":"Optional TikTok Shop seller product ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"campaignIds":{"type":"array","items":{"type":"number"},"description":"Optional Euka outreach campaign ids. Summary reads apply them to counted videos; activity and cohort reads use them to select creators with matching videos in the requested window."},"cohortStart":{"type":"string","description":"Inclusive lower bound for each creator first-post cohort month."},"cohortEnd":{"type":"string","description":"Inclusive upper bound for each creator first-post cohort month and activity."}},"required":["brandId","cohortStart","cohortEnd"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"cells":{"type":"array","items":{"type":"object","properties":{"cohort":{"type":"string","description":"Month of the creator first seller video."},"monthsSinceCohort":{"type":"number","description":"Months from the cohort month to the activity month; 0 is the cohort month itself."},"cohortSize":{"type":"number","description":"Creators whose first seller video was posted in the cohort month."},"active":{"type":"number","description":"Creators from the cohort who posted a seller video in the activity month."},"rate":{"type":"number","description":"active divided by cohortSize, as a ratio from 0 to 1."}},"required":["cohort","monthsSinceCohort","cohortSize","active","rate"]},"description":"One cell per cohort month and activity month, through the month of cohortEnd, sorted by cohort then monthsSinceCohort. A month in which no cohort creator posted has no cell."}},"required":["cells"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/advertisers":{"get":{"operationId":"listGmvMaxAdvertisers","summary":"List connected ad accounts","description":"Returns the TikTok Ads accounts connected to the brand's TikTok Shop, with their names, currencies and time zones. Pass one as `advertiserId` when the shop runs GMV Max from several accounts in different currencies. Account details are read from TikTok at most once a day.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the brand's TikTok Shop sells in. Null when its market has none Euka knows (GLOBAL or unknown)."},"advertisers":{"type":"array","items":{"type":"object","properties":{"advertiserId":{"type":"string","description":"TikTok Ads advertiser (ad account) id: the advertiserId the other GMV Max tools take."},"advertiserName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the ad account in TikTok. Null when TikTok could not be reached and only the ids saved at connection time are known."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the account's billing currency, which its budgets and spend are in. Null when TikTok did not return it."},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"IANA time zone TikTok counts the account's report days in. Null when TikTok did not return it."},"costLast30Days":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV Max spend Euka holds for the account over the last 30 days, for this brand's shop only, in the account's currency. 0 when it ran none, which for a shop with several accounts usually means the account isn't the one running GMV Max. Null when Euka could not read it just now: unknown, not zero."},"lastSpendDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD, the account's time zone) the account spent on GMV Max for this brand's shop, from Euka's synced history. Null when it never has (the account is connected but runs no GMV Max for this shop), or when costLast30Days is null and it is not known."},"shopRate":{"anyOf":[{"type":"object","properties":{"rate":{"type":"number","description":"Units of shopCurrency one unit of the account's currency buys."},"rateDate":{"type":"string","description":"The ECB rate date, YYYY-MM-DD."}},"required":["rate","rateDate"]},{"type":"null"}],"description":"The European Central Bank's latest rate from the account's currency to the shop's, for a rough equivalent of a budget or threshold, which stays in the account's currency. Null when the account bills in the shop's currency, either is unknown, or the ECB publishes no rate for it."}},"required":["advertiserId","advertiserName","currency","timezone","costLast30Days","lastSpendDate","shopRate"]},"description":"The TikTok Ads accounts connected to the brand's TikTok Shop, highest 30-day GMV Max spend first. Names, currency and time zone are read from TikTok at most once a day."}},"required":["shopCurrency","advertisers"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/overview":{"get":{"operationId":"getGmvMaxOverview","summary":"Shop overview","description":"The shop's GMV Max spend, gross revenue, ROI, orders and cost per order for an inclusive date range, against the previous period, with a daily series and campaign counts. `freshness` says which days come from Euka's daily sync and which were read live.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","description":"First day of the window, YYYY-MM-DD, inclusive, in the ad account time zone (freshness.timezone)."},"allowEmptyValue":true,"allowReserved":true},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","description":"Last day of the window, YYYY-MM-DD, inclusive, in the ad account time zone. At most 365 days from startDate."},"allowEmptyValue":true,"allowReserved":true},{"name":"compare","in":"query","required":false,"schema":{"enum":["previous_period","none"],"type":"string","default":"previous_period","description":"previous_period also returns the same figures for the equally long window just before startDate; none leaves them null."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"currency","in":"query","required":false,"schema":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 code of the currency every money figure in this response is in (cost, grossRevenue, costPerOrder, totals, trends): shopCurrency when the read asked for currency shop and could convert, accountCurrency otherwise."},"accountCurrency":{"type":"string","description":"ISO 4217 code of the ad account's billing currency: what TikTok reports and bills in, and what budgets, Min. spend, alert and rule thresholds and every write tool's amounts are in. Never copy a converted figure into a setting."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"totals":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"The shop's GMV Max totals for the window, Product and LIVE campaigns together."},"accountTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"TikTok's own totals for the window, in accountCurrency: what TikTok Ads Manager shows. Null when money is not converted (totals already are)."},"previousTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"The same totals for previousRange. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"previousRange":{"anyOf":[{"type":"object","properties":{"startDate":{"type":"string","description":"YYYY-MM-DD, inclusive."},"endDate":{"type":"string","description":"YYYY-MM-DD, inclusive."}},"required":["startDate","endDate"]},{"type":"null"}],"description":"The comparison window: as long as the window, ending the day before startDate. Null when compare is none."},"daily":{"type":"array","items":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."},"date":{"type":"string","description":"The day, YYYY-MM-DD in the ad account time zone."}},"required":["cost","grossRevenue","orders","roi","costPerOrder","date"]},"description":"One entry per day of the window, oldest first. A day with no spend has zeros; a day TikTok could not be read for (freshness.liveTail) is left out."},"campaigns":{"type":"object","properties":{"total":{"type":"number","description":"The shop's GMV Max campaigns, on or off."},"enabled":{"type":"number","description":"Campaigns switched on in TikTok."},"withSpend":{"type":"number","description":"Campaigns that spent anything in the window."}},"required":["total","enabled","withSpend"],"description":"Campaign counts, for the overview header."}},"required":["currency","accountCurrency","shopCurrency","exchangeRates","freshness","totals","accountTotals","previousTotals","previousRange","daily","campaigns"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/campaigns":{"get":{"operationId":"listGmvMaxCampaigns","summary":"List GMV Max campaigns","description":"Every GMV Max campaign of the shop with its settings (status, bid strategy, target ROI, daily budget) and its metrics for the date range, against the previous period. Up to 500 rows; `truncated` says when there were more.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","description":"First day of the window, YYYY-MM-DD, inclusive, in the ad account time zone (freshness.timezone)."},"allowEmptyValue":true,"allowReserved":true},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","description":"Last day of the window, YYYY-MM-DD, inclusive, in the ad account time zone. At most 365 days from startDate."},"allowEmptyValue":true,"allowReserved":true},{"name":"compare","in":"query","required":false,"schema":{"enum":["previous_period","none"],"type":"string","default":"previous_period","description":"previous_period also returns the same figures for the equally long window just before startDate; none leaves them null."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"status","in":"query","required":false,"schema":{"enum":["all","enabled","disabled"],"type":"string","default":"all","description":"Only campaigns switched on (enabled) or off (disabled) in TikTok; all lists both."},"allowEmptyValue":true,"allowReserved":true},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Only campaigns whose name or id contains this text, ignoring case."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"enum":["cost","grossRevenue","roi","orders","costPerOrder","name"],"type":"string","default":"cost","description":"Column to sort by. Metrics sort by their window totals."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortDirection","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","description":"desc puts the highest first."},"allowEmptyValue":true,"allowReserved":true},{"name":"currency","in":"query","required":false,"schema":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 code of the currency every money figure in this response is in (cost, grossRevenue, costPerOrder, totals, trends): shopCurrency when the read asked for currency shop and could convert, accountCurrency otherwise."},"accountCurrency":{"type":"string","description":"ISO 4217 code of the ad account's billing currency: what TikTok reports and bills in, and what budgets, Min. spend, alert and rule thresholds and every write tool's amounts are in. Never copy a converted figure into a setting."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"totals":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"Totals for the window across every campaign that matches the filters, including any past the row cap."},"accountTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"TikTok's own totals for the window, in accountCurrency: what TikTok Ads Manager shows. Null when money is not converted (totals already are)."},"previousTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"The same totals for previousRange. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"previousRange":{"anyOf":[{"type":"object","properties":{"startDate":{"type":"string","description":"YYYY-MM-DD, inclusive."},"endDate":{"type":"string","description":"YYYY-MM-DD, inclusive."}},"required":["startDate","endDate"]},{"type":"null"}],"description":"The comparison window: as long as the window, ending the day before startDate. Null when compare is none."},"rows":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string","description":"TikTok GMV Max campaign id: the campaignId the other GMV Max tools take."},"campaignName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name in TikTok Ads Manager. Null when TikTok returned none."},"type":{"anyOf":[{"enum":["product","live"],"type":"string"},{"type":"null"}],"description":"product: Product GMV Max (shop products promoted with videos). live: LIVE GMV Max (LIVE streams). Null when unknown."},"status":{"enum":["enabled","disabled"],"type":"string","description":"Whether the campaign is switched on in TikTok."},"deliveryStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok's detailed delivery status as TikTok spells it, e.g. CAMPAIGN_STATUS_ENABLE (delivering), CAMPAIGN_STATUS_BUDGET_EXCEED (out of budget) or CAMPAIGN_STATUS_DISABLE. Null when unknown."},"bidStrategy":{"anyOf":[{"enum":["roi_target","max_delivery"],"type":"string"},{"type":"null"}],"description":"roi_target: bids to hold roiTarget. max_delivery: spends the daily budget for the most orders, with no ROI target. Null when the settings are unknown."},"roiTarget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Target ROI the campaign bids to: gross revenue ÷ cost, a ratio (3 means 3×). Null unless bidStrategy is roi_target."},"dailyBudget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Daily budget, in accountCurrency (TikTok's own setting, never converted). Null when unknown."},"settingsSource":{"enum":["live","snapshot"],"type":"string","description":"live: the settings were read from TikTok just now. snapshot: they come from Euka's nightly snapshot of settingsAsOf, either because the campaign is switched off (its settings are only read on demand) or because TikTok could not be reached; in the second case editable is false until TikTok answers again."},"settingsAsOf":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Day of the snapshot the settings come from (YYYY-MM-DD) when settingsSource is snapshot. Null when live."},"ownership":{"enum":["verified","unverified"],"type":"string","description":"verified: the campaign belongs to this brand's TikTok Shop. unverified: a new campaign on an ad account the shop shares with other shops, not yet confirmed as this shop's; it is listed but never edited."},"editable":{"type":"boolean","description":"Whether update_gmv_max_campaign and set_gmv_max_campaign_status can change the campaign now."},"notEditableReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why editable is false, in one English sentence. Null when editable."},"budgetUtilization":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Average daily cost over the last 3 complete days ÷ dailyBudget: a ratio (0.9 = 90% of the budget spent). Null without a daily budget or without data for those days."},"modifiedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the campaign's settings last changed in TikTok. Null when unknown."},"metrics":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"Totals for the window."},"previous":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"Totals for the comparison window. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"accountFigures":{"type":"object","properties":{"cost":{"type":"number"},"grossRevenue":{"type":"number"},"previousCost":{"anyOf":[{"type":"number"},{"type":"null"}]},"previousGrossRevenue":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["cost","grossRevenue","previousCost","previousGrossRevenue"],"description":"TikTok's own spend and gross revenue in accountCurrency, for the window and the comparison window (null when compare is none). Present only when money is converted. Adding up several campaigns, take ROI from these: converted figures give a slightly different ratio."},"trend":{"type":"array","items":{"type":"number"},"description":"Cost over the window, oldest first, in `currency`, at most 31 points: one per day for windows up to 31 days, otherwise summed into weekly (or, past about 30 weeks, longer) buckets."}},"required":["campaignId","campaignName","type","status","deliveryStatus","bidStrategy","roiTarget","dailyBudget","settingsSource","settingsAsOf","ownership","editable","notEditableReason","budgetUtilization","modifiedAt","metrics","previous","trend"]},"description":"The campaigns that match the filters, sorted, at most 500. A campaign is listed even when it spent nothing in the window."},"truncated":{"type":"boolean","description":"True when more than 500 campaigns matched and the rest were left out; narrow the list with status or search."}},"required":["currency","accountCurrency","shopCurrency","exchangeRates","freshness","totals","accountTotals","previousTotals","previousRange","rows","truncated"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/campaigns/{campaignId}":{"get":{"operationId":"getGmvMaxCampaign","summary":"Get a GMV Max campaign","description":"One campaign with all of its settings, its totals and daily series for the date range, and its products.","tags":["GMV Max"],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","description":"TikTok GMV Max campaign id from list_gmv_max_campaigns."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","description":"First day of the window, YYYY-MM-DD, inclusive, in the ad account time zone (freshness.timezone)."},"allowEmptyValue":true,"allowReserved":true},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","description":"Last day of the window, YYYY-MM-DD, inclusive, in the ad account time zone. At most 365 days from startDate."},"allowEmptyValue":true,"allowReserved":true},{"name":"compare","in":"query","required":false,"schema":{"enum":["previous_period","none"],"type":"string","default":"previous_period","description":"previous_period also returns the same figures for the equally long window just before startDate; none leaves them null."},"allowEmptyValue":true,"allowReserved":true},{"name":"currency","in":"query","required":false,"schema":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 code of the currency every money figure in this response is in (cost, grossRevenue, costPerOrder, totals, trends): shopCurrency when the read asked for currency shop and could convert, accountCurrency otherwise."},"accountCurrency":{"type":"string","description":"ISO 4217 code of the ad account's billing currency: what TikTok reports and bills in, and what budgets, Min. spend, alert and rule thresholds and every write tool's amounts are in. Never copy a converted figure into a setting."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"campaign":{"type":"object","properties":{"campaignId":{"type":"string","description":"TikTok GMV Max campaign id: the campaignId the other GMV Max tools take."},"campaignName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name in TikTok Ads Manager. Null when TikTok returned none."},"type":{"anyOf":[{"enum":["product","live"],"type":"string"},{"type":"null"}],"description":"product: Product GMV Max (shop products promoted with videos). live: LIVE GMV Max (LIVE streams). Null when unknown."},"status":{"enum":["enabled","disabled"],"type":"string","description":"Whether the campaign is switched on in TikTok."},"deliveryStatus":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok's detailed delivery status as TikTok spells it, e.g. CAMPAIGN_STATUS_ENABLE (delivering), CAMPAIGN_STATUS_BUDGET_EXCEED (out of budget) or CAMPAIGN_STATUS_DISABLE. Null when unknown."},"bidStrategy":{"anyOf":[{"enum":["roi_target","max_delivery"],"type":"string"},{"type":"null"}],"description":"roi_target: bids to hold roiTarget. max_delivery: spends the daily budget for the most orders, with no ROI target. Null when the settings are unknown."},"roiTarget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Target ROI the campaign bids to: gross revenue ÷ cost, a ratio (3 means 3×). Null unless bidStrategy is roi_target."},"dailyBudget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Daily budget, in accountCurrency (TikTok's own setting, never converted). Null when unknown."},"settingsSource":{"enum":["live","snapshot"],"type":"string","description":"live: the settings were read from TikTok just now. snapshot: they come from Euka's nightly snapshot of settingsAsOf, either because the campaign is switched off (its settings are only read on demand) or because TikTok could not be reached; in the second case editable is false until TikTok answers again."},"settingsAsOf":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Day of the snapshot the settings come from (YYYY-MM-DD) when settingsSource is snapshot. Null when live."},"ownership":{"enum":["verified","unverified"],"type":"string","description":"verified: the campaign belongs to this brand's TikTok Shop. unverified: a new campaign on an ad account the shop shares with other shops, not yet confirmed as this shop's; it is listed but never edited."},"editable":{"type":"boolean","description":"Whether update_gmv_max_campaign and set_gmv_max_campaign_status can change the campaign now."},"notEditableReason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why editable is false, in one English sentence. Null when editable."},"budgetUtilization":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Average daily cost over the last 3 complete days ÷ dailyBudget: a ratio (0.9 = 90% of the budget spent). Null without a daily budget or without data for those days."},"modifiedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the campaign's settings last changed in TikTok. Null when unknown."},"advertiserId":{"type":"string","description":"TikTok Ads advertiser (ad account) the campaign runs under."},"productSelection":{"anyOf":[{"enum":["auto","custom"],"type":"string"},{"type":"null"}],"description":"How a Product GMV Max campaign picks its products: auto (every product in the shop) or custom (the products in itemGroupIds). Null for LIVE campaigns or when unknown."},"itemGroupIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop product (SPU) ids of a custom product selection; empty otherwise."},"autoBudget":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether TikTok raises the daily budget on its own while the campaign performs."},"maxBudget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Highest daily budget TikTok may raise it to, in accountCurrency. Null when none is set."}},"required":["enabled","maxBudget"]},{"type":"null"}],"description":"TikTok's automatic budget increase. Null when TikTok does not report it."},"scheduleStartTime":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When delivery starts. Null when unknown."},"scheduleEndTime":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When delivery ends. Null when the campaign runs with no end date."},"roiProtection":{"anyOf":[{"enum":["in_effect","not_eligible"],"type":"string"},{"type":"null"}],"description":"in_effect: TikTok's ROI protection covers today (TikTok compensates when ROI falls well short of the target). not_eligible: it does not, for example after a target ROI change or a pause today. Null for max_delivery campaigns or when unknown."},"roiTargetChangedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the target ROI last changed. Null when no change is known."},"tiktokUrl":{"type":"string","description":"Link that opens the ad account's GMV Max campaigns in TikTok Ads Manager (TikTok has no stable per-campaign link)."}},"required":["campaignId","campaignName","type","status","deliveryStatus","bidStrategy","roiTarget","dailyBudget","settingsSource","settingsAsOf","ownership","editable","notEditableReason","budgetUtilization","modifiedAt","advertiserId","productSelection","itemGroupIds","autoBudget","scheduleStartTime","scheduleEndTime","roiProtection","roiTargetChangedAt","tiktokUrl"]},"totals":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"The campaign's totals for the window."},"accountTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"TikTok's own totals for the window, in accountCurrency: what TikTok Ads Manager shows. Null when money is not converted (totals already are)."},"previousTotals":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"The same totals for the comparison window. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"daily":{"type":"array","items":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."},"date":{"type":"string","description":"The day, YYYY-MM-DD in the ad account time zone."}},"required":["cost","grossRevenue","orders","roi","costPerOrder","date"]},"description":"One entry per day of the window, oldest first. A day with no spend has zeros; a day TikTok could not be read for (freshness.liveTail) is left out."},"products":{"type":"array","items":{"type":"object","properties":{"itemGroupId":{"type":"string","description":"TikTok Shop product (SPU) id."},"campaignId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The campaign the row covers. Null when the row sums the product across every campaign."},"productName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title from the shop's catalog. Null when Euka has not synced the product."},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Main product image URL. Null when unknown."},"metrics":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"Totals for the window."},"previous":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"Totals for the comparison window. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."}},"required":["itemGroupId","campaignId","productName","productImageUrl","metrics","previous"]},"description":"The campaign's products with their totals for the window, highest cost first, at most 100. LIVE campaigns have none."},"productsHasMore":{"type":"boolean","description":"True when more products sold in the window than products lists; list_gmv_max_products with this campaignId pages through them all."},"productsHistoryFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day Euka holds the shop's product figures for (YYYY-MM-DD): products miss the days before it. It can be later than freshness.historyFrom, which describes the campaign's own figures. Null when none are held yet."}},"required":["currency","accountCurrency","shopCurrency","exchangeRates","freshness","campaign","totals","accountTotals","previousTotals","daily","products","productsHasMore","productsHistoryFrom"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/campaigns/{campaignId}/history":{"get":{"operationId":"listGmvMaxCampaignHistory","summary":"Campaign change history","description":"Changes to one campaign, newest first: those made in Euka, by Euka's automation rules, and outside Euka (seen in the nightly snapshots).","tags":["GMV Max"],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","description":"TikTok GMV Max campaign id from list_gmv_max_campaigns."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":50,"description":"Most events to return, at most 100."},"allowEmptyValue":true,"allowReserved":true},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time","x-native-type":"date","description":"Only events before this moment: pass the last event's `at` to read the next page, with its id as beforeId."},"allowEmptyValue":true,"allowReserved":true},{"name":"beforeId","in":"query","required":false,"schema":{"type":"string","description":"The last event's id, passed with its `at` as before: events at that same moment that come after it are on the next page too. Several changes made in one go share a moment."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id of the event."},"at":{"type":"string","format":"date-time","x-native-type":"date","description":"When it happened. An edit made outside Euka is dated by TikTok's last-modified time, so several such edits on one day show as one."},"source":{"enum":["euka_user","euka_ai","automation","tiktok"],"type":"string","description":"euka_user: a person in Euka. euka_ai: Copilot or MCP, for a person. automation: an Euka automation rule. tiktok: an edit made outside Euka (TikTok Ads Manager), seen in the nightly snapshots."},"actorName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Who made it: the person, or the AI surface and the person it acted for. Null for automation and edits made outside Euka."},"ruleId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The automation rule that made it (list_gmv_max_rules), when source is automation. Null otherwise."},"ruleName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"That rule's name. Null when source is not automation."},"kind":{"enum":["daily_budget","roi_target","status","creative_removed","creative_restored","boost_started","boost_stopped","other"],"type":"string","description":"What changed: the daily budget, the target ROI, on/off status, a creative removed or added back, a Creative Boost started or stopped, or other (an edit outside Euka that cannot be named)."},"itemId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The TikTok post (video) the change was about, for a creative removed or added back or a Creative Boost started or stopped: the itemId list_gmv_max_creatives returns. Null for campaign-level changes and when unknown."},"before":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value before, as displayed (a budget with its currency, a target ROI, a status). Null when unknown or not applicable, and for automation events, whose after says the whole change."},"after":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The value after, as displayed. For automation events, the rule's own account of the change (e.g. 'Daily budget: $260 → $300'). Null when unknown or not applicable."},"outcome":{"enum":["success","failed","dry_run","skipped"],"type":"string","description":"success: TikTok took the change. failed: TikTok refused it (message says why). dry_run: a rule in dry-run mode would have made it; nothing changed. skipped: a rule chose not to act (message says why)."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok's error or the rule's reason. Null otherwise."}},"required":["id","at","source","actorName","ruleId","ruleName","kind","itemId","before","after","outcome","message"]},"description":"Changes to the campaign from Euka, its automation rules and edits made outside Euka, newest first."},"hasMore":{"type":"boolean","description":"True when older events follow: pass the last `at` as before."}},"required":["events","hasMore"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/campaigns/{campaignId}/recommendation":{"get":{"operationId":"getGmvMaxCampaignRecommendation","summary":"TikTok's recommended settings","description":"TikTok's recommended target ROI and daily budget for one campaign. Live from TikTok.","tags":["GMV Max"],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","description":"TikTok GMV Max campaign id from list_gmv_max_campaigns."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","description":"The campaign, as requested."},"currency":{"type":"string","description":"ISO 4217 code of the ad account currency every money field in this response is in (cost, grossRevenue, costPerOrder, budgets)."},"roiTarget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's recommended target ROI (a ratio). Null when TikTok has none, e.g. for a max_delivery campaign."},"dailyBudget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"TikTok's recommended daily budget, in `currency`. Null when TikTok has none."},"basis":{"type":"string","description":"What TikTok based the recommendation on, in one English sentence."}},"required":["campaignId","currency","roiTarget","dailyBudget","basis"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/products":{"get":{"operationId":"listGmvMaxProducts","summary":"List promoted products","description":"Spend, gross revenue, ROI, orders and cost per order per promoted product (SPU) for a date range, across the shop or within one campaign, with each product's ad impressions and clicks, the campaigns (with their target ROIs) and creatives that spent on it, and everything it sold in TikTok Shop. Filtered, sorted and paged.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","description":"First day of the window, YYYY-MM-DD, inclusive, in the ad account time zone (freshness.timezone)."},"allowEmptyValue":true,"allowReserved":true},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","description":"Last day of the window, YYYY-MM-DD, inclusive, in the ad account time zone. At most 365 days from startDate."},"allowEmptyValue":true,"allowReserved":true},{"name":"compare","in":"query","required":false,"schema":{"enum":["previous_period","none"],"type":"string","default":"previous_period","description":"previous_period also returns the same figures for the equally long window just before startDate; none leaves them null."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string","description":"Only this campaign's products (campaignId from list_gmv_max_campaigns). Leave it out to sum each product across every campaign."},"allowEmptyValue":true,"allowReserved":true},{"name":"itemGroupIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","description":"TikTok Shop product (SPU) id: an itemGroupId from list_gmv_max_products."},"description":"Only these products, at most 100."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Only products whose title or id contains this text, ignoring case."},"allowEmptyValue":true,"allowReserved":true},{"name":"minCost","in":"query","required":false,"schema":{"type":"number","description":"Only products that spent at least this in the window, in the ad account's currency (accountCurrency), also when money is shown in the shop's."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"enum":["cost","grossRevenue","roi","orders","costPerOrder","averageOrderValue","totalRevenue","adShare","productImpressions","productClicks","productClickRate","conversionRate","campaignCount","creativeCount","productName"],"type":"string","default":"cost","description":"Window figure to sort by: a metrics field; averageOrderValue (grossRevenue ÷ orders); adShare (grossRevenue ÷ totalRevenue); productClickRate (productClicks ÷ productImpressions); conversionRate (orders ÷ productClicks); campaignCount; creativeCount; or productName (A to Z ascending). Products without a value come last either way. productName, totalRevenue and adShare sort at most 2,000 products; past that the call fails with BAD_REQUEST."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortDirection","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","description":"desc puts the highest first."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"type":"number","default":1,"description":"Page number, starting at 1."},"allowEmptyValue":true,"allowReserved":true},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","default":20,"description":"Rows per page, at most 100; 20 when left out."},"allowEmptyValue":true,"allowReserved":true},{"name":"include","in":"query","required":false,"schema":{"type":"object","properties":{"campaignNames":{"type":"boolean","default":true,"description":"Name each campaign in campaigns, with its target ROI. With false, those are null and the read skips TikTok Ads."},"totalRevenue":{"type":"boolean","default":true,"description":"Read each product's TikTok Shop sales into totalRevenue. With false, totalRevenue is null, shopSales.status is not_read, and the read skips TikTok Shop; sorting by totalRevenue or adShare reads them anyway."}},"default":{"campaignNames":true,"totalRevenue":true},"description":"Parts of each row read from TikTok, which slow the call. Turn off what the answer doesn't need."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"currency","in":"query","required":false,"schema":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 code of the currency every money figure in this response is in (cost, grossRevenue, costPerOrder, totals, trends): shopCurrency when the read asked for currency shop and could convert, accountCurrency otherwise."},"accountCurrency":{"type":"string","description":"ISO 4217 code of the ad account's billing currency: what TikTok reports and bills in, and what budgets, Min. spend, alert and rule thresholds and every write tool's amounts are in. Never copy a converted figure into a setting."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"rows":{"type":"array","items":{"type":"object","properties":{"itemGroupId":{"type":"string","description":"TikTok Shop product (SPU) id."},"campaignId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The campaign the row covers. Null when the row sums the product across every campaign."},"productName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title from the shop's catalog. Null when Euka has not synced the product."},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Main product image URL. Null when unknown."},"metrics":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."},"productImpressions":{"type":"number","description":"Times the product was shown in a GMV Max ad, summed over its creatives."},"productClicks":{"type":"number","description":"Clicks on the product from those ads."},"totalRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Everything the product sold in TikTok Shop over the window, in `currency`: GMV Max, affiliates, and the shop's own posts and LIVEs. The same figure as Total GMV in the Dashboard's product table. grossRevenue ÷ totalRevenue is the part of the product's sales GMV Max brought in; with money converted it can pass 1, because TikTok converts each order at its own rate. Null when it could not be read (shopSales.status says why)."}},"required":["cost","grossRevenue","orders","roi","costPerOrder","productImpressions","productClicks","totalRevenue"],"description":"Totals for the window."},"previous":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."},"productImpressions":{"type":"number","description":"Times the product was shown in a GMV Max ad, summed over its creatives."},"productClicks":{"type":"number","description":"Clicks on the product from those ads."},"totalRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Everything the product sold in TikTok Shop over the window, in `currency`: GMV Max, affiliates, and the shop's own posts and LIVEs. The same figure as Total GMV in the Dashboard's product table. grossRevenue ÷ totalRevenue is the part of the product's sales GMV Max brought in; with money converted it can pass 1, because TikTok converts each order at its own rate. Null when it could not be read (shopSales.status says why)."}},"required":["cost","grossRevenue","orders","roi","costPerOrder","productImpressions","productClicks","totalRevenue"]},{"type":"null"}],"description":"Totals for the comparison window. Null when compare is none. Its totalRevenue is null when the comparison window starts more than 178 days ago, which is as far back as TikTok keeps product sales. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"campaigns":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string","description":"GMV Max campaign id."},"campaignName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The campaign's name. Null when unknown."},"bidStrategy":{"anyOf":[{"enum":["roi_target","max_delivery"],"type":"string"},{"type":"null"}],"description":"roi_target: bids to hold roiTarget. max_delivery: spends the daily budget for the most orders, with no ROI target. Null when the settings are unknown."},"roiTarget":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The campaign's target ROI as set now: gross revenue ÷ cost, a ratio (3 means 3×). Null unless bidStrategy is roi_target."}},"required":["campaignId","campaignName","bidStrategy","roiTarget"]},"description":"The campaigns that spent on the product in the window, highest cost first. TikTok sets a target ROI per campaign, not per product, so a product is held to its campaign's."},"creativeCount":{"type":"number","description":"Posts that spent on the product in the window, across its campaigns. list_gmv_max_creatives with itemGroupIds lists them."}},"required":["itemGroupId","campaignId","productName","productImageUrl","metrics","previous","campaigns","creativeCount"]},"description":"Products GMV Max promoted in the window, sorted. LIVE GMV Max spend has no product and is not in them."},"total":{"type":"number","description":"Products the filters match in the window, across every page."},"hasMore":{"type":"boolean","description":"True when another page follows this one."},"shopSales":{"type":"object","properties":{"status":{"enum":["ok","partial","unavailable","before_retention","other_currency","not_read"],"type":"string","description":"ok: read from TikTok Shop. partial: read as far as the shop's best sellers go (500 of them, or 2,000 when sorting by totalRevenue or adShare); a product further down has a null totalRevenue. unavailable: TikTok Shop could not be read just now; retrying later can help. before_retention: the window starts more than 178 days ago, further back than TikTok keeps product sales. other_currency: the shop sells in shopCurrency while the response's money is in `currency` (ask for currency shop to compare them). not_read: include.totalRevenue was false. Every totalRevenue is null unless ok or partial."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code TikTok Shop reported the sales in. Null when unknown."},"through":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) TikTok Shop's product sales are ready for: totalRevenue leaves out the window's days after it. Null when unknown."}},"required":["status","shopCurrency","through"],"description":"How the products' totalRevenue was read."}},"required":["currency","accountCurrency","shopCurrency","exchangeRates","freshness","rows","total","hasMore","shopSales"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/creatives":{"get":{"operationId":"listGmvMaxCreatives","summary":"List creatives","description":"Per-creative (video) metrics for a date range with delivery status, authorization, performance against the campaign and active Creative Boosts, filtered, sorted and paged.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"startDate","in":"query","required":true,"schema":{"type":"string","description":"First day of the window, YYYY-MM-DD, inclusive, in the ad account time zone (freshness.timezone)."},"allowEmptyValue":true,"allowReserved":true},{"name":"endDate","in":"query","required":true,"schema":{"type":"string","description":"Last day of the window, YYYY-MM-DD, inclusive, in the ad account time zone. At most 365 days from startDate."},"allowEmptyValue":true,"allowReserved":true},{"name":"compare","in":"query","required":false,"schema":{"enum":["previous_period","none"],"type":"string","default":"previous_period","description":"previous_period also returns the same figures for the equally long window just before startDate; none leaves them null."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string","description":"Only creatives in this campaign (campaignId from list_gmv_max_campaigns)."},"allowEmptyValue":true,"allowReserved":true},{"name":"campaignIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","description":"TikTok GMV Max campaign id from list_gmv_max_campaigns."},"description":"Only creatives in one of these campaigns, e.g. the campaigns of the findings of one kind from list_gmv_max_insights."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"items","in":"query","required":false,"schema":{"type":"array","items":{"type":"object","properties":{"campaignId":{"type":"string","description":"TikTok GMV Max campaign id from list_gmv_max_campaigns."},"itemId":{"type":"string","description":"TikTok post id of the creative, from list_gmv_max_creatives."}},"required":["campaignId","itemId"]},"description":"Only these creatives: each post (itemId) in the campaign named. A finding from list_gmv_max_insights names its creatives as itemIds in its campaignId; pass them here to list them."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"itemGroupId","in":"query","required":false,"schema":{"type":"string","description":"Only creatives promoting this TikTok Shop product (SPU id, itemGroupId from list_gmv_max_products)."},"allowEmptyValue":true,"allowReserved":true},{"name":"itemGroupIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Only creatives promoting one of these TikTok Shop products (itemGroupIds from list_gmv_max_products), at most 100."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"enum":["in_queue","learning","delivering","not_delivering","authorization_needed","excluded","unavailable","rejected","not_active","unknown"],"type":"string","description":"TikTok's delivery status of the creative: in_queue (waiting to be tested), learning, delivering, not_delivering (TikTok stopped spending on it), authorization_needed (the creator must authorize it before it can run), excluded (taken out of the campaign), unavailable, rejected (failed review), not_active, or unknown (no status seen yet)."},"description":"Only creatives in one of these delivery statuses."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"performance","in":"query","required":false,"schema":{"enum":["top","under"],"type":"string","description":"Only creatives judged top (ROI at least 1.2× their campaign's) or under (ROI at most 0.8× their campaign's, or no orders). Creatives that spent too little to judge are left out."},"allowEmptyValue":true,"allowReserved":true},{"name":"minCost","in":"query","required":false,"schema":{"type":"number","description":"Only creatives that spent at least this in the window, in the ad account's currency (accountCurrency), also when money is shown in the shop's."},"allowEmptyValue":true,"allowReserved":true},{"name":"belowRoiTarget","in":"query","required":false,"schema":{"type":"boolean","description":"true: only creatives whose ROI in the window is under their campaign's target ROI; max delivery campaigns have none."},"allowEmptyValue":true,"allowReserved":true},{"name":"needsAuthorization","in":"query","required":false,"schema":{"type":"boolean","description":"true: only creatives that cannot run until the creator authorizes them; false: leave those out."},"allowEmptyValue":true,"allowReserved":true},{"name":"sparkCode","in":"query","required":false,"schema":{"enum":["has","none"],"type":"string","description":"Only creatives that need authorization, split by whether Euka holds a Spark Code for the post: has (apply it with apply_spark_codes_to_tiktok_ads so the creative can run) or none (ask the creator for one). Checks at most 5,000 of them, like search."},"allowEmptyValue":true,"allowReserved":true},{"name":"boosted","in":"query","required":false,"schema":{"type":"boolean","description":"true: only creatives with a Creative Boost running now; false: leave those out. Read live from TikTok; the call fails with SERVICE_UNAVAILABLE when TikTok cannot be asked."},"allowEmptyValue":true,"allowReserved":true},{"name":"search","in":"query","required":false,"schema":{"type":"string","description":"Only creatives whose caption or creator handle contains this text, ignoring case. Search looks through at most 5,000 creatives, those the other filters leave; with more, the call fails with BAD_REQUEST, so narrow the list first."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"enum":["cost","grossRevenue","roi","orders","costPerOrder","productClickRate","conversionRate"],"type":"string","default":"cost","description":"Window figure to sort by."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortDirection","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","description":"desc puts the highest first."},"allowEmptyValue":true,"allowReserved":true},{"name":"page","in":"query","required":false,"schema":{"type":"number","default":1,"description":"Page number, starting at 1."},"allowEmptyValue":true,"allowReserved":true},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number","default":20,"description":"Rows per page, at most 100; 20 when left out."},"allowEmptyValue":true,"allowReserved":true},{"name":"currency","in":"query","required":false,"schema":{"enum":["account","shop"],"type":"string","default":"account","description":"account (default): money in the ad account's billing currency, TikTok's own figures. shop: money in the TikTok Shop's currency (shopCurrency), each day converted at the last European Central Bank rate before it; ROI and changes against the previous period stay TikTok's own. When the shop's currency is unknown or the same, or a day has no ECB rate, money stays in the account's currency; currency in the answer always says which. Budgets and other settings are always in accountCurrency."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217 code of the currency every money figure in this response is in (cost, grossRevenue, costPerOrder, totals, trends): shopCurrency when the read asked for currency shop and could convert, accountCurrency otherwise."},"accountCurrency":{"type":"string","description":"ISO 4217 code of the ad account's billing currency: what TikTok reports and bills in, and what budgets, Min. spend, alert and rule thresholds and every write tool's amounts are in. Never copy a converted figure into a setting."},"shopCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 code of the currency the TikTok Shop sells in. Null when the shop's market has none Euka knows (GLOBAL or unknown); money is then never converted."},"exchangeRates":{"anyOf":[{"type":"object","properties":{"source":{"enum":["ecb"],"type":"string","description":"ecb: the European Central Bank's euro reference rates, crossed through the euro."},"firstRateDate":{"type":"string","description":"Oldest ECB rate date used, YYYY-MM-DD."},"lastRateDate":{"type":"string","description":"Newest ECB rate date used, YYYY-MM-DD."}},"required":["source","firstRateDate","lastRateDate"]},{"type":"null"}],"description":"The rates money was converted at: each report day uses the last rate the ECB published before that day, so a weekend uses Friday's. Null when nothing was converted and money is in accountCurrency."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"rows":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"TikTok post id of the creative: the itemId the creative tools take."},"campaignId":{"type":"string","description":"The campaign the creative runs in."},"campaignName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The campaign's name. Null when unknown."},"itemGroupId":{"type":"string","description":"TikTok Shop product (SPU) id the creative promotes."},"productName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title from the shop's catalog. Null when unknown."},"productImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Main product image URL. Null when unknown."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The post's caption. Null when unknown."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The post's cover image URL. Null when unknown."},"creatorHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok handle of the account that posted it. Null when unknown."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"That account's avatar URL. Null when unknown."},"authorizationType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the shop may advertise the post, as TikTok spells it: AFFILIATE (the creator's ad authorization), AUTH_CODE (a Spark code), or TTS_TT, TT_USER or BC_AUTH_TT (an account the shop owns or manages). Null when unknown."},"status":{"enum":["in_queue","learning","delivering","not_delivering","authorization_needed","excluded","unavailable","rejected","not_active","unknown"],"type":"string","description":"TikTok's delivery status of the creative: in_queue (waiting to be tested), learning, delivering, not_delivering (TikTok stopped spending on it), authorization_needed (the creator must authorize it before it can run), excluded (taken out of the campaign), unavailable, rejected (failed review), not_active, or unknown (no status seen yet)."},"statusAsOf":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the status was observed: the status comes from the daily sync, not live. Null when status is unknown."},"pendingChange":{"anyOf":[{"type":"object","properties":{"kind":{"enum":["excluded","restored"],"type":"string","description":"excluded: Euka took the creative out of GMV Max (remove_videos_from_gmv_max); restored: Euka added it back (restore_videos_to_gmv_max)."},"at":{"type":"string","format":"date-time","x-native-type":"date","description":"When Euka made the change."}},"required":["kind","at"]},{"type":"null"}],"description":"A change Euka made to the creative after the last daily sync, which TikTok's next daily sync will confirm; until then `status` (and the status filter and counts) still shows what the last sync saw. Null when there is none."},"metrics":{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"],"description":"Totals for the window."},"previous":{"anyOf":[{"type":"object","properties":{"cost":{"type":"number","description":"Ad spend, in `currency`."},"grossRevenue":{"type":"number","description":"Gross revenue of the TikTok Shop orders TikTok attributes to the ads, in `currency`: what buyers paid plus TikTok Shop subsidies."},"orders":{"type":"number","description":"SKU orders TikTok attributes to the ads."},"roi":{"type":"number","description":"grossRevenue ÷ cost: a ratio (3 means 3×), not a percentage. Always TikTok's own, from the ad account's figures, so it never moves with an exchange rate. 0 when nothing was spent."},"costPerOrder":{"type":"number","description":"cost ÷ orders, in `currency`. 0 when there were no orders."}},"required":["cost","grossRevenue","orders","roi","costPerOrder"]},{"type":"null"}],"description":"Totals for the comparison window. Null when compare is none. When money is converted, the comparison period is at this window's rates (constant currency), so a change between the two is TikTok's own and never an exchange-rate move."},"productImpressions":{"type":"number","description":"Times the product was shown in an ad with this post, in the window."},"productClicks":{"type":"number","description":"Clicks on the product from those ads, in the window."},"productClickRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"productClicks ÷ productImpressions, a ratio (0.02 = 2%). Null without impressions."},"conversionRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"orders ÷ productClicks, a ratio. Null without clicks."},"viewRate2s":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share of ad views watched for at least 2 seconds, a ratio. Null when TikTok reports none."},"viewRate6s":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share of ad views watched for at least 6 seconds, a ratio. Null when TikTok reports none."},"performance":{"anyOf":[{"enum":["top","average","under"],"type":"string"},{"type":"null"}],"description":"ROI against the campaign's, once the creative spent at least 2× the campaign's cost per order or 5% of its cost: top (at least 1.2×), under (at most 0.8×, or no orders) or average. Null below that spend."},"boost":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string","description":"The boost session: pass it to stop_gmv_max_creative_boost."},"dailyBudget":{"type":"number","description":"Daily boost budget, in accountCurrency (TikTok's own setting, never converted)."},"endsAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the boost ends. Null when it runs until the campaign ends."}},"required":["sessionId","dailyBudget","endsAt"]},{"type":"null"}],"description":"The Creative Boost running on the creative right now. Null when there is none, or when boostsUnavailable is true."},"sparkCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For a creative that needs authorization: the unexpired Spark Code Euka holds for the post (sent by the creator by DM, on the Spark Code form, or uploaded). Applying it with apply_spark_codes_to_tiktok_ads lets the creative run. Null for other statuses, or when Euka holds none."},"sparkCodeAppliedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When Euka last sent that Spark Code to the campaign's ad account, while TikTok accepted it or is still checking it; the status changes at TikTok's next daily sync. Null when it was not sent, or TikTok refused it."},"tiktokUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link to the post on TikTok. Null when unknown."}},"required":["itemId","campaignId","campaignName","itemGroupId","productName","productImageUrl","caption","thumbnailUrl","creatorHandle","creatorAvatarUrl","authorizationType","status","statusAsOf","pendingChange","metrics","previous","productImpressions","productClicks","productClickRate","conversionRate","viewRate2s","viewRate6s","performance","boost","sparkCode","sparkCodeAppliedAt","tiktokUrl"]},"description":"Creatives on this page, sorted. A creative is one TikTok post promoting one product in one campaign, so a video can appear in several rows."},"hasMore":{"type":"boolean","description":"True when another page follows this one."},"boostsUnavailable":{"type":"boolean","description":"True when TikTok could not be asked which creatives are boosted right now: every boost is then null, which does not mean unboosted."},"statusCounts":{"type":"object","propertyNames":{"enum":["in_queue","learning","delivering","not_delivering","authorization_needed","excluded","unavailable","rejected","not_active","unknown"],"type":"string","description":"TikTok's delivery status of the creative: in_queue (waiting to be tested), learning, delivering, not_delivering (TikTok stopped spending on it), authorization_needed (the creator must authorize it before it can run), excluded (taken out of the campaign), unavailable, rejected (failed review), not_active, or unknown (no status seen yet)."},"additionalProperties":{"type":"number"},"description":"Creatives per delivery status under every filter except status, boosted and sparkCode, for the status tabs."},"boostedCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Creatives with a Creative Boost running now, under the same filters as statusCounts. Null when boostsUnavailable is true."},"sparkCodeCounts":{"anyOf":[{"type":"object","properties":{"has":{"type":"number","description":"Creatives needing authorization whose post Euka holds a Spark Code for."},"none":{"type":"number","description":"Creatives needing authorization with no Spark Code in Euka."}},"required":["has","none"]},{"type":"null"}],"description":"Creatives needing authorization, with and without a Spark Code, under the same filters as statusCounts. Counted only when status is [authorization_needed] or sparkCode is set, and at most 5,000 of them; null otherwise."}},"required":["currency","accountCurrency","shopCurrency","exchangeRates","freshness","rows","hasMore","boostsUnavailable","statusCounts","boostedCount","sparkCodeCounts"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/creative-boosts":{"get":{"operationId":"listGmvMaxCreativeBoosts","summary":"List active Creative Boosts","description":"Returns the creatives in one campaign that have an active Creative Boost session, with daily budget, the ad account currency it is in, and schedule. Live from TikTok.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"campaignId","in":"query","required":true,"schema":{"type":"string","description":"Required. TikTok lists boost sessions per campaign (campaignId from list_gmv_max_campaigns)."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"advertiserId":{"type":"string","description":"TikTok Ads advertiser (ad account) the campaign runs under: the advertiserId passed in, or the shop's only advertiser."},"campaignId":{"type":"string","description":"GMV Max campaign the boosts belong to, as requested."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ad account's billing currency (ISO code) that every boost budget is in. Null only when TikTok did not return one."},"source":{"const":"live","description":"Fetched from the TikTok Business API at request time."},"boosts":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string","description":"TikTok’s id for this Creative Boost session."},"itemId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok post id of the boosted creative. Null only when TikTok did not return one."},"itemGroupIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop product (SPU) ids the boost is attached to."},"budget":{"type":"number","description":"Daily boost budget, in `currency`."},"scheduleStartTime":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the boost started. Null when TikTok omits it."},"scheduleEndTime":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When the boost ends. Null when it has no end time of its own and runs until the campaign’s scheduled end."}},"required":["sessionId","itemId","itemGroupIds","budget","scheduleStartTime","scheduleEndTime"]},"description":"Creatives in the campaign with an active Creative Boost right now, live from TikTok. Ended boosts are not listed."}},"required":["advertiserId","campaignId","currency","source","boosts"]}}}}},"security":[{"openApiKey":[]}]}},"/gmv-max/insights":{"get":{"operationId":"listGmvMaxInsights","summary":"What needs attention","description":"Findings about the shop's GMV Max campaigns from the last 28 complete days (budget limits, ROI below target, campaigns not spending, creatives needing authorization), each with a suggested action.","tags":["GMV Max"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Brand UUID from list_accessible_brands[].brandId."},"allowEmptyValue":true,"allowReserved":true},{"name":"advertiserId","in":"query","required":false,"schema":{"type":"string","description":"TikTok Ads advertiser (ad account) id from list_gmv_max_advertisers. Leave it out: it is resolved automatically, and is needed only when the shop runs GMV Max from several ad accounts in different currencies."},"allowEmptyValue":true,"allowReserved":true},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string","description":"Only findings about this campaign (campaignId from list_gmv_max_campaigns)."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time","x-native-type":"date","description":"When the insights were computed."},"freshness":{"type":"object","properties":{"timezone":{"type":"string","description":"IANA time zone of the ad account, e.g. America/Los_Angeles. TikTok counts every report day in it."},"syncedThrough":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (YYYY-MM-DD) Euka's daily sync covers. Days after it come from the live read in liveTail. Null when nothing has synced yet."},"syncedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When that sync finished. Null when nothing has synced yet."},"partial":{"type":"boolean","description":"True when the latest sync was partial: some of its TikTok requests failed, so synced days can be missing spend."},"liveTail":{"anyOf":[{"type":"object","properties":{"status":{"enum":["ok","rate_limited","timeout","unavailable","not_read"],"type":"string","description":"ok: the days were read live from TikTok. rate_limited, timeout or unavailable: TikTok could not be read, and those days are left out of every figure (not counted as zero); retrying later can help. not_read: nothing failed, this view (creatives, products) uses Euka's daily sync only, so those days are not included until the next sync; retrying does not help."},"from":{"type":"string","description":"First day after syncedThrough in the window, YYYY-MM-DD in the ad account time zone."},"to":{"type":"string","description":"Last such day, YYYY-MM-DD, inclusive; never later than today in the ad account time zone."},"fetchedAt":{"anyOf":[{"type":"string","format":"date-time","x-native-type":"date"},{"type":"null"}],"description":"When TikTok answered. Null unless status is ok."}},"required":["status","from","to","fetchedAt"]},{"type":"null"}],"description":"The window days after syncedThrough (normally only today): read live from TikTok, or not_read where a view uses the daily sync only. Null when the window ends on or before syncedThrough."},"historyFrom":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day (YYYY-MM-DD) Euka holds the shop's GMV Max delivery at the level these figures come from: campaigns, products or creatives. Days before it are not in any figure: Euka's history starts there, not the shop's spend. Null when it holds none yet."},"historyImport":{"anyOf":[{"enum":["importing","failed","needs_reconnect"],"type":"string"},{"type":"null"}],"description":"Euka's import of the shop's earlier GMV Max history at this level. importing: earlier days are still being added, so historyFrom moves back; ask again later. failed: the import stopped on errors; Euka tries again within a day, or Retry on the GMV Max page restarts it now. needs_reconnect: TikTok refused an ad account; reconnect TikTok Ads. Null when nothing is being imported."}},"required":["timezone","syncedThrough","syncedAt","partial","liveTail","historyFrom","historyImport"],"description":"How current the figures are: which days come from the daily sync and which were read live."},"insights":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable id: the same finding about the same campaign and window keeps it."},"campaignId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The campaign it is about. Null for a shop-wide finding."},"campaignName":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"That campaign's name. Null for a shop-wide finding."},"kind":{"enum":["budget_limited","spend_drop_roi_on_target","roi_below_target","roi_target_changed_recently","not_spending","authorization_needed","few_delivering_creatives","top_creative_unboosted"],"type":"string","description":"budget_limited: spends at least 80% of its budget while at or above its ROI target, so more budget can scale it. spend_drop_roi_on_target: spend fell to 70% or less of the week before while ROI held; check delivery and budget before raising spend. roi_below_target: 7-day ROI under 80% of the target. roi_target_changed_recently: the target changed under 3 days ago; hold it. not_spending: switched on but spent nothing for 2 complete days. authorization_needed: creatives that sold need the creator's authorization to keep running. few_delivering_creatives: fewer than 5 creatives delivering. top_creative_unboosted: a top creative gets little of the campaign's spend and has no boost."},"severity":{"enum":["critical","warning","opportunity","info"],"type":"string","description":"critical: losing money now. warning: something to check. opportunity: room to grow. info: context, such as why to hold a setting."},"summary":{"type":"string","description":"The finding in one English sentence, with its numbers."},"facts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"number"},{"type":"string"}]},"description":"The figures behind the finding, by name (for example roi, roiTarget, cost, dailyBudget). Money is in the ad account currency, given as facts.currency; ROI is a ratio."},"action":{"anyOf":[{"type":"object","properties":{"type":{"enum":["edit_budget","edit_roi_target","review_creatives","authorize_creatives","check_delivery","hold"],"type":"string","description":"edit_budget or edit_roi_target: change the campaign with update_gmv_max_campaign. review_creatives or authorize_creatives: look at its creatives with list_gmv_max_creatives. check_delivery: check its status and delivery in TikTok. hold: change nothing for now."},"suggested":{"type":"object","properties":{"dailyBudget":{"type":"number","description":"Suggested daily budget, in the ad account currency."},"roiTarget":{"type":"number","description":"Suggested target ROI, a ratio."}},"description":"Values to start the edit from; empty for other actions."}},"required":["type","suggested"]},{"type":"null"}],"description":"What to do about it. Null when there is nothing to do."},"itemIds":{"type":"array","items":{"type":"string"},"description":"The creatives the finding is about, as TikTok post ids in campaignId (at most 100): the posts that sold but need authorization, or the top creatives with no boost. Pass them as items to list_gmv_max_creatives. Empty for findings about the campaign as a whole."}},"required":["id","campaignId","campaignName","kind","severity","summary","facts","action","itemIds"]},"description":"What needs attention, most severe first. Empty when nothing does."}},"required":["generatedAt","freshness","insights"]}}}}},"security":[{"openApiKey":[]}]}},"/licensed-content/search":{"post":{"operationId":"searchLicensedContent","summary":"Search Licensed Content","description":"List the videos and images a brand holds usage rights to, with the brand’s tags, whether Euka uploaded each one to Meta, how many synced Meta ads use it, and its license terms and end date. Filter by tags with filter.tagIds and filter.tagMatch. Results default to 20 per page: for a full sync, set pageSize to 100, sort by createdAt ascending, and increment page while page × pageSize is below total. Euka links a Meta ad to this content, and pays its creator, only when the ad uses a file Euka uploaded to Meta or its ad name contains the item’s videoId.","tags":["Licensed Content"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string"},"filter":{"type":"object","properties":{"licensedContentIds":{"type":"array","items":{"type":"string"}},"requestIds":{"type":"array","items":{"type":"number"},"description":"Only content licensed under these usage rights requests."},"creatorQuery":{"type":"string","description":"Part of a creator handle or video id."},"favorite":{"type":"boolean","description":"true lists only starred content; false only the rest."},"source":{"enum":["per-content","enrollment","marketplace","contest","spark","retainer"],"type":"string","description":"How the rights were obtained: per-content (negotiated for this video), enrollment (the creator’s enrollment in the brand’s creator program), marketplace (an approved Creator Marketplace submission), spark (a Spark code that allows promotion), retainer, or contest (a contest, and any other rights granted without an offer)."},"compensation":{"enum":["flat_fee","percentage","free"],"type":"string","description":"Only content whose current license pays this way: flat_fee (a one-time fee), percentage (a commission on sales or ad spend), or free."},"platform":{"enum":["tiktok","instagram","uploaded"],"type":"string","description":"tiktok: TikTok videos; instagram: Instagram imports; uploaded: files the creator uploaded in the Euka creator app."},"reviewStatus":{"enum":["pending","approved","rejected"],"type":"string","description":"Creator uploads to an Ads Program the brand reviews first wait as 'pending' until approved. Absent means approved content only."},"hasLinkedAds":{"type":"boolean","description":"true lists only content a synced Meta ad uses (active, paused or stopped; multi-video ads and ads running an edited version count); false only content no ad uses."},"excludeHiddenCreators":{"type":"boolean","description":"true leaves out content from creators the brand hid on its Licensed Content page."},"edited":{"type":"boolean","description":"true lists the brand's edited versions of its licensed videos (each a row under its original) instead of the originals. Otherwise only originals are listed, with their edited versions nested in `editedCuts`."},"resolution":{"enum":["1080p","720p-or-below"],"type":"string","description":"Whether the file Euka serves for the item is at least 1080p, as read from the file. '720p-or-below' is every item that is not '1080p', including items whose resolution is unknown (not yet synced, or a file not yet measured)."},"mediaType":{"enum":["video","image"],"type":"string","description":"The item's mediaType: 'image' for static images (photos uploaded or imported as images), 'video' for everything else, including TikTok photo posts, which Euka stores as slideshow videos."},"postedFrom":{"type":"string","description":"Earliest TikTok post time, inclusive. Setting either posted bound leaves out content with no TikTok post."},"postedTo":{"type":"string","description":"Latest TikTok post time, inclusive."},"grantedFrom":{"type":"string","description":"Earliest time the rights became final (grantedAt, or createdAt when it is null), inclusive."},"grantedTo":{"type":"string","description":"Latest time the rights became final, inclusive."},"tagIds":{"type":"array","items":{"type":"string"},"description":"Tag ids from the brand’s tag list; tagMatch sets how they apply."},"tagMatch":{"enum":["any","all","none","empty","notEmpty"],"type":"string","default":"any","description":"any: content with at least one of tagIds; all: with every one; none: with none of them. empty and notEmpty ignore tagIds and list content with no tags or with any tag."},"noteStatusIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"const":"none"}]},"description":"Only content whose note has one of these statuses (ids from the brand’s note status list). none matches content with no status."},"productIds":{"type":"array","items":{"type":"string"},"description":"TikTok Shop product ids the videos promote."},"priorityGrades":{"type":"array","items":{"enum":["a","b","c","d","pending"],"type":"string","description":"Ad Potential grade: a (best) to d, from common content-quality checks plus Creative Coach insights when the product has them. Readiness blockers do not change it; they are flags. pending: not analysed yet."},"description":"Only content with one of these Ad Potential grades."},"priorityFlag":{"enum":["personal_info_visible","wrong_or_missing_product","competitor_product_featured","brand_rule","double_discount","slideshow_or_stock","tiktok_shop","discount","any","none"],"type":"string","description":"Only content with this flag (a failed readiness blocker, or a tiktok_shop or discount mention), with any flag (any), or analysed content with none (none)."},"priorityInsightKeys":{"type":"array","items":{"type":"string"},"description":"Only content showing at least one of these tested insights."},"singleProduct":{"type":"boolean","description":"true lists only content where no other product is used or shown on camera; false only content that shows another product."}},"default":{"tagMatch":"any"}},"sort":{"type":"object","properties":{"field":{"enum":["createdAt","postedAt","grantedAt","tiktokViews","tiktokRevenue","priority"],"type":"string"},"direction":{"enum":["asc","desc"],"type":"string"}},"required":["field","direction"],"default":{"field":"createdAt","direction":"desc"}},"page":{"type":"number","default":1},"pageSize":{"type":"number","default":20}},"required":["brandId"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Licensed Content id: the licensedContentId that download, tag, and Meta operations take."},"brandId":{"type":"string","description":"The brand that holds the rights."},"requestId":{"type":"number","description":"The usage rights request whose terms govern this content."},"videoId":{"type":"string","description":"The licensed video: a TikTok video id, euka_v_… for a file uploaded in the Euka creator app, ig_… for an Instagram import, or euka_cut_… for an edited cut the brand uploaded."},"sourceLicensedContentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set on an edited cut: the Licensed Content id of the original it was edited from. A cut is paid and capped under its original’s terms. Null on originals."},"sourceVideoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set on an edited cut: the videoId of the original it was edited from, which Meta ads made from the cut end their name with. Null on originals."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The brand’s name for this content, e.g. \"Cut 2\" for an edited cut. Null when the brand has not named it."},"creatorHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The creator’s TikTok handle, or their name from the Euka creator app when they have none. Null when unknown."},"source":{"enum":["per-content","enrollment","marketplace","contest","spark","retainer"],"type":"string","description":"How the rights were obtained: per-content (negotiated for this video), enrollment (the creator’s enrollment in the brand’s creator program), marketplace (an approved Creator Marketplace submission), spark (a Spark code that allows promotion), retainer, or contest (a contest, and any other rights granted without an offer)."},"tiktokSyncStatus":{"enum":["none","processing","ready","failed"],"type":"string","description":"Progress of Euka’s copy of the TikTok video file, which the tiktok download and Meta uploads use: none (not started), processing, ready, or failed (the copy can be retried). Files uploaded in the Euka creator app are ready."},"mediaType":{"enum":["video","image"],"type":"string","description":"image when the stored file is an image, otherwise video."},"assets":{"type":"object","properties":{"tiktokAvailable":{"type":"boolean","description":"Whether Euka’s copy of the TikTok video is ready to download (asset tiktok)."},"originalAvailable":{"type":"boolean","description":"Whether an original file from the creator has been received (asset original). False while an upload has started but no bytes have arrived."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Thumbnail image URL. Null when there is none."},"mimeType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"MIME type of the stored file, such as video/mp4. Null when no file is stored."},"hd1080":{"type":"boolean","description":"Whether the file Euka serves for downloads and Meta is at least 1080p, as read from the file (short side of 1080 pixels or more). False for smaller files and for files not yet measured."}},"required":["tiktokAvailable","originalAvailable","thumbnailUrl","mimeType","hd1080"],"description":"Which files Euka holds for this content."},"enrollmentId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The creator program enrollment the rights came from. Null otherwise."},"partnershipEligible":{"type":"boolean","description":"Whether the creator has granted Meta partnership-ad permission, so an ad from this content can run with their Instagram account."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the video was posted on TikTok. Null for uploads, Instagram imports, or when unknown."},"tiktokRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok Shop GMV of the video in the shop’s currency, as of Euka’s last update; may be Euka’s estimate for a video not read from a connected shop. Null when unknown or not a TikTok video."},"tiktokViews":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok views as of Euka’s last update. Null when unknown or not a TikTok video."},"linkedAdCount":{"type":"number","description":"Synced Meta ads linked to this content, including ads it shares with other videos. 0 when none."},"uploadedToMeta":{"type":"boolean","description":"Whether Euka has uploaded this content’s file to one of the brand’s Meta ad accounts. It does not mean an ad exists."},"metaAdSpend":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Always null in this result; Meta spend is reported separately."},"metaAdSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Always null in this result; Meta sales are reported separately."},"favorite":{"type":"boolean","description":"Whether the brand starred this content."},"product":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title. Null when Euka does not have it."},"photoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product image URL; the image may be missing. Null when unavailable."}},"required":["id","title","photoUrl"]},{"type":"null"}],"description":"The TikTok Shop product the video promotes. Null when unknown or not a TikTok video."},"terms":{"type":"object","properties":{"duration":{"anyOf":[{"type":"object","properties":{"kind":{"const":"months"},"months":{"type":"number","description":"Length of the license in months, counted from when the creator accepts."}},"required":["kind","months"]},{"type":"object","properties":{"kind":{"const":"perpetual"}},"required":["kind"]}],"description":"How long the rights last: a number of months, or perpetual (no end date)."},"compensation":{"anyOf":[{"type":"object","properties":{"kind":{"const":"free"}},"required":["kind"]},{"type":"object","properties":{"kind":{"const":"flatFee"},"amount":{"type":"object","properties":{"amount":{"type":"number","description":"Fee in whole currency units (dollars for USD), not cents."},"currency":{"type":"string","description":"ISO 4217 currency code, such as USD."}},"required":["amount","currency"],"description":"One-time fee paid to the creator for the rights."}},"required":["kind","amount"]},{"type":"object","properties":{"kind":{"const":"percentage"},"ratePercent":{"type":"number","description":"Commission rate, as a percentage (0–100) of the basis."},"basis":{"enum":["metaAdSpend","metaWebsiteSales","metaAttributedSales","tripleWhaleLastClickSales","tripleWhaleFirstClickSales"],"type":"string","description":"What a percentage is taken of, across the ads that use the video: metaAdSpend (Meta ad spend), metaWebsiteSales (website purchases Meta attributes to the ads), metaAttributedSales (all purchases Meta attributes to the ads), tripleWhaleLastClickSales or tripleWhaleFirstClickSales (orders Triple Whale credits to the ads as the last or first click)."},"maxPayout":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Cap in major currency units (dollars for USD), not cents."},"currency":{"type":"string","description":"ISO 4217 currency code, such as USD."}},"required":["amount","currency"]},{"type":"null"}],"description":"Most the creator can earn in total under these terms, over the whole license. Null means no cap."}},"required":["kind","ratePercent","basis","maxPayout"]}],"description":"What the creator is paid: free (nothing), flatFee (a one-time amount), or percentage (a share of the basis, calculated for each 7-day payout period)."}},"required":["duration","compensation"],"description":"Current license terms. With tiered commission (commissionIsTiered), the rate shown is not the rate paid."},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the license ends. Null when it has no end date. Expired content is still listed."},"grantedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the rights became final: payment of a flat fee, or the creator’s acceptance. Null for enrollment rights and rights granted without an offer, whose grant time is createdAt."},"commissionIsTiered":{"type":"boolean","description":"Whether the brand’s creator program pays this license by creator tier, so the brand’s current tier table sets the rate."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","description":"Tag color as saved by the brand, usually a hex code such as #1890ff."}},"required":["id","name","color"]},"description":"The brand’s tags on this content, A to Z."},"note":{"anyOf":[{"type":"object","properties":{"text":{"type":"string","description":"The note. Empty when only a status is set."},"status":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","description":"Status color, a hex code such as #D89614."}},"required":["id","name","color"]},{"type":"null"}]},"updatedAt":{"type":"string","description":"When the note was last saved."},"updatedBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the teammate who last saved it. Null when unknown."}},"required":["text","status","updatedAt","updatedBy"]},{"type":"null"}],"description":"The brand’s current note and status on this content. Null when it has none."},"priority":{"anyOf":[{"type":"object","properties":{"grade":{"enum":["a","b","c","d","pending"],"type":"string","description":"Ad Potential grade: a (best) to d, from common content-quality checks plus Creative Coach insights when the product has them. Readiness blockers do not change it; they are flags. pending: not analysed yet."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad Potential score 0-100 behind the grade. Null until analysed."},"common":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The common content checks part of the score."},"coach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The Creative Coach part of the score; null when the product has no tested insight that goes with higher spend, so the score is the common checks alone."},"singleProduct":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether no product other than the promoted one is used or shown on camera. Null until analysed."},"flags":{"type":"array","items":{"type":"object","properties":{"key":{"enum":["personal_info_visible","wrong_or_missing_product","competitor_product_featured","brand_rule","double_discount","slideshow_or_stock","tiktok_shop","discount"],"type":"string","description":"tiktok_shop: TikTok Shop is said or shown. discount: a discount or deal is said or shown. The rest are failed readiness blockers: personal_info_visible, wrong_or_missing_product, competitor_product_featured, brand_rule, double_discount, slideshow_or_stock."},"startSeconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Where in the video it is first observed."}},"required":["key","startSeconds"]},"description":"Failed readiness blockers, and mentions that may need cutting before the video runs off TikTok."}},"required":["grade","score","singleProduct","flags"],"description":"Ad Potential, for brands with the licensed_content_priority feature. Null when not analysed."},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"editedCuts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Licensed Content id: the licensedContentId that download, tag, and Meta operations take."},"brandId":{"type":"string","description":"The brand that holds the rights."},"requestId":{"type":"number","description":"The usage rights request whose terms govern this content."},"videoId":{"type":"string","description":"The licensed video: a TikTok video id, euka_v_… for a file uploaded in the Euka creator app, ig_… for an Instagram import, or euka_cut_… for an edited cut the brand uploaded."},"sourceLicensedContentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set on an edited cut: the Licensed Content id of the original it was edited from. A cut is paid and capped under its original’s terms. Null on originals."},"sourceVideoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Set on an edited cut: the videoId of the original it was edited from, which Meta ads made from the cut end their name with. Null on originals."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The brand’s name for this content, e.g. \"Cut 2\" for an edited cut. Null when the brand has not named it."},"creatorHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The creator’s TikTok handle, or their name from the Euka creator app when they have none. Null when unknown."},"source":{"enum":["per-content","enrollment","marketplace","contest","spark","retainer"],"type":"string","description":"How the rights were obtained: per-content (negotiated for this video), enrollment (the creator’s enrollment in the brand’s creator program), marketplace (an approved Creator Marketplace submission), spark (a Spark code that allows promotion), retainer, or contest (a contest, and any other rights granted without an offer)."},"tiktokSyncStatus":{"enum":["none","processing","ready","failed"],"type":"string","description":"Progress of Euka’s copy of the TikTok video file, which the tiktok download and Meta uploads use: none (not started), processing, ready, or failed (the copy can be retried). Files uploaded in the Euka creator app are ready."},"mediaType":{"enum":["video","image"],"type":"string","description":"image when the stored file is an image, otherwise video."},"assets":{"type":"object","properties":{"tiktokAvailable":{"type":"boolean","description":"Whether Euka’s copy of the TikTok video is ready to download (asset tiktok)."},"originalAvailable":{"type":"boolean","description":"Whether an original file from the creator has been received (asset original). False while an upload has started but no bytes have arrived."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Thumbnail image URL. Null when there is none."},"mimeType":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"MIME type of the stored file, such as video/mp4. Null when no file is stored."},"hd1080":{"type":"boolean","description":"Whether the file Euka serves for downloads and Meta is at least 1080p, as read from the file (short side of 1080 pixels or more). False for smaller files and for files not yet measured."}},"required":["tiktokAvailable","originalAvailable","thumbnailUrl","mimeType","hd1080"],"description":"Which files Euka holds for this content."},"enrollmentId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The creator program enrollment the rights came from. Null otherwise."},"partnershipEligible":{"type":"boolean","description":"Whether the creator has granted Meta partnership-ad permission, so an ad from this content can run with their Instagram account."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the video was posted on TikTok. Null for uploads, Instagram imports, or when unknown."},"tiktokRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok Shop GMV of the video in the shop’s currency, as of Euka’s last update; may be Euka’s estimate for a video not read from a connected shop. Null when unknown or not a TikTok video."},"tiktokViews":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime TikTok views as of Euka’s last update. Null when unknown or not a TikTok video."},"linkedAdCount":{"type":"number","description":"Synced Meta ads linked to this content, including ads it shares with other videos. 0 when none."},"uploadedToMeta":{"type":"boolean","description":"Whether Euka has uploaded this content’s file to one of the brand’s Meta ad accounts. It does not mean an ad exists."},"metaAdSpend":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Always null in this result; Meta spend is reported separately."},"metaAdSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Always null in this result; Meta sales are reported separately."},"favorite":{"type":"boolean","description":"Whether the brand starred this content."},"product":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title. Null when Euka does not have it."},"photoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product image URL; the image may be missing. Null when unavailable."}},"required":["id","title","photoUrl"]},{"type":"null"}],"description":"The TikTok Shop product the video promotes. Null when unknown or not a TikTok video."},"terms":{"type":"object","properties":{"duration":{"anyOf":[{"type":"object","properties":{"kind":{"const":"months"},"months":{"type":"number","description":"Length of the license in months, counted from when the creator accepts."}},"required":["kind","months"]},{"type":"object","properties":{"kind":{"const":"perpetual"}},"required":["kind"]}],"description":"How long the rights last: a number of months, or perpetual (no end date)."},"compensation":{"anyOf":[{"type":"object","properties":{"kind":{"const":"free"}},"required":["kind"]},{"type":"object","properties":{"kind":{"const":"flatFee"},"amount":{"type":"object","properties":{"amount":{"type":"number","description":"Fee in whole currency units (dollars for USD), not cents."},"currency":{"type":"string","description":"ISO 4217 currency code, such as USD."}},"required":["amount","currency"],"description":"One-time fee paid to the creator for the rights."}},"required":["kind","amount"]},{"type":"object","properties":{"kind":{"const":"percentage"},"ratePercent":{"type":"number","description":"Commission rate, as a percentage (0–100) of the basis."},"basis":{"enum":["metaAdSpend","metaWebsiteSales","metaAttributedSales","tripleWhaleLastClickSales","tripleWhaleFirstClickSales"],"type":"string","description":"What a percentage is taken of, across the ads that use the video: metaAdSpend (Meta ad spend), metaWebsiteSales (website purchases Meta attributes to the ads), metaAttributedSales (all purchases Meta attributes to the ads), tripleWhaleLastClickSales or tripleWhaleFirstClickSales (orders Triple Whale credits to the ads as the last or first click)."},"maxPayout":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Cap in major currency units (dollars for USD), not cents."},"currency":{"type":"string","description":"ISO 4217 currency code, such as USD."}},"required":["amount","currency"]},{"type":"null"}],"description":"Most the creator can earn in total under these terms, over the whole license. Null means no cap."}},"required":["kind","ratePercent","basis","maxPayout"]}],"description":"What the creator is paid: free (nothing), flatFee (a one-time amount), or percentage (a share of the basis, calculated for each 7-day payout period)."}},"required":["duration","compensation"],"description":"Current license terms. With tiered commission (commissionIsTiered), the rate shown is not the rate paid."},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the license ends. Null when it has no end date. Expired content is still listed."},"grantedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the rights became final: payment of a flat fee, or the creator’s acceptance. Null for enrollment rights and rights granted without an offer, whose grant time is createdAt."},"commissionIsTiered":{"type":"boolean","description":"Whether the brand’s creator program pays this license by creator tier, so the brand’s current tier table sets the rate."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","description":"Tag color as saved by the brand, usually a hex code such as #1890ff."}},"required":["id","name","color"]},"description":"The brand’s tags on this content, A to Z."},"note":{"anyOf":[{"type":"object","properties":{"text":{"type":"string","description":"The note. Empty when only a status is set."},"status":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","description":"Status color, a hex code such as #D89614."}},"required":["id","name","color"]},{"type":"null"}]},"updatedAt":{"type":"string","description":"When the note was last saved."},"updatedBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the teammate who last saved it. Null when unknown."}},"required":["text","status","updatedAt","updatedBy"]},{"type":"null"}],"description":"The brand’s current note and status on this content. Null when it has none."},"priority":{"anyOf":[{"type":"object","properties":{"grade":{"enum":["a","b","c","d","pending"],"type":"string","description":"Ad Potential grade: a (best) to d, from common content-quality checks plus Creative Coach insights when the product has them. Readiness blockers do not change it; they are flags. pending: not analysed yet."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Ad Potential score 0-100 behind the grade. Null until analysed."},"common":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The common content checks part of the score."},"coach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"The Creative Coach part of the score; null when the product has no tested insight that goes with higher spend, so the score is the common checks alone."},"singleProduct":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether no product other than the promoted one is used or shown on camera. Null until analysed."},"flags":{"type":"array","items":{"type":"object","properties":{"key":{"enum":["personal_info_visible","wrong_or_missing_product","competitor_product_featured","brand_rule","double_discount","slideshow_or_stock","tiktok_shop","discount"],"type":"string","description":"tiktok_shop: TikTok Shop is said or shown. discount: a discount or deal is said or shown. The rest are failed readiness blockers: personal_info_visible, wrong_or_missing_product, competitor_product_featured, brand_rule, double_discount, slideshow_or_stock."},"startSeconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Where in the video it is first observed."}},"required":["key","startSeconds"]},"description":"Failed readiness blockers, and mentions that may need cutting before the video runs off TikTok."}},"required":["grade","score","singleProduct","flags"],"description":"Ad Potential, for brands with the licensed_content_priority feature. Null when not analysed."},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","brandId","requestId","videoId","sourceLicensedContentId","sourceVideoId","title","creatorHandle","source","tiktokSyncStatus","mediaType","assets","enrollmentId","partnershipEligible","postedAt","tiktokRevenue","tiktokViews","linkedAdCount","uploadedToMeta","metaAdSpend","metaAdSales","favorite","product","terms","expiresAt","grantedAt","commissionIsTiered","tags","note","priority","createdAt","updatedAt"]},"description":"Edited cuts the brand uploaded of this content, oldest first. Cuts are never listed as items of their own."}},"required":["id","brandId","requestId","videoId","sourceLicensedContentId","sourceVideoId","title","creatorHandle","source","tiktokSyncStatus","mediaType","assets","enrollmentId","partnershipEligible","postedAt","tiktokRevenue","tiktokViews","linkedAdCount","uploadedToMeta","metaAdSpend","metaAdSales","favorite","product","terms","expiresAt","grantedAt","commissionIsTiered","tags","note","priority","createdAt","updatedAt","editedCuts"]},"description":"Licensed Content on this page. Content from an ended creator program is left out."},"total":{"type":"number","description":"Items matching the filters, across all pages."},"page":{"type":"number","description":"Page returned, starting at 1."},"pageSize":{"type":"number","description":"Maximum items per page."}},"required":["items","total","page","pageSize"]}}}}},"security":[{"openApiKey":[]}]}},"/licensed-content/{licensedContentId}/download-url":{"get":{"operationId":"getLicensedContentDownloadUrl","summary":"Get a download link","description":"Returns a signed link to a file Euka stores for one Licensed Content item. Check assets.tiktokAvailable or assets.originalAvailable in the search result first: a missing file returns 404, and content whose license has ended returns 403. Request a new link once expiresInSeconds has passed.","tags":["Licensed Content"],"parameters":[{"name":"licensedContentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string"},"allowEmptyValue":true,"allowReserved":true},{"name":"asset","in":"query","required":true,"schema":{"enum":["tiktok","original"],"type":"string","description":"tiktok: Euka’s copy of the TikTok video; original: the file the creator uploaded."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"downloadUrl":{"type":"string","description":"Signed link that downloads the requested file (Euka’s TikTok copy or the creator’s original); anyone with it can download until it expires."},"expiresInSeconds":{"type":"number","description":"Seconds until downloadUrl expires."}},"required":["downloadUrl","expiresInSeconds"]}}}}},"security":[{"openApiKey":[]}]}},"/licensed-content/tags":{"get":{"operationId":"listLicensedContentTags","summary":"List Licensed Content tags","description":"Returns every tag the brand has created for its Licensed Content. Pass their ids as filter.tagIds when searching Licensed Content.","tags":["Licensed Content"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string"},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"brandId":{"type":"string","description":"The brand that owns the tag."},"name":{"type":"string"},"color":{"type":"string","description":"Tag color as saved by the brand, usually a hex code such as #1890ff."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","brandId","name","color","createdAt","updatedAt"]},"description":"Every Licensed Content tag the brand has, newest first."}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/brands":{"get":{"operationId":"listSocialIntelligenceBrands","summary":"List top brands","description":"Returns a cursor-paginated ranking of TikTok Shop brands for a supported market.","tags":["Social Intelligence"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor returned by the previous page."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":20,"description":"Maximum number of brands to return. Defaults to 20."},"allowEmptyValue":true,"allowReserved":true},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive name or title search. Omit to return top items."},"allowEmptyValue":true,"allowReserved":true},{"name":"categoryIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"description":"Category ids returned by Social Intelligence category endpoints. Legacy top-level ids 1–25 are also accepted. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD."},"preset":{"enum":["last90Day","last180Day","last365Day"],"type":"string","description":"Rolling window ending on the latest data day, for ranges over 31 days. startDate and endDate must span the same number of days."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"const":"last30dSales","default":"last30dSales","description":"Legacy selector retained for compatibility. Rankings use requested-period GMV."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]},"currencyCode":{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},"salesMetric":{"enum":["last30dSales","totalSales"],"type":"string","description":"Legacy field selector retained for compatibility. Period-scoped market responses use last30dSales as an alias for requested-period GMV."},"categoryId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Primary category id."},"categoryNames":{"type":"array","items":{"type":"string"},"description":"Category names reported by the active data source."},"shopType":{"anyOf":[{"enum":["BRAND","RETAILER"],"type":"string"},{"type":"null"}],"description":"Shop ownership type reported by the active data source."},"productCount":{"type":"number","description":"Product count reported by the active data source."},"totalSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime GMV in currencyCode, when available."},"last30dSales":{"type":"number","description":"Legacy field. Period-scoped market responses contain GMV during the requested metric period."},"gmv":{"type":"number","description":"GMV during the requested metric period."},"averageProductPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Average product price in currencyCode."},"unitsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units sold during the requested period, when available."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when not reported, which is always the case when reading a single brand."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"isFavoritable":{"type":"boolean","description":"Whether this brand can be added to Social Intelligence favorites."},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last source refresh time in ISO 8601 format."}},"required":["id","name","region","currencyCode","salesMetric","categoryId","productCount","totalSales","last30dSales","gmv","averageProductPrice","unitsSold","gmvGrowthRate","imageUrl","isFavoritable","updatedAt"]},"description":"TikTok Shop sellers (brands) in the market, ranked by GMV for the requested period (the last 30 days unless dateRange is set), highest first; with a query, an exact name match comes first. Figures are market estimates."},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string","description":"Opaque cursor returned by the previous page."},{"type":"null"}]},"hasNextPage":{"type":"boolean","description":"Whether another page follows. Pass nextCursor as cursor to fetch it."}},"required":["nextCursor","hasNextPage"],"description":"Cursor paging for this list."}},"required":["items","pageInfo"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/brands/{sellerId}":{"get":{"operationId":"getSocialIntelligenceBrand","summary":"Get a brand","description":"Returns one Social Intelligence brand by seller id.","tags":["Social Intelligence"],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"string","description":"TikTok Shop seller id, as returned in `brand.id` and `sellerId`."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]},"currencyCode":{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},"salesMetric":{"enum":["last30dSales","totalSales"],"type":"string","description":"Legacy field selector retained for compatibility. Period-scoped market responses use last30dSales as an alias for requested-period GMV."},"categoryId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Primary category id."},"categoryNames":{"type":"array","items":{"type":"string"},"description":"Category names reported by the active data source."},"shopType":{"anyOf":[{"enum":["BRAND","RETAILER"],"type":"string"},{"type":"null"}],"description":"Shop ownership type reported by the active data source."},"productCount":{"type":"number","description":"Product count reported by the active data source."},"totalSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime GMV in currencyCode, when available."},"last30dSales":{"type":"number","description":"Legacy field. Period-scoped market responses contain GMV during the requested metric period."},"gmv":{"type":"number","description":"GMV during the requested metric period."},"averageProductPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Average product price in currencyCode."},"unitsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units sold during the requested period, when available."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when not reported, which is always the case when reading a single brand."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"isFavoritable":{"type":"boolean","description":"Whether this brand can be added to Social Intelligence favorites."},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last source refresh time in ISO 8601 format."},"creatorCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Affiliate creators who worked with the shop in the requested period (the last 30 days unless dateRange is set), a market estimate. Null when the market data has none."},"videoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Videos reported for the requested period."},"gmvTrend":{"type":"array","items":{"type":"number"},"description":"Daily GMV values for the requested period."}},"required":["id","name","region","currencyCode","salesMetric","categoryId","productCount","totalSales","last30dSales","gmv","averageProductPrice","unitsSold","gmvGrowthRate","imageUrl","isFavoritable","updatedAt","creatorCount","videoCount","gmvTrend"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/products":{"get":{"operationId":"listSocialIntelligenceProducts","summary":"List top products","description":"Returns a cursor-paginated ranking of TikTok Shop products with optional seller, category, and title filters.","tags":["Social Intelligence"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor returned by the previous page."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":20,"description":"Maximum number of products to return. Defaults to 20."},"allowEmptyValue":true,"allowReserved":true},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive name or title search. Omit to return top items."},"allowEmptyValue":true,"allowReserved":true},{"name":"sellerIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Entity ids to include. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"categoryIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"description":"Category ids returned by Social Intelligence category endpoints. Legacy top-level ids 1–25 are also accepted. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD."},"preset":{"enum":["last90Day","last180Day","last365Day"],"type":"string","description":"Rolling window ending on the latest data day, for ranges over 31 days. startDate and endDate must span the same number of days."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"launchedWithinDays","in":"query","required":false,"schema":{"anyOf":[{"const":3},{"const":7},{"const":30}],"description":"Only return products first listed on TikTok Shop within this many days. Supported windows: 3, 7, or 30 days."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"const":"last30dSales","default":"last30dSales","description":"Legacy selector retained for compatibility. Rankings use requested-period GMV."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop product id."},"sellerId":{"type":"string","description":"TikTok Shop seller id."},"categoryId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product category id."},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]}},"required":["id","name","imageUrl","region"]},{"type":"null"}],"description":"TikTok Shop seller (brand) that sells the product."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}],"description":"Category id and name. Null for market data, which leaves it unset; the product detail gives categoryId instead."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title."},"currencyCode":{"anyOf":[{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},{"type":"null"}]},"salesMetric":{"enum":["last30dSales","totalSales"],"type":"string","description":"Legacy field selector retained for compatibility. Period-scoped market responses use last30dSales as an alias for requested-period GMV."},"price":{"type":"object","properties":{"current":{"type":"number","description":"Current selling price."},"original":{"type":"number","description":"Original listed price."},"shipping":{"type":"number","description":"Recorded shipping fee."}},"required":["current","original","shipping"],"description":"Product prices in the record currencyCode."},"soldCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime units sold, when available."},"last30dSoldCount":{"type":"number","description":"Legacy field. Period-scoped market responses contain units sold during the requested metric period."},"totalSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime GMV in currencyCode, when available."},"last30dSales":{"type":"number","description":"Legacy field. Period-scoped market responses contain GMV during the requested metric period."},"gmv":{"type":"number","description":"GMV during the requested metric period."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when not reported, which is always the case when reading a single product."},"unitsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units sold during the requested metric period."},"averageSellingPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV per unit sold during the requested metric period."},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether a locally recorded product is currently active."},"launchedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Date the product was first listed on TikTok Shop, in YYYY-MM-DD format."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public product image URL."},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last source refresh time in ISO 8601 format."}},"required":["id","sellerId","categoryId","brand","category","title","currencyCode","salesMetric","price","soldCount","last30dSoldCount","totalSales","last30dSales","gmv","gmvGrowthRate","unitsSold","averageSellingPrice","active","launchedAt","imageUrl","updatedAt"]},"description":"TikTok Shop products in the market, ranked by GMV for the requested period (the last 30 days unless dateRange is set), highest first. Figures are market estimates."},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string","description":"Opaque cursor returned by the previous page."},{"type":"null"}]},"hasNextPage":{"type":"boolean","description":"Whether another page follows. Pass nextCursor as cursor to fetch it."}},"required":["nextCursor","hasNextPage"],"description":"Cursor paging for this list."}},"required":["items","pageInfo"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/products/{productId}":{"get":{"operationId":"getSocialIntelligenceProduct","summary":"Get a product","description":"Returns selected-period sales, trend, creator, video, and livestream signals for one product, plus its listing description when captured.","tags":["Social Intelligence"],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop product id."},"sellerId":{"type":"string","description":"TikTok Shop seller id."},"categoryId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Product category id."},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]}},"required":["id","name","imageUrl","region"]},{"type":"null"}],"description":"TikTok Shop seller (brand) that sells the product."},"category":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}],"description":"Category id and name. Null for market data, which leaves it unset; the product detail gives categoryId instead."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title."},"currencyCode":{"anyOf":[{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},{"type":"null"}]},"salesMetric":{"enum":["last30dSales","totalSales"],"type":"string","description":"Legacy field selector retained for compatibility. Period-scoped market responses use last30dSales as an alias for requested-period GMV."},"price":{"type":"object","properties":{"current":{"type":"number","description":"Current selling price."},"original":{"type":"number","description":"Original listed price."},"shipping":{"type":"number","description":"Recorded shipping fee."}},"required":["current","original","shipping"],"description":"Product prices in the record currencyCode."},"soldCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime units sold, when available."},"last30dSoldCount":{"type":"number","description":"Legacy field. Period-scoped market responses contain units sold during the requested metric period."},"totalSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Recorded lifetime GMV in currencyCode, when available."},"last30dSales":{"type":"number","description":"Legacy field. Period-scoped market responses contain GMV during the requested metric period."},"gmv":{"type":"number","description":"GMV during the requested metric period."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when not reported, which is always the case when reading a single product."},"unitsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units sold during the requested metric period."},"averageSellingPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV per unit sold during the requested metric period."},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether a locally recorded product is currently active."},"launchedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Date the product was first listed on TikTok Shop, in YYYY-MM-DD format."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public product image URL."},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last source refresh time in ISO 8601 format."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Listing description text from the TikTok Shop product page. Null when Euka has not captured it."},"analysis":{"type":"object","properties":{"hooks":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Hooks (attention-grabbing openings) that top videos use, from Euka’s analysis. Empty when there is none."},"sellingPoints":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Selling points that top videos make, from Euka’s analysis. Empty when there is none."},"videoFormats":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Video formats that top videos use, from Euka’s analysis. Empty when there is none."}},"required":["hooks","sellingPoints","videoFormats"],"description":"Existing Euka creative analysis for this product, when available."},"creatorCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Creators who promoted the product in the requested period (the last 30 days unless dateRange is set), a market estimate. Null when the market data has none."},"videoCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Videos reported for the requested period."},"livestreamCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Livestreams that promoted the product in the requested period, a market estimate. Null when the market data has none."},"gmvTrend":{"type":"array","items":{"type":"number"},"description":"Daily GMV values for the requested period."}},"required":["id","sellerId","categoryId","brand","category","title","currencyCode","salesMetric","price","soldCount","last30dSoldCount","totalSales","last30dSales","gmv","gmvGrowthRate","unitsSold","averageSellingPrice","active","launchedAt","imageUrl","updatedAt","description","analysis","creatorCount","videoCount","livestreamCount","gmvTrend"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/categories":{"get":{"operationId":"listSocialIntelligenceCategories","summary":"List top categories","description":"Returns top-level categories (plus subcategories with includeSubcategories) ranked by GMV for the selected period in a supported market.","tags":["Social Intelligence"],"parameters":[{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive name or title search. Omit to return top items."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"enum":["last7Day","last30Day"],"type":"string","default":"last30Day","description":"Category metric period."},"allowEmptyValue":true,"allowReserved":true},{"name":"includeSubcategories","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"enum":["true","false"],"type":"string"}],"description":"Also return level-2 subcategories (with parentId), each listed right after its parent. Only categories with GMV are listed. Subcategory ids work with brands.list, products.list, trendingVideos.list and videos.list with a dateRange, not with categories.get, videos.list without a dateRange, or exports."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"TikTok Shop category id."},"name":{"type":"string","description":"Category name."},"currencyCode":{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},"gmv":{"type":"number","description":"Category GMV for the requested period (the last 30 days unless dateRange is last7Day), in currencyCode; a market estimate."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when the market data has none."},"unitsSold":{"type":"number","description":"Units sold in the category in the requested period, a market estimate."},"averageGmvPerShop":{"type":"number","description":"Average GMV per shop selling in the category in the requested period, in currencyCode; a market estimate."},"level":{"anyOf":[{"const":1},{"const":2}],"description":"TikTok Shop category level: 1 = top level, 2 = subcategory."},"parentId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Level-1 category id for a subcategory; null for a top-level category."}},"required":["id","name","currencyCode","gmv","gmvGrowthRate","unitsSold","averageGmvPerShop","level","parentId"]},"description":"Top-level TikTok Shop categories in the market, ranked by GMV for the requested period, highest first. With includeSubcategories, each parent is followed by its subcategories (level 2, parentId set), ranked by GMV within the parent. Figures are market estimates."},"subcategoriesComplete":{"type":"boolean","description":"Present only when includeSubcategories is requested. false while some parents' subcategories are still being loaded; request again shortly."}},"required":["items"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/categories/{categoryId}":{"get":{"operationId":"getSocialIntelligenceCategory","summary":"Get a category","description":"Returns selected-period GMV, sales, shop, product, and trend metrics for one category.","tags":["Social Intelligence"],"parameters":[{"name":"categoryId","in":"path","required":true,"schema":{"type":"number","description":"Category id returned by Social Intelligence category endpoints. Legacy top-level ids 1–25 are also accepted."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"enum":["last7Day","last30Day"],"type":"string","default":"last30Day","description":"Category metric period."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number","description":"TikTok Shop category id."},"name":{"type":"string","description":"Category name."},"currencyCode":{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},"gmv":{"type":"number","description":"Category GMV for the requested period (the last 30 days unless dateRange is last7Day), in currencyCode; a market estimate."},"gmvGrowthRate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"GMV change versus the preceding period of the same length, as a percentage (12.5 means +12.5%). Null when the market data has none."},"unitsSold":{"type":"number","description":"Units sold in the category in the requested period, a market estimate."},"averageGmvPerShop":{"type":"number","description":"Average GMV per shop selling in the category in the requested period, in currencyCode; a market estimate."},"analysis":{"type":"object","properties":{"hooks":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Hooks (attention-grabbing openings) that top videos use, from Euka’s analysis. Empty when there is none."},"sellingPoints":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Selling points that top videos make, from Euka’s analysis. Empty when there is none."},"videoFormats":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Short name of the hook, selling point or video format, or a numbered placeholder such as Hook 1 when the analysis gives no name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tips for using this video format. Null for hooks and selling points."},"examples":{"type":"array","items":{"type":"object","properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"TikTok id of the example video. Null when the analysis gives none."},"phrase":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The example video’s own words for this hook or selling point. Null for video formats, which give an explanation instead."},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the example video uses this video format. Null for hooks and selling points."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the example video, as Euka last recorded them. Null when not available, as in category analyses."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the example video was posted, in ISO 8601 format. Null when not available, as in category analyses."},"creatorAvatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Profile image URL of the creator who posted the example video. Null when not available, as in category analyses."}},"required":["videoId","phrase","explanation"]},"description":"Videos that show this hook, selling point or video format."}},"required":["label","description","guidance","examples"]},"description":"Video formats that top videos use, from Euka’s analysis. Empty when there is none."}},"required":["hooks","sellingPoints","videoFormats"],"description":"Existing Euka creative analysis for this category, when available."},"localCategoryId":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Euka’s own top-level category id (1–25) for this category, which Euka’s creator and video filters use. Null when Euka has no matching category."},"shopCount":{"type":"number","description":"Shops with sales in the category in the requested period, a market estimate."},"activeProductCount":{"type":"number","description":"Active products reported for the requested period."},"gmvTrend":{"type":"array","items":{"type":"number"},"description":"Daily GMV values for the requested period."}},"required":["id","name","currencyCode","gmv","gmvGrowthRate","unitsSold","averageGmvPerShop","analysis","localCategoryId","shopCount","activeProductCount","gmvTrend"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/videos":{"get":{"operationId":"listSocialIntelligenceVideos","summary":"Discover videos","description":"Searches and ranks TikTok Shop videos with bounded market, entity, date, performance, creator demographic, and post-fulfillment filters. Date filters are inclusive YYYY-MM-DD values.","tags":["Social Intelligence"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Opaque cursor returned by the previous page."},"allowEmptyValue":true,"allowReserved":true},{"name":"limit","in":"query","required":false,"schema":{"type":"number","default":20,"description":"Maximum number of items to return. Defaults to 20."},"allowEmptyValue":true,"allowReserved":true},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true},{"name":"region","in":"query","required":false,"schema":{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"Market to read. Defaults to the market of the brand's TikTok Shop store."},"allowEmptyValue":true,"allowReserved":true},{"name":"query","in":"query","required":false,"schema":{"type":"string","description":"Content keywords that further narrow any entity filters. Without dateRange, searches captions only; with dateRange, uses provider keyword filtering. For product/brand lookup, use entity IDs and omit query."},"allowEmptyValue":true,"allowReserved":true},{"name":"sellerIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Entity ids to include. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"productIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Entity ids to include. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"categoryIds","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"description":"Category ids returned by Social Intelligence category endpoints. Legacy top-level ids 1–25 are also accepted. Maximum 50."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"dateRange","in":"query","required":false,"schema":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date in YYYY-MM-DD."},"endDate":{"type":"string","description":"Inclusive end date in YYYY-MM-DD."}},"required":["startDate","endDate"]},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"postedAfter","in":"query","required":false,"schema":{"type":"string","description":"Inclusive earliest post date in YYYY-MM-DD format."},"allowEmptyValue":true,"allowReserved":true},{"name":"postedBefore","in":"query","required":false,"schema":{"type":"string","description":"Inclusive latest post date in YYYY-MM-DD format."},"allowEmptyValue":true,"allowReserved":true},{"name":"minViews","in":"query","required":false,"schema":{"type":"number"},"allowEmptyValue":true,"allowReserved":true},{"name":"maxViews","in":"query","required":false,"schema":{"type":"number"},"allowEmptyValue":true,"allowReserved":true},{"name":"minRevenue","in":"query","required":false,"schema":{"type":"number"},"allowEmptyValue":true,"allowReserved":true},{"name":"maxRevenue","in":"query","required":false,"schema":{"type":"number"},"allowEmptyValue":true,"allowReserved":true},{"name":"genders","in":"query","required":false,"schema":{"type":"array","items":{"enum":["male","female","other","undecided"],"type":"string"},"description":"Creator genders to include."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"languages","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Creator language codes, such as en or es."},"style":"deepObject","explode":true,"allowEmptyValue":true,"allowReserved":true},{"name":"minPostRate","in":"query","required":false,"schema":{"type":"number","description":"Minimum creator post-fulfillment rate percentage."},"allowEmptyValue":true,"allowReserved":true},{"name":"maxPostRate","in":"query","required":false,"schema":{"type":"number","description":"Maximum creator post-fulfillment rate percentage."},"allowEmptyValue":true,"allowReserved":true},{"name":"sortBy","in":"query","required":false,"schema":{"enum":["revenue","views","postedAt"],"type":"string","default":"revenue","description":"Ranking metric. revenue means attributed GMV."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"TikTok video id."},"isEukaMapped":{"type":"boolean","description":"Whether Euka has indexed the video. videos.get resolves only indexed ids; provider-only items carry ranking metrics but no transcript or insight."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Video caption."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Video post time in ISO 8601 format."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public thumbnail URL."},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public video URL when available."},"currencyCode":{"anyOf":[{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},{"type":"null"}]},"metrics":{"type":"object","properties":{"views":{"type":"number","description":"Recorded video views."},"likes":{"type":"number","description":"Recorded video likes."},"comments":{"type":"number","description":"Recorded comments."},"revenue":{"type":"number","description":"Attributed video GMV in the record currencyCode."},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units attributed to this video, when available."}},"required":["views","likes","comments","revenue","itemsSold"],"description":"The video’s numbers. Without dateRange: Euka’s recorded lifetime totals, in currencyCode. With dateRange: market estimates for those dates, in USD, with itemsSold null."},"creator":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Creator id: Euka’s creator id (same as uidShop) when Euka has indexed the creator, otherwise the TikTok creator id from the market data."},"uidShop":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Euka creator id. Null for provider-ranked videos with no indexed creator."},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s TikTok handle. Null when unknown."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s profile image URL. Null when unknown."},"followerCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Null when Euka has no follower count for the creator."}},"required":["id","uidShop","handle","name","avatarUrl","followerCount"]},{"type":"null"}],"description":"Creator who posted the video. Null when unknown."},"product":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title, as Euka recorded it. Null when unknown."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product image URL. Null when none is available."}},"required":["id","title","imageUrl"]},{"type":"null"}],"description":"TikTok Shop product the video promotes, from Euka’s records. Null when Euka has none linked, as for videos found only in the market data (isEukaMapped false)."},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]}},"required":["id","name","imageUrl","region"]},{"type":"null"}],"description":"TikTok Shop seller (brand) of that product, from Euka’s records. Null when Euka has none linked, as for videos found only in the market data (isEukaMapped false)."}},"required":["id","isEukaMapped","description","postedAt","thumbnailUrl","videoUrl","currencyCode","metrics","creator","product","brand"]},"description":"Videos on this page, ranked by sortBy, highest or newest first. Without dateRange they come from Euka’s index; with dateRange they are the market data’s ranking for those dates."},"pageInfo":{"type":"object","properties":{"nextCursor":{"anyOf":[{"type":"string","description":"Opaque cursor returned by the previous page."},{"type":"null"}]},"hasNextPage":{"type":"boolean","description":"Whether another page follows. Pass nextCursor as cursor to fetch it."}},"required":["nextCursor","hasNextPage"],"description":"Cursor paging for this list."}},"required":["items","pageInfo"]}}}}},"security":[{"openApiKey":[]}]}},"/social-intelligence/videos/{videoId}":{"get":{"operationId":"getSocialIntelligenceVideo","summary":"Get a video","description":"Returns one indexed TikTok Shop video with its caption, market metrics, creator, product, brand, transcript, and stored content insight. Only videos Euka has indexed can be read; unindexed ids return 404.","tags":["Social Intelligence"],"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string","description":"TikTok video id."}},{"name":"brandId","in":"query","required":true,"schema":{"type":"string","description":"Euka brand the read is made for."},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"TikTok video id."},"isEukaMapped":{"type":"boolean","description":"Whether Euka has indexed the video. videos.get resolves only indexed ids; provider-only items carry ranking metrics but no transcript or insight."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Video caption."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Video post time in ISO 8601 format."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public thumbnail URL."},"videoUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Playable video URL resolved live from TikTok; short-lived, fetch again rather than storing it. Null when no playable rendition exists."},"currencyCode":{"anyOf":[{"type":"string","description":"ISO 4217 currency code for monetary fields in this record."},{"type":"null"}]},"metrics":{"anyOf":[{"type":"object","properties":{"views":{"type":"number","description":"Recorded video views."},"likes":{"type":"number","description":"Recorded video likes."},"comments":{"type":"number","description":"Recorded comments."},"revenue":{"type":"number","description":"Attributed video GMV in the record currencyCode."},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Units attributed to this video, when available."}},"required":["views","likes","comments","revenue","itemsSold"]},{"type":"null"}],"description":"Figures from the market data, in USD. Views, revenue, and itemsSold cover the last 365 days, which is the whole life of a video posted within a year; likes and comments are totals to date. Null when the market data has no record of the video in its seller's market."},"creator":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Creator id: Euka’s creator id (same as uidShop) when Euka has indexed the creator, otherwise the TikTok creator id from the market data."},"uidShop":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Euka creator id. Null for provider-ranked videos with no indexed creator."},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s TikTok handle. Null when unknown."},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s profile image URL. Null when unknown."},"followerCount":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Null when Euka has no follower count for the creator."}},"required":["id","uidShop","handle","name","avatarUrl","followerCount"]},{"type":"null"}],"description":"Creator who posted the video. Null when unknown."},"product":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title, as Euka recorded it. Null when unknown."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product image URL. Null when none is available."}},"required":["id","title","imageUrl"]},{"type":"null"}],"description":"TikTok Shop product the video promotes, from Euka’s records. Null when Euka has none linked, as for videos found only in the market data (isEukaMapped false)."},"brand":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"TikTok Shop seller id."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brand or seller display name."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public brand image URL."},"region":{"anyOf":[{"enum":["US","UK","FR","DE","ES","IE","IT","JP"],"type":"string","description":"TikTok Shop market used to scope Social Intelligence data."},{"type":"string"}]}},"required":["id","name","imageUrl","region"]},{"type":"null"}],"description":"TikTok Shop seller (brand) of that product, from Euka’s records. Null when Euka has none linked, as for videos found only in the market data (isEukaMapped false)."},"transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Spoken-word transcript when Euka has transcribed the video. Null means no transcript is stored."},"contentInsight":{"anyOf":[{"type":"object","properties":{"status":{"const":"available"},"value":{"type":"object","properties":{"keyIdea":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The video’s key idea, concept or format. Null when the analysis has none."},"hooks":{"type":"array","items":{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Short name for the hook. Null when the analysis stored only its wording."},"phrasing":{"type":"string","description":"The hook as worded in the video, per the analysis."}},"required":["label","phrasing"]},"description":"Attention-grabbing hooks the analysis found, mostly from the video’s opening."},"sellingPoints":{"type":"array","items":{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Short name for the selling point. Null when the analysis stored only its wording."},"phrasing":{"type":"string","description":"The selling point as worded in the video, per the analysis."}},"required":["label","phrasing"]},"description":"Product selling points the analysis found in the video."},"callToAction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What the video asks viewers to do, with its offer and wording. Null when the analysis has none."},"targetAudience":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Audiences the analysis says the video targets. Null when it has none."},"engagementTechniques":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Engagement techniques the analysis found. Null when it has none."},"transcript":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Transcript stored with this analysis. Null when it has none; prefer the video’s top-level transcript, which also covers videos transcribed separately."},"sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Overall sentiment the analysis assigned, usually positive, mixed or negative. Null when it has none."}},"required":["keyIdea","hooks","sellingPoints","callToAction","targetAudience","engagementTechniques","transcript","sentiment"],"additionalProperties":false,"description":"Euka’s stored analysis of the video: key idea, hooks, selling points, call to action, audience, engagement techniques, transcript and sentiment."}},"required":["status","value"],"additionalProperties":false},{"type":"object","properties":{"status":{"const":"missing"},"requestEligible":{"type":"boolean","description":"Whether analysis can be requested for this video. False for market videos read through Social Intelligence."}},"required":["status","requestEligible"],"additionalProperties":false},{"type":"object","properties":{"status":{"const":"unavailable"},"reason":{"enum":["tiktokDataMissing","mediaUnavailable","providerBlocked","providerSafetyBlocked","providerVisualSafetyBlocked","providerRecitationBlocked","providerProhibitedContentBlocked","providerRestrictedTermsBlocked","providerSensitiveInformationBlocked","providerOtherBlocked","enrichmentFailed"],"type":"string","description":"Why the video cannot be analyzed. tiktokDataMissing: TikTok returned no data for the video; mediaUnavailable: the video file could not be downloaded; enrichmentFailed: the analysis failed. The provider values mean the AI model’s content filter stopped the analysis, named by filter category (providerBlocked when the category is unknown); they name the filter, not a finding about the video."}},"required":["status","reason"],"additionalProperties":false}],"description":"Stored Euka content analysis. Market videos cannot be analyzed on request, so a missing insight reports requestEligible: false."}},"required":["id","isEukaMapped","description","postedAt","thumbnailUrl","videoUrl","currencyCode","metrics","creator","product","brand","transcript","contentInsight"]}}}}},"security":[{"openApiKey":[]}]}},"/videos/search":{"post":{"operationId":"searchVideos","summary":"Search brand videos","description":"Search videos for a connected brand. For lifetime attributed GMV and items sold for specific TikTok videos, set scope.kind to lifetime and scope.filter.videoIds to up to 100 video IDs. Results default to 20 per page: set pageSize to 100 to fetch all matching IDs in one page, or increment page while pageInfo.hasNextPage is true. Do not combine exact lifetime IDs with other filters. Lifetime metrics are stored values as of the last sync, not live TikTok reads; null means unavailable. Use commerceWindow for sales earned within a date range, regardless of when the videos were posted. Paid performance, when present, covers a separate trailing-year window.","tags":["Videos"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brandId":{"type":"string","description":"Euka brand UUID."},"scope":{"anyOf":[{"type":"object","properties":{"kind":{"const":"lifetime"},"filter":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string","description":"Stored creator video ID; treat this value as opaque."}},"query":{"type":"string"},"productIds":{"type":"array","items":{"type":"string"}},"campaignIds":{"type":"array","items":{"type":"number"}},"creatorGenders":{"type":"array","items":{"type":"string"}},"creatorLanguages":{"type":"array","items":{"type":"string"}},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date."},"endDate":{"type":"string","description":"Inclusive end date."}},"required":["startDate","endDate"],"additionalProperties":false},"creatorTagIds":{"type":"array","items":{"type":"string"},"description":"Brand member tag ids from list_member_tags: a video matches when its creator, as a member of the brand, has any of them."},"durationBuckets":{"type":"array","items":{"enum":["lt15","15to30","30to60","gt60","unknown"],"type":"string"},"description":"Video lengths, any of: lt15 (under 15s), 15to30, 30to60 (60s included), gt60 (over 60s), unknown (no stored length). Slideshows have no length and match none."},"contentFormat":{"enum":["video","slideshow"],"type":"string","description":"video: videos only; slideshow: TikTok photo posts only, which ignores durationBuckets."},"hasUsageRightsRequest":{"type":"boolean","description":"true: only videos the brand has asked usage rights for, in any state; false: only videos with no request."},"creatorPostRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"The creator's estimated post rate, a percent from 0 to 100: how often they post after getting a sample."},"attributedGmv":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"views":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"likes":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"comments":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"itemsSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"paidSpend":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad spend of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidRoi":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"ROI TikTok reported (paid and organic sales over ad spend) of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductClicks":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product clicks of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidConversionRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Conversion rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidCostPerOrder":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Cost per order of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidOrders":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Orders of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidGrossRevenue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Gross revenue of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductImpressions":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product impressions of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductClickRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product click rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidClickRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad click rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRate2s":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched for 2 seconds, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRate6s":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched for 6 seconds, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP25":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 25%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP50":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 50%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP75":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 75%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP100":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to the end, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adItemsSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Items sold due to ads, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adRoi":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad ROI: ad sales over ad spend, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adSalesShare":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of the video's lifetime items sold that ads drove, in percent, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adSales":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad sales: the video's lifetime revenue times that share, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adCostPerItemSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"ACoS: ad spend over the items sold due to ads, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."}},"additionalProperties":false,"default":{}},"sort":{"type":"object","properties":{"field":{"enum":["attributedGmv","postedAt","views","likes","comments","itemsSold","paidSpend","paidRoi"],"type":"string"},"direction":{"enum":["asc","desc"],"type":"string"}},"required":["field","direction"],"additionalProperties":false,"default":{"field":"attributedGmv","direction":"desc"}}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"const":"commerceWindow"},"dateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date."},"endDate":{"type":"string","description":"Inclusive end date."}},"required":["startDate","endDate"],"additionalProperties":false},"filter":{"type":"object","properties":{"videoIds":{"type":"array","items":{"type":"string","description":"Stored creator video ID; treat this value as opaque."}},"query":{"type":"string"},"productIds":{"type":"array","items":{"type":"string"}},"campaignIds":{"type":"array","items":{"type":"number"}},"creatorGenders":{"type":"array","items":{"type":"string"}},"creatorLanguages":{"type":"array","items":{"type":"string"}},"postedDateRange":{"type":"object","properties":{"startDate":{"type":"string","description":"Inclusive start date."},"endDate":{"type":"string","description":"Inclusive end date."}},"required":["startDate","endDate"],"additionalProperties":false},"creatorTagIds":{"type":"array","items":{"type":"string"},"description":"Brand member tag ids from list_member_tags: a video matches when its creator, as a member of the brand, has any of them."},"durationBuckets":{"type":"array","items":{"enum":["lt15","15to30","30to60","gt60","unknown"],"type":"string"},"description":"Video lengths, any of: lt15 (under 15s), 15to30, 30to60 (60s included), gt60 (over 60s), unknown (no stored length). Slideshows have no length and match none."},"contentFormat":{"enum":["video","slideshow"],"type":"string","description":"video: videos only; slideshow: TikTok photo posts only, which ignores durationBuckets."},"hasUsageRightsRequest":{"type":"boolean","description":"true: only videos the brand has asked usage rights for, in any state; false: only videos with no request."},"creatorPostRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"The creator's estimated post rate, a percent from 0 to 100: how often they post after getting a sample."},"attributedGmv":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"itemsSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false},"lifetimeViews":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"The video's stored lifetime views, not the views it earned during the window."},"lifetimeLikes":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"The video's stored lifetime likes."},"lifetimeComments":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"The video's stored lifetime comments."},"paidSpend":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad spend of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidRoi":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"ROI TikTok reported (paid and organic sales over ad spend) of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductClicks":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product clicks of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidConversionRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Conversion rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidCostPerOrder":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Cost per order of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidOrders":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Orders of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidGrossRevenue":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Gross revenue of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductImpressions":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product impressions of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidProductClickRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Product click rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidClickRate":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad click rate, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRate2s":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched for 2 seconds, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRate6s":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched for 6 seconds, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP25":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 25%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP50":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 50%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP75":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to 75%, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"paidViewRateP100":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of ad impressions watched to the end, in percent, of the video's highest-ROI GMV Max campaign over the trailing year. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adItemsSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Items sold due to ads, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adRoi":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad ROI: ad sales over ad spend, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adSalesShare":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Share of the video's lifetime items sold that ads drove, in percent, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adSales":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"Ad sales: the video's lifetime revenue times that share, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."},"adCostPerItemSold":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"additionalProperties":false,"description":"ACoS: ad spend over the items sold due to ads, from the items sold Euka credits to ads: the video's highest-ROI GMV Max campaign's product clicks times its conversion rate, at most the video's lifetime items sold. A min leaves out videos with no GMV Max report; a max alone keeps them."}},"additionalProperties":false,"default":{}},"sort":{"type":"object","properties":{"field":{"enum":["attributedGmv","itemsSold"],"type":"string"},"direction":{"enum":["asc","desc"],"type":"string"}},"required":["field","direction"],"additionalProperties":false,"default":{"field":"attributedGmv","direction":"desc"}}},"required":["kind","dateRange"],"additionalProperties":false}]},"page":{"type":"number","default":1},"pageSize":{"type":"number","default":20}},"required":["brandId","scope"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string","description":"Stored creator video ID; treat this value as opaque."},"tiktokUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Link to the video on TikTok, built from the creator’s handle. Null when the handle is unknown."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the video’s cover image. Null when Euka has none."},"postedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the creator posted the video. Null when unknown."},"durationSeconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Video length in seconds. Null when unknown or a photo post."},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"creator":{"type":"object","properties":{"id":{"type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creator’s TikTok handle, without the @. Null when unknown."},"profileImageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the creator’s profile picture; it may not load when Euka has no copy of it."}},"required":["id","handle","profileImageUrl"],"description":"The creator who posted the video."},"product":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Product title. Null when unknown or when the product is not one of the shop’s."},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the product’s image; it may not load when Euka has no copy of it."}},"required":["id","title","imageUrl"]},{"type":"null"}],"description":"The product the video is tagged with. Null when it has none."},"usageRights":{"anyOf":[{"type":"object","properties":{"requestId":{"type":"number","description":"Usage rights request id for get_usage_rights_request."},"state":{"enum":["offerSent","offerDeclined","pendingPayment","active","expired"],"type":"string","description":"offerSent: waiting for the creator’s answer; offerDeclined: the creator declined, or the offer expired unanswered after 14 days; pendingPayment: the creator accepted a flat fee the brand has not paid yet; active: rights granted and not expired; expired: the license duration has ended."},"source":{"enum":["negotiated","enrollment","covered"],"type":"string","description":"covered: granted with no offer by a contest, marketplace campaign, Spark code or retainer; negotiated: an offer; enrollment: a program."},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When these rights end. Null when they never expire or no end date is set."}},"required":["requestId","state","source","expiresAt"],"description":"The brand's usage rights for this video: the request behind its live license, otherwise its latest open request. Null when there is neither."},{"type":"null"}]},"performance":{"anyOf":[{"type":"object","properties":{"scope":{"const":"lifetime"},"attributedGmv":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Amount in currencyCode."},"currencyCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 currency code, such as USD. Null when the source does not record one (the field holding this amount then names its currency) or when the amounts summed into it mix currencies."}},"required":["amount","currencyCode"]},{"type":"null"}],"description":"GMV TikTok Shop attributes to the video over its lifetime, as of the last sync, in the shop’s currency; currencyCode is not recorded. Null when unknown."},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Items sold through the video over its lifetime, as of the last sync. Null when unknown."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime views of the video, as of the last sync. Null when unknown."},"likes":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime likes, as of the last sync. Null when unknown."},"comments":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lifetime comments, as of the last sync. Null when unknown."},"observedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When Euka last refreshed the video’s lifetime numbers from TikTok Shop. Null when unknown; search_videos always returns null."}},"required":["scope","attributedGmv","itemsSold","views","likes","comments","observedAt"]},{"type":"object","properties":{"scope":{"const":"commerceWindow"},"startDate":{"type":"string","description":"Inclusive first date of the window."},"endDate":{"type":"string","description":"Inclusive last date of the window."},"sourceThroughDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Latest date with daily video data for the shop; later dates in the window have no data yet. Null when Euka has none for the shop."},"commerce":{"type":"object","properties":{"productScope":{"enum":["allProducts","selectedProducts"],"type":"string","description":"allProducts: GMV and items sold count every product the video sold; selectedProducts: only the filter’s productIds."},"attributedGmv":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Amount in currencyCode."},"currencyCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 currency code, such as USD. Null when the source does not record one (the field holding this amount then names its currency) or when the amounts summed into it mix currencies."}},"required":["amount","currencyCode"]},{"type":"null"}],"description":"GMV from the video’s sales during the window, in the shop’s currency as TikTok Shop reports it (USD for days synced before a non-US shop moved to its own currency); currencyCode is not recorded. Null when nonzero amounts have mixed or unknown currencies."},"itemsSold":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Items sold through the video during the window, with the same product scope."}},"required":["productScope","attributedGmv","itemsSold"],"description":"Sales the video drove during the window."},"views":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Views the whole video earned during the window, from TikTok Shop's daily video analytics (the source get_video_performance reads). Product filters do not apply."}},"required":["scope","startDate","endDate","sourceThroughDate","commerce","views"]}],"description":"Performance for the requested scope: lifetime numbers to date, or sales and views inside the commerce window."},"paidPerformance":{"anyOf":[{"type":"object","properties":{"source":{"const":"gmvMax"},"aggregation":{"const":"highestRoiCampaign"},"lookback":{"const":"trailingYear"},"spend":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Amount in currencyCode."},"currencyCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 currency code, such as USD. Null when the source does not record one (the field holding this amount then names its currency) or when the amounts summed into it mix currencies."}},"required":["amount","currencyCode"]},{"type":"null"}],"description":"Ad spend on the video in its highest-ROI GMV Max campaign over the trailing year, in the ad account’s billing currency."},"reportedRoi":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"ROI TikTok reported for that campaign: paid and organic sales divided by ad spend."},"orders":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Orders TikTok attributed to that campaign’s ads for the video."},"grossRevenue":{"anyOf":[{"type":"object","properties":{"amount":{"type":"number","description":"Amount in currencyCode."},"currencyCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 4217 currency code, such as USD. Null when the source does not record one (the field holding this amount then names its currency) or when the amounts summed into it mix currencies."}},"required":["amount","currencyCode"]},{"type":"null"}],"description":"Gross revenue TikTok reported for that campaign’s ads for the video, in the ad account’s billing currency."}},"required":["source","aggregation","lookback","spend","reportedRoi","orders","grossRevenue"]},{"type":"null"}],"description":"GMV Max results for the video over the trailing year, from its highest-ROI campaign rather than a total across campaigns; not limited to a search window or the video’s lifetime. Null when no GMV Max report covers the video."}},"required":["videoId","tiktokUrl","thumbnailUrl","postedAt","durationSeconds","description","creator","product","usageRights","performance","paidPerformance"]},"description":"Videos on this page, in the requested sort order."},"pageInfo":{"type":"object","properties":{"page":{"type":"number","description":"The page returned, from 1."},"pageSize":{"type":"number","description":"Maximum videos per page, as requested."},"hasNextPage":{"type":"boolean","description":"Whether another page follows; request page + 1 to read it."},"omittedVideoCount":{"type":"number","description":"Videos left out because Euka could not load them as the shop’s creator videos: requested videoIds it did not find, or commerceWindow videos on this page that have sales but no video record. Report it when nonzero."}},"required":["page","pageSize","hasNextPage","omittedVideoCount"],"description":"Paging for this result."}},"required":["items","pageInfo"]}}}}},"security":[{"openApiKey":[]}]}},"/data-export":{"get":{"operationId":"dataExport","summary":"Export brand data","description":"Export data for a brand accessible to the OpenAPI key. brand_id is preferred; deprecated store-only requests remain supported temporarily and are translated to the store's authoritative brand_id. Date-bounded exports support windows up to 180 days, except spark-code download links, which remain limited to the most recent 60 days. For creator_videos and creator_video_level, the JSON envelope also includes video_data_scraped_at, video_data_unscraped_shop_count, and latest_video_posted_at so consumers can detect ingestion lag; those fields are null when unavailable. spark_codes_video_download_links returns at most 150 videos, newest Spark code first, and leaves out the rest without saying so; narrow the dates to stay under it. A Spark code does not grant usage rights: use /licensed-content/search for the content the brand holds usage rights to.","tags":["Data Export"],"security":[{"openApiKey":[]}],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["target_collab_invites","sample_requests","creator_videos","creator_level","creator_video_level","bot_level","spark_codes_video_download_links"]}},{"name":"brand_id","in":"query","required":false,"description":"Preferred tenant input. Required unless deprecated store_id compatibility is used.","schema":{"type":"string","format":"uuid"}},{"name":"store_id","in":"query","required":false,"deprecated":true,"description":"Deprecated public-API compatibility input. The server translates it to the store's authoritative brand_id; when brand_id is also supplied, the pair must match.","schema":{"type":"string","format":"uuid"}},{"name":"start_date","in":"query","required":false,"description":"YYYY-MM-DD start date for date-bounded exports. The maximum window is 180 days, except spark-code download links.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"YYYY-MM-DD end date for date-bounded exports. Spark-code download links must stay within the most recent 60 days.","schema":{"type":"string","format":"date"}},{"name":"export_type","in":"query","required":false,"schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"creator_handle","in":"query","required":false,"description":"Required when type is creator_video_level.","schema":{"type":"string"}},{"name":"creator_username","in":"query","required":false,"description":"Optional filter for creator_level exports.","schema":{"type":"string"}}],"responses":{"200":{"description":"Export result as JSON or CSV.","content":{"application/json":{"schema":{"type":"object"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid export request."},"401":{"description":"Missing or invalid OpenAPI key."},"404":{"description":"Brand or store not found or not accessible."},"502":{"description":"Data export upstream failed."}}}},"/market-intelligence/tiktok/category/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok category detail","description":"Retrieve detailed information for a specific category.\n\n**`date_range`**: only `last7Day`, `last30Day`, `last90Day`, `last180Day`, `last365Day` are supported (natural date ranges and months are NOT accepted here).","operationId":"marketIntelligenceTikTokCategoryDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceCategoryDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","category_id":"601450"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultCategoryDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/category/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok category rank","description":"Retrieve ranking list of categories based on specified criteria and filters.\n\n**`date_range`**: only `last7Day`, `last30Day`, `last90Day`, `last180Day`, `last365Day` are supported (natural date ranges and months are NOT accepted here).\n\n**`sort_field.field`**: `revenue` (default), `revenue_growth_rate`, `top3_shop_revenue_ratio`, `average_revenue`, `rank`, `category_id`, `category_name`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokCategoryRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceCategoryRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListCategoryRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/creator/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok creator detail","description":"Retrieve detailed information for a specific creator","operationId":"marketIntelligenceTikTokCreatorDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceCreatorDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","creator_id":"7153432386608251946"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultCreatorDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/creator/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok creator rank","description":"Retrieve ranking list of creators based on specified criteria and filters.\n\n**`date_range`**: window is capped at 30 days. Supports `lastDay`, `last7Day`, `last30Day`, a natural `yyyy-MM-dd~yyyy-MM-dd` (span ≤ 30 days), or a natural month `yyyy-MM`.\n\n**`sort_field.field`**: `revenue` (default), `revenue_growth_rate`, `content_views`, `creator_followers`, `sales_volumn`, `video_revenue`, `live_revenue`, `creator_id`, `creator_nickname`, `creator_handle`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokCreatorRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceCreatorRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListCreatorRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/livestream/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok livestream detail","description":"Retrieve detailed information for a specific livestream","operationId":"marketIntelligenceTikTokLivestreamDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceLiveStreamDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","livestream_id":"7665792164135258910"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultLiveStreamDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/livestream/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok livestream rank","description":"Retrieve ranking list of livestreams based on specified criteria and filters.\n\n**`date_range`**: window is capped at 30 days. Supports `lastDay`, `last7Day`, `last30Day`, a natural `yyyy-MM-dd~yyyy-MM-dd` (span ≤ 30 days), or a natural month `yyyy-MM`.\n\n**`sort_field.field`**: `revenue` (default), `unit_price`, `views`, `livestream_start_time`, `livestream_end_time`, `livestream_duration`, `livestream_id`, `livestream_title`, `creator_id`, `creator_handle`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokLivestreamRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceLiveStreamRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListLiveStreamRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/product/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok product detail","description":"Retrieve detailed information for a specific product","operationId":"marketIntelligenceTikTokProductDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceProductDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","product_id":"1729508370969629931"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultProductDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/product/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok product rank","description":"Retrieve ranking list of products based on specified criteria and filters.\n\n**`date_range`**: window is capped at 30 days. Supports `lastDay`, `last7Day`, `last30Day`, a natural `yyyy-MM-dd~yyyy-MM-dd` (span ≤ 30 days), or a natural month `yyyy-MM`.\n\n**`sort_field.field`**: `revenue` (default), `commission_rate`, `revenue_growth_rate`, `sales_volumn`, `unit_price`, `launch_date`, `live_revenue`, `video_revenue`, `showcase_revenue`, `product_id`, `product_name`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokProductRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceProductRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListProductRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/shop/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok shop detail","description":"Retrieve detailed information for a specific shop","operationId":"marketIntelligenceTikTokShopDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceShopDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","shop_id":"7495514739648989419"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultShopDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/shop/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok shop rank","description":"Retrieve ranking list of shops based on specified criteria and filters.\n\n**`date_range`**: window is capped at 30 days. Supports `lastDay`, `last7Day`, `last30Day`, a natural `yyyy-MM-dd~yyyy-MM-dd` (span ≤ 30 days), or a natural month `yyyy-MM`.\n\n**`sort_field.field`**: `revenue` (default), `sales_volumn`, `revenue_growth_rate`, `unit_price`, `shop_type`, `affiliate_revenue`, `self_promotion_revenue`, `shopping_mall_revenue`, `on_sell_product_count`, `rank`, `shop_id`, `shop_name`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokShopRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceShopRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListShopRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/video/detail":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok video detail","description":"Retrieve detailed information for a specific video","operationId":"marketIntelligenceTikTokVideoDetail","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceVideoDetailReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","video_id":"7655013236043025678"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultVideoDetailRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}},"/market-intelligence/tiktok/video/rank":{"post":{"tags":["Market Intelligence - TikTok"],"summary":"TikTok video rank","description":"Retrieve ranking list of videos based on specified criteria and filters.\n\n**`date_range`**: window is capped at 30 days. Supports `lastDay`, `last7Day`, `last30Day`, a natural `yyyy-MM-dd~yyyy-MM-dd` (span ≤ 30 days), or a natural month `yyyy-MM`.\n\n**`sort_field.field`**: `revenue` (default), `views`, `revenue_growth_rate`, `ads_roas`, `video_id`, `video_title`, `belonged_creator_id`, `belonged_creator_handle`. Default sort is `revenue DESC`.","operationId":"marketIntelligenceTikTokVideoRank","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceVideoRankReq"},"example":{"region":"US","language":"en-US","currency":"USD","date_range":"last30Day","sort_field":{"field":"revenue","type":"DESC"},"page_number":1,"page_size":10}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceResultListVideoRankRes"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"401":{"description":"Missing or invalid Euka OpenAPI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"429":{"description":"Weekly Market Intelligence request quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}},"headers":{"Retry-After":{"description":"Seconds until the weekly quota resets (next Monday 00:00 UTC).","schema":{"type":"integer"}}}},"503":{"description":"Market Intelligence service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}},"504":{"description":"Market Intelligence provider request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntelligenceError"}}}}},"security":[{"openApiKey":[]}]}}},"components":{"schemas":{"MarketIntelligenceCategoryDetailReq":{"required":["category_id","currency","date_range","language","region"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"category_id":{"type":"string","description":"Category ID to query.","example":"601450"}},"additionalProperties":false},"MarketIntelligenceCategoryDetailRes":{"type":"object","properties":{"category_id":{"type":"string","description":"Category ID","example":"12345"},"category_name":{"type":"string","description":"Category name","example":"Electronics"},"revenue":{"type":"number","description":"Category revenue within the selected time range","format":"double","example":150000.5},"shop_number":{"type":"integer","description":"Number of shops with product sales records in this category within the selected time range","format":"int32","example":25},"live_revenue":{"type":"number","description":"Transaction amount for category products through live streaming channels within the selected time range","format":"double","example":80000.25},"video_revenue":{"type":"number","description":"Transaction amount for category products through video channels within the selected time range","format":"double","example":70000.25},"revenue_growth_rate":{"type":"number","description":"Growth rate of the category within the selected time range","format":"double","example":15.5},"average_shop_revenue":{"type":"number","description":"Average revenue of active selling shops within the selected time range","format":"double","example":6000.2},"affiliate_revenue":{"type":"number","description":"Order amount for category products through affiliate creator partnerships within the selected time range","format":"double","example":45000.75},"self_operate_revenue":{"type":"number","description":"Order amount for category products through shop's own creators within the selected time range","format":"double","example":55000.25},"shopping_mall_revenue":{"type":"number","description":"Order amount for category products through shopping mall channels within the selected time range","format":"double","example":50000},"revenue_trend":{"type":"array","description":"Category revenue trend within the selected time range","example":50000,"items":{"type":"number","description":"Category revenue trend within the selected time range","format":"double","example":50000}},"sale":{"type":"integer","description":"Sales  of the category within the selected time range","format":"int32","example":340},"active_product_number":{"type":"integer","description":"Number of product with product sales records in this category within the selected time range","format":"int32","example":25}}},"MarketIntelligenceCategoryRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Restrict results to the given category IDs and their sub-categories. When omitted, all categories are included.","example":["601450"],"items":{"type":"string","description":"Restrict results to the given category IDs and their sub-categories. When omitted, all categories are included.","example":"[\"601450\"]"}},"category_level":{"type":"integer","description":"Category level to return. 1 = top level, 2 = mid level, 3 = leaf level.","format":"int32","example":1,"enum":[1,2,3]},"revenue_range":{"type":"string","description":"Revenue range filter within the selected time period, in the same currency as the request `currency`. Also supports open-ended forms like `<100` or `>1000`.","example":"100-1000"}},"additionalProperties":false},"MarketIntelligenceCategoryRankRes":{"type":"object","properties":{"category_id":{"type":"string","description":"Category ID","example":"12345"},"category_name":{"type":"string","description":"Category name, returns category name in different languages based on different language parameters","example":"Electronics"},"rank":{"type":"integer","description":"Category ranking","format":"int32","example":3},"revenue":{"type":"number","description":"Total revenue of the category within the selected time range","format":"double","example":250000.75},"sale":{"type":"integer","description":"Sales  of the category within the selected time range","format":"int32","example":340},"revenue_growth_rate":{"type":"number","description":"Sales growth rate of the category within the selected time range","format":"double","example":25.8},"top3_shop_revenue_ratio":{"type":"number","description":"Revenue ratio of the top 3 revenue-ranked shops in the corresponding category","format":"double","example":35.2},"average_revenue":{"type":"number","description":"Average revenue per shop in the category","format":"double","example":12500.5}}},"MarketIntelligenceCreatorDetailReq":{"required":["creator_id","currency","date_range","language","region"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"creator_id":{"type":"string","description":"Creator ID to query.","example":"6937492675021095937"},"category_ids":{"type":"array","description":"Restrict revenue attribution to the given category IDs.","example":[700645,223],"items":{"type":"integer","description":"Restrict revenue attribution to the given category IDs.","format":"int64"}},"shop_id":{"type":"string","description":"Restrict revenue attribution to products from the given shop.","example":"7495634116320922282"},"need_extra":{"type":"boolean","description":"Need Extra Info","example":false}},"additionalProperties":false},"MarketIntelligenceCreatorDetailRes":{"type":"object","properties":{"creator_id":{"type":"string","description":"Creator ID","example":"6865455528727708677"},"creator_nickname":{"type":"string","description":"Creator nickname","example":"TechReviewer"},"creator_handle":{"type":"string","description":"Creator handle","example":"techreviewer"},"creator_region":{"type":"string","description":"Creator's country/region","example":"US"},"creator_status":{"type":"string","description":"Creator identity. BELONGED_TO_SELLER = shop-owned creator, INDEPENDENT = independent affiliate creator.","example":"INDEPENDENT","enum":["BELONGED_TO_SELLER","INDEPENDENT"]},"creator_belonged_shop_id":{"type":"string","description":"Creator's affiliated shop, empty if creator is an affiliate creator","example":"7495514739648989419"},"creator_bio":{"type":"string","description":"Creator bio on profile page, updated daily for top creators","example":"Tech enthusiast sharing the latest gadgets"},"creator_contact_email":{"type":"string","description":"Creator's email","example":"creator@example.com"},"creator_contact_tiktok":{"type":"string","description":"Creator's TikTok account","example":"techreviewer_tiktok"},"creator_contact_whatsapp":{"type":"string","description":"Creator's WhatsApp account","example":"+1234567890"},"creator_contact_line":{"type":"string","description":"Creator's Line account","example":"techreviewer_line"},"creator_contact_facebook":{"type":"string","description":"Creator's Facebook account","example":"techreviewer.fb"},"creator_contact_ins":{"type":"string","description":"Creator's Instagram account","example":"@techreviewer_insta"},"creator_contact_zalo":{"type":"string","description":"Creator's Zalo account","example":"techreviewer_zalo"},"revenue":{"type":"number","description":"Creator's sales revenue in selected category during selected period","format":"double","example":12500.75},"sales_volumn":{"type":"integer","description":"Creator's sales volume in selected category during selected period","format":"int32","example":150},"unit_price":{"type":"number","description":"Creator's average unit price in selected category during selected period","format":"double","example":83.34},"video_revenue":{"type":"number","description":"Creator's revenue from video sales of selected category products during selected period","format":"double","example":7500.25},"live_revenue":{"type":"number","description":"Creator's revenue from live stream sales of selected category products during selected period","format":"double","example":5000.5},"video_views":{"type":"integer","description":"Creator's total video view count during selected period","format":"int32","example":250000},"live_views":{"type":"integer","description":"Creator's total live stream view count during selected period","format":"int32","example":180000},"live_gpm":{"type":"number","description":"Creator's GPM from live stream sales during selected period, GPM is revenue per thousand views","format":"double","example":27.78},"video_gpm":{"type":"number","description":"Creator's GPM from video sales during selected period, GPM is revenue per thousand views","format":"double","example":30},"new_followers":{"type":"integer","description":"Number of new followers gained by creator during selected period","format":"int32","example":5000},"video_number":{"type":"integer","description":"Number of videos with views by creator during selected period","format":"int32","example":25},"live_number":{"type":"integer","description":"Number of live streams conducted by creator during selected period","format":"int32","example":10},"shop_number":{"type":"integer","description":"Number of shops collaborated with by creator during selected period","format":"int32","example":8},"product_number":{"type":"integer","description":"Number of products sold by creator during selected period","format":"int32","example":45},"creator_followers":{"type":"string","description":"Creator's follower count, updated daily","example":"100000"},"revenue_trend":{"type":"array","description":"Creator's sales revenue trend in selected category during selected period","example":[25.1,24.3],"items":{"type":"number","description":"Creator's sales revenue trend in selected category during selected period","format":"double"}},"top3_product_ids":{"type":"array","description":"Creator's sales top3 product ids  in selected category during selected period","example":[25.1,24.3],"items":{"type":"string","description":"Creator's sales top3 product ids  in selected category during selected period","example":"[25.1,24.3]"}}}},"MarketIntelligenceCreatorRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Deprecated, use `category_id_list`. List of category IDs to restrict creator revenue.","example":[700645,223],"items":{"type":"integer","description":"Deprecated, use `category_id_list`. List of category IDs to restrict creator revenue.","format":"int64"}},"category_id_list":{"type":"string","description":"Comma-separated category IDs (preferred over `category_ids`).","example":"700645,223"},"shop_id":{"type":"string","description":"Restrict to creators collaborating with the given shop (any video / live / showcase mounting the shop's products with exposure).","example":"7494965300835814281"},"product_id":{"type":"string","description":"Restrict to creators who have promoted the given product.","example":"1729587769570529799"},"revenue_range":{"type":"string","description":"Revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms.","example":"100-1000"},"creator_type":{"type":"string","description":"Creator type filter. BELONGED_TO_SELLER = seller's own creator, INDEPENDENT = independent affiliate creator.","example":"INDEPENDENT","enum":["BELONGED_TO_SELLER","INDEPENDENT"]},"followers_range":{"type":"string","description":"Follower count range filter. Also supports `<100` / `>1000` forms.","example":"1000-10000"},"engagement_rate":{"type":"string","description":"Engagement rate bucket. LOW = <8%, MEDIUM = 8%-20%, HIGH = >20%.","example":"MEDIUM","enum":["LOW","MEDIUM","HIGH"]},"keyword":{"type":"string","description":"Keyword for creator search","example":"beauty"},"need_image":{"type":"integer","description":"Whether main image URL is needed: 0 not needed (default), 1 return official URL, 2 return Market Intelligence provider image URL (paid service required)","format":"int32","example":1},"need_category":{"type":"integer","description":"Whether category information is needed (0 = not needed, 1 = needed)","format":"int32","example":0},"need_ter_category":{"type":"integer","description":"Whether ter category information is needed (0 = not needed, 1 = needed)","format":"int32","example":0}},"additionalProperties":false},"MarketIntelligenceCreatorRankRes":{"type":"object","properties":{"creator_id":{"type":"string","description":"Creator ID","example":"6937492675021095937"},"creator_nickname":{"type":"string","description":"Creator nickname","example":"Cici Barbar"},"creator_handle":{"type":"string","description":"Creator handle name, names with @ prefix are handle names","example":"cici.barbar"},"revenue":{"type":"number","description":"Creator transaction amount","format":"double","example":2000},"revenue_growth_rate":{"type":"number","description":"Creator transaction amount growth rate","format":"double","example":1},"content_views":{"type":"string","description":"Creator content views within the selected time range","example":"1200"},"creator_followers":{"type":"string","description":"Creator's follower count, updated daily","example":"100000"},"sales_volumn":{"type":"integer","description":"Sales volume","format":"int32","example":150},"video_revenue":{"type":"number","description":"Video sales revenue","format":"double","example":1200.5},"live_revenue":{"type":"number","description":"Live streaming sales revenue","format":"double","example":800.25},"image_url":{"type":"string","description":"Creator image URL","example":"https://example.com/creator123.jpg"},"category_list":{"type":"array","description":"Top three categories","example":["Electronics","Fashion","Beauty"],"items":{"type":"string","description":"Top three categories","example":"[\"Electronics\",\"Fashion\",\"Beauty\"]"}},"category_id_list":{"type":"array","description":"Top three category IDs","example":["12345","67890","11111"],"items":{"type":"string","description":"Top three category IDs","example":"[\"12345\",\"67890\",\"11111\"]"}},"ter_category_list":{"type":"array","description":"Top 3 third categories","example":["Mules & Clogs","Heels","Slippers"],"items":{"type":"string","description":"Top 3 third categories","example":"[\"Mules & Clogs\",\"Heels\",\"Slippers\"]"}},"ter_category_id_list":{"type":"array","description":"Top 3 third category IDs","example":["901896","601396","601405"],"items":{"type":"string","description":"Top 3 third category IDs","example":"[\"901896\",\"601396\",\"601405\"]"}}}},"MarketIntelligenceLiveStreamDetailReq":{"required":["currency","date_range","language","livestream_id","region"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"livestream_id":{"type":"string","description":"Live stream ID to query.","example":"7413090312010091307"},"need_extra":{"type":"boolean","description":"Need Extra Info","example":false}},"additionalProperties":false},"MarketIntelligenceLiveStreamDetailRes":{"type":"object","properties":{"livestream_id":{"type":"string","description":"Live stream ID","example":"7649943840243059469"},"livestream_title":{"type":"string","description":"Live stream title","example":"Live Shopping Event"},"creator_handle":{"type":"string","description":"Live stream creator handle","example":"techreviewer"},"creator_id":{"type":"string","description":"Live stream creator ID","example":"7205949066194781230"},"livestream_start_time":{"type":"integer","description":"Live stream start time (milliseconds)","format":"int64","example":1699123200000},"livestream_end_time":{"type":"integer","description":"Live stream end time (milliseconds)","format":"int64","example":1699126800000},"livestream_duration":{"type":"integer","description":"Live stream duration (seconds)","format":"int32","example":3600},"product_number":{"type":"integer","description":"Number of products sold in live stream","format":"int32","example":15},"viewers":{"type":"integer","description":"Number of live stream viewers","format":"int32","example":5000},"revenue":{"type":"number","description":"Live stream revenue","format":"double","example":8500.5},"gpm":{"type":"number","description":"Live stream GPM (revenue per thousand views)","format":"double","example":1.7},"top3_product_ids":{"type":"array","description":"top3 product ids  within selected time period","example":["1733316657074833297"],"items":{"type":"string","description":"top3 product ids  within selected time period","example":"[\"1733316657074833297\"]"}},"record_type":{"type":"string","description":"Live record type","example":"SCREENSHOT"}}},"MarketIntelligenceLiveStreamRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Restrict results to live streams in the given category IDs.","example":["601450"],"items":{"type":"string","description":"Restrict results to live streams in the given category IDs.","example":"[\"601450\"]"}},"shop_id":{"type":"string","description":"Restrict results to live streams promoting the given shop's products.","example":"7494965300835814281"},"creator_id":{"type":"string","description":"Restrict results to live streams hosted by the given creator.","example":"7014603102829593606"},"product_id":{"type":"string","description":"Restrict results to live streams mounting the given product.","example":"1729587769570529799"},"followers_range":{"type":"string","description":"Follower count range of the live stream host. Also supports `<100` / `>10000` forms.","example":">100"},"keyword":{"type":"string","description":"Keyword search","example":"beauty"}},"additionalProperties":false},"MarketIntelligenceLiveStreamRankRes":{"type":"object","properties":{"livestream_id":{"type":"string","description":"Live stream ID","example":"7649943840243059469"},"livestream_title":{"type":"string","description":"Live stream title","example":"Top Products Live"},"creator_handle":{"type":"string","description":"Live stream creator handle","example":"seller123"},"creator_id":{"type":"string","description":"Live stream creator ID","example":"7205949066194781230"},"livestream_start_time":{"type":"integer","description":"Live stream start time (milliseconds)","format":"int64","example":1699123200000},"livestream_end_time":{"type":"integer","description":"Live stream end time (milliseconds)","format":"int64","example":1699127800000},"livestream_duration":{"type":"integer","description":"Live stream duration in seconds","format":"int32","example":4600},"revenue":{"type":"string","description":"Live stream revenue under selected category/shop/product","example":"15000.75"},"unit_price":{"type":"string","description":"Live stream unit price under selected category/shop/product","example":"25.5"},"views":{"type":"integer","description":"View count","format":"int32","example":12000},"record_type":{"type":"string","description":"Live record type","example":"SCREENSHOT"}}},"MarketIntelligenceProductDetailReq":{"required":["currency","date_range","language","product_id","region"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"product_id":{"type":"string","description":"Product ID to query.","example":"1729587769570529799"},"need_image":{"type":"integer","description":"Whether main image URL is needed: 0-not needed (default), 1-return official URL, 2-return Market Intelligence provider image URL (paid service required)","format":"int32","example":1},"need_extra":{"type":"boolean","description":"Need Extra Info","example":false}},"additionalProperties":false},"MarketIntelligenceProductDetailRes":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID","example":"7495514739648989419"},"product_region":{"type":"string","description":"Product country/region","example":"US"},"product_name":{"type":"string","description":"Product name","example":"Smart Watch Pro"},"product_shop_id":{"type":"string","description":"Product shop ID","example":"7495514739648989419"},"pri_cate_id":{"type":"string","description":"Product primary category ID","example":"12345"},"sec_cate_id":{"type":"string","description":"Product secondary category ID","example":"67890"},"ter_cate_id":{"type":"string","description":"Product tertiary category ID","example":"13579"},"max_price":{"type":"number","description":"Maximum SKU price of the product","format":"double","example":299.99},"min_price":{"type":"number","description":"Minimum SKU price of the product","format":"double","example":199.99},"revenue":{"type":"number","description":"Revenue of the product within the selected time range","format":"double","example":15000.75},"video_revenue":{"type":"number","description":"Video revenue of the product within the selected time range","format":"double","example":8500.25},"live_revenue":{"type":"number","description":"Livestream revenue of the product within the selected time range","format":"double","example":6500.5},"sales_volumn":{"type":"integer","description":"Sales volume of the product within the selected time range","format":"int32","example":750},"creator_number":{"type":"integer","description":"Number of creators who have promoted this product within the selected time range","format":"int32","example":25},"video_number":{"type":"integer","description":"Number of videos that have promoted this product within the selected time range","format":"int32","example":85},"live_number":{"type":"integer","description":"Number of livestreams that have promoted this product within the selected time range","format":"int32","example":15},"delivery_type":{"type":"string","description":"Fulfillment mode of the product.","example":"local"},"shopping_mall_revenue":{"type":"number","description":"Shopping mall revenue","format":"double","example":5000},"commission_rate":{"type":"number","description":"Product commission rate. Value is percentage points, i.e. 1.0 = 1%.","format":"double","example":1},"unit_price":{"type":"number","description":"Unit price of the product within the selected time range","format":"double","example":20},"product_review_count":{"type":"integer","description":"Product review count","format":"int32","example":120},"launch_date":{"type":"string","description":"Product launch date","example":"2024-02-01"},"master_image_url":{"type":"string","description":"Main image URL","example":"https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/cad4b7c7409f459a87c54baf31ff8a20~tplv-omjb5zjo8w-resize-webp:800:800.jpeg"},"revenue_trend":{"type":"array","description":"revenue trend  within selected time period","example":[25.1,24.3],"items":{"type":"number","description":"revenue trend  within selected time period","format":"double"}}}},"MarketIntelligenceProductRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Restrict results to the given category IDs.","example":["601450"],"items":{"type":"string","description":"Restrict results to the given category IDs.","example":"[\"601450\"]"}},"shop_id":{"type":"string","description":"Restrict results to the given shop.","example":"7495634116320922282"},"creator_id":{"type":"string","description":"Restrict results to products promoted by the given creator. Combined with `shop_id` returns the creator's list for that shop.","example":"7495634116320922282"},"video_id":{"type":"string","description":"Return the products mounted on the given video.","example":"7495634116320922282"},"livestream_id":{"type":"string","description":"Return the products mounted in the given live stream.","example":"7495634116320922282"},"revenue_range":{"type":"string","description":"Revenue range filter, in the same currency as the request `currency`. Also supports `<10` / `>1` forms.","example":"1-10"},"is_affiliate":{"type":"integer","description":"Affiliate-program filter. 0 = non-affiliate only, 1 = affiliate only.","format":"int32","example":1,"enum":[0,1]},"commission_rate":{"type":"string","description":"Commission rate filter for affiliate products. Accepts range (`15-35`), open-ended (`<10`, `>=30`), or a single ratio.","example":"15-35"},"is_tts_product":{"type":"integer","description":"TTS (Tiktok fully-managed) product filter. 1 = fully managed only, 0 = self-fulfilled only.","format":"int32","example":1,"enum":[0,1]},"unit_price_range":{"type":"string","description":"Product unit-price range filter.","example":"1-1000"},"need_all":{"type":"boolean","description":"If true, include products that have no sales in the selected period. Default false (sales-only).","example":false},"delivery_type":{"type":"string","description":"Delivery mode filter. `local` = domestic fulfillment, `global` = cross-border.","example":"local","enum":["local","global"]},"launch_date":{"type":"string","description":"Days since product launch. <3 = within 3 days, <7 = within 7 days, <30 = within 30 days.","example":"<7","enum":["<3","<7","<30"]},"need_image":{"type":"integer","description":"Whether main image URL is needed: 0-not needed (default), 1-return official URL, 2-return Market Intelligence provider image URL (paid service required)","format":"int32","example":1},"keyword":{"type":"string","description":"Keyword search","example":"mobile phone"},"need_extra":{"type":"boolean","description":"Need Extra Info,such as seller name, SKU quantity.","example":false}},"additionalProperties":false},"MarketIntelligenceProductRankRes":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID","example":"1729508370969629931"},"product_name":{"type":"string","description":"Product name","example":"Wireless Bluetooth Headphones"},"revenue":{"type":"number","description":"Revenue completed under specified conditions","format":"double","example":8500.5},"commission_rate":{"type":"number","description":"Product commission rate, updated daily for top products","format":"double","example":15},"revenue_growth_rate":{"type":"number","description":"Product revenue growth rate","format":"double","example":25.8},"sales_volumn":{"type":"integer","description":"Sales volume of the product within the selected time range","format":"int32","example":340},"unit_price":{"type":"number","description":"Unit price of the product within the selected time range","format":"double","example":25},"live_revenue":{"type":"number","description":"Livestream revenue of the product within the selected time range","format":"double","example":1200},"video_revenue":{"type":"number","description":"Video revenue of the product within the selected time range","format":"double","example":800},"showcase_revenue":{"type":"number","description":"show case revenue","format":"double","example":500},"launch_date":{"type":"string","description":"Product launch date","example":"2024-01-15"},"master_image_url":{"type":"string","description":"Main image URL","example":"https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/29510943b3664843abfd17e5371edd44~tplv-omjb5zjo8w-resize-webp:800:800.jpeg"},"seller_id":{"type":"string","description":"Seller Id","example":"7495514739648989419"},"seller_name":{"type":"string","description":"Seller name","example":"medicube US Store"},"sku_count":{"type":"string","description":"Sku Cnt","example":"2"}}},"MarketIntelligenceResultCategoryDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceCategoryDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultCreatorDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceCreatorDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListCategoryRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceCategoryRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListCreatorRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceCreatorRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListLiveStreamRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceLiveStreamRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListProductRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceProductRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListShopRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceShopRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultListVideoRankRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntelligenceVideoRankRes"}},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultLiveStreamDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceLiveStreamDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultProductDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceProductDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultShopDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceShopDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceResultVideoDetailRes":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/MarketIntelligenceVideoDetailRes"},"message":{"type":"string"},"cached":{"type":"boolean"},"code":{"type":"string"}}},"MarketIntelligenceShopDetailReq":{"required":["currency","date_range","language","region","shop_id"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"shop_id":{"type":"string","description":"Shop ID to query.","example":"7494965300835814281"},"category_ids":{"type":"array","description":"Restrict revenue attribution to the given category IDs.","example":["601450"],"items":{"type":"string","description":"Restrict revenue attribution to the given category IDs.","example":"[\"601450\"]"}},"need_extra":{"type":"boolean","description":"Need Extra Info","example":false}},"additionalProperties":false},"MarketIntelligenceShopDetailRes":{"type":"object","properties":{"shop_id":{"type":"string","description":"Shop ID","example":"7495514739648989419"},"shop_name":{"type":"string","description":"Shop name","example":"TechStore"},"region":{"type":"string","description":"Shop country / region (matches the request `region` value).","example":"US"},"revenue":{"type":"number","description":"Shop revenue within selected time period","format":"double","example":125000.5},"shoppingmall_revenue":{"type":"number","description":"Shop revenue through shopping mall channel within selected time period","format":"double","example":45000.25},"self_account_revenue":{"type":"number","description":"Shop revenue through self-operated account orders within selected time period","format":"double","example":55000.75},"affiliate_revenue":{"type":"number","description":"Shop revenue through affiliate partner account orders within selected time period","format":"double","example":25000},"sales_volumn":{"type":"integer","description":"Shop sales volume, total sales volume of shop products within selected time period","format":"int32","example":2500},"unit_price":{"type":"number","description":"Shop's average unit price within selected time period","format":"double","example":50},"creator_number":{"type":"integer","description":"Number of affiliate creators collaborating with shop within selected time period","format":"int32","example":15},"product_number":{"type":"integer","description":"Number of products listed by shop within selected time period","format":"int32","example":125},"video_number":{"type":"integer","description":"Number of videos with shop products that have exposure within selected time period","format":"int32","example":85},"live_number":{"type":"integer","description":"Number of live streams featuring shop products within selected time period","format":"int32","example":25},"revenue_trend":{"type":"array","description":"shop revenue trend  within selected time period","example":[25.1,24.3],"items":{"type":"number","description":"shop revenue trend  within selected time period","format":"double"}},"top3_product_ids":{"type":"array","description":"top3 product ids  within selected time period","example":["1733316657074833297"],"items":{"type":"string","description":"top3 product ids  within selected time period","example":"[\"1733316657074833297\"]"}},"seller_type":{"type":"string","description":"seller type","example":"BRAND"}}},"MarketIntelligenceShopRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Restrict results to shops that sell in the given category IDs.","example":["601450"],"items":{"type":"string","description":"Restrict results to shops that sell in the given category IDs.","example":"[\"601450\"]"}},"revenue_range":{"type":"string","description":"Shop revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms.","example":"100-1000"},"shop_type":{"type":"string","description":"Shop type filter. BRAND = brand-owned store, RETAILER = retailer store.","example":"BRAND","enum":["BRAND","RETAILER"]},"keyword":{"type":"string","description":"Keyword for shop search","example":"electronics"},"need_image":{"type":"integer","description":"Whether main image URL is needed: 0 not needed (default), 1 return official URL, 2 return Market Intelligence provider image URL (paid service required)","format":"int32","example":1},"need_category":{"type":"integer","description":"Whether category information is needed (0 = not needed, 1 = needed)","format":"int32","example":0},"unit_price_range":{"type":"string","description":"Shop product avg price range","example":"10-100"}},"additionalProperties":false},"MarketIntelligenceShopRankRes":{"type":"object","properties":{"shop_id":{"type":"string","description":"Shop ID","example":"7495514739648989419"},"shop_name":{"type":"string","description":"Shop name","example":"TechWorld Store"},"rank":{"type":"integer","description":"Shop ranking obtained based on sorting criteria under the selected conditions","format":"int32","example":5},"revenue":{"type":"number","description":"Shop transaction amount","format":"double","example":125000.75},"sales_volumn":{"type":"integer","description":"Shop sales volume, total sales volume of products under the shop within the selected time range","format":"int32","example":2500},"revenue_growth_rate":{"type":"number","description":"Shop transaction amount growth rate","format":"double","example":18.5},"unit_price":{"type":"number","description":"Average unit price of the shop within the selected time range","format":"double","example":50},"shop_type":{"type":"string","description":"Categorized into retail shops and brand shops","example":"BRAND"},"on_sell_product_count":{"type":"integer","description":"Number of products on sale","format":"int32","example":85},"affiliate_revenue":{"type":"number","description":"Shop revenue through affiliate partner account orders within selected time period","format":"double","example":25000},"self_promotion_revenue":{"type":"number","description":"Shop revenue through self-operated account orders within selected time period","format":"double","example":55000.75},"shopping_mall_revenue":{"type":"number","description":"Shop revenue through shopping mall channel within selected time period","format":"double","example":45000.25},"image_url":{"type":"string","description":"Shop image URL","example":"https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/4ae4940e7bcf436491ab2ddb3363ce9c~tplv-omjb5zjo8w-resize-webp:800:800.jpeg"},"category_list":{"type":"array","description":"Category names, returns category names in different languages based on different language parameters","example":["Electronics","Fashion","Home"],"items":{"type":"string","description":"Category names, returns category names in different languages based on different language parameters","example":"[\"Electronics\",\"Fashion\",\"Home\"]"}},"category_id_list":{"type":"array","description":"Category IDs, returns category IDs in different languages based on different language parameters","example":["12345","67890","11111"],"items":{"type":"string","description":"Category IDs, returns category IDs in different languages based on different language parameters","example":"[\"12345\",\"67890\",\"11111\"]"}}}},"MarketIntelligenceSortFieldReq":{"type":"object","properties":{"field":{"type":"string","description":"Sort field name. Any numeric field returned by the endpoint is supported (e.g. revenue, sales_volumn, revenue_growth_rate).","example":"revenue"},"type":{"type":"string","description":"Sort direction.","example":"DESC","enum":["ASC","DESC"]}},"description":"Sort spec. `field` accepts any numeric field from the response; `type` is ASC or DESC. Defaults to `{\"field\":\"revenue\",\"type\":\"DESC\"}`.","additionalProperties":false},"MarketIntelligenceVideoDetailReq":{"required":["currency","date_range","language","region","video_id"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"video_id":{"type":"string","description":"Video ID to query.","example":"7404191282148511007"},"need_extra":{"type":"boolean","description":"Need Extra Info","example":false}},"additionalProperties":false},"MarketIntelligenceVideoDetailRes":{"type":"object","properties":{"video_id":{"type":"string","description":"Video ID","example":"7627814494370057503"},"video_region":{"type":"string","description":"Video country/region","example":"US"},"video_title":{"type":"string","description":"Video title","example":"Product Review: Best Tech of 2024"},"belonged_creator_id":{"type":"string","description":"Creator ID of the video","example":"7434060602055984170"},"belonged_creator_handle":{"type":"string","description":"Creator handle of the video","example":"techreviewer"},"product_number":{"type":"integer","description":"Number of products attached to the video","format":"int32","example":5},"revenue":{"type":"number","description":"Revenue of the video within the selected time range","format":"double","example":2500.75},"sales_volumn":{"type":"integer","description":"Sales volume of the video within the selected time range","format":"int32","example":45},"views":{"type":"integer","description":"Views of the video within the selected time range","format":"int32","example":150000},"video_gpm":{"type":"number","description":"Revenue per thousand views (GPM) of the video within the selected time range","format":"double","example":16.67},"ads_views":{"type":"integer","description":"Ad views of the video","format":"int32","example":12000},"ads_roas":{"type":"number","description":"ROAS (Return on Ad Spend) of the video ads","format":"double","example":3.5},"ads_period":{"type":"integer","description":"Ad campaign duration in days within the selected time range","format":"int32","example":7},"digg_count":{"type":"integer","description":"Like count","format":"int32","example":15000},"share_count":{"type":"integer","description":"Share count","format":"int32","example":2500},"comment_count":{"type":"integer","description":"Comment count","format":"int32","example":800},"ad_cpa":{"type":"number","description":"Single transaction advertising cost of the video under specified date","format":"double","example":3500.25},"revenue_trend":{"type":"array","description":"revenue trend within the selected time range (day-by-day series in the response currency)","example":[50000,62000],"items":{"type":"number","description":"revenue trend within the selected time range (day-by-day series in the response currency)","format":"double"}},"ad":{"type":"integer","description":"Whether this video is an ad video. 1 = ad, 0 = organic.","format":"int32","example":1,"enum":[0,1]},"ad_view_ratio":{"type":"number","description":"Ad view ratio","format":"double","example":0.12},"duration":{"type":"number","description":"duration(s)","format":"double","example":12},"ai_video":{"type":"integer","description":"Whether the video is AI-generated (1: yes, 0: no)","format":"int32","example":1}}},"MarketIntelligenceVideoRankReq":{"required":["currency","date_range","language","region","sort_field"],"type":"object","properties":{"region":{"type":"string","description":"Data country code, e.g. US, BR, MX, ID, JP, MY, PH, SG, TH, VN, GB, ES, DE, FR, IT.","example":"US","enum":["US","BR","MX","ID","JP","MY","PH","SG","TH","VN","GB","ES","DE","FR","IT"]},"language":{"type":"string","description":"Language for text fields in the response. Currently supports zh-CN, en-US, id-ID, th-TH, vi-VN, es-ES, ja-JP, pt-BR, ko-KR, fr-FR.","example":"en-US","enum":["zh-CN","en-US","id-ID","th-TH","vi-VN","es-ES","ja-JP","pt-BR","ko-KR","fr-FR"]},"currency":{"type":"string","description":"Currency unit for revenue and price fields. Currently supports CNY, USD, IDR, VND, THB, MYR, JPY, PHP, GBP, SGD, MXN, EUR, BRL.","example":"USD","enum":["CNY","USD","IDR","VND","THB","MYR","JPY","PHP","GBP","SGD","MXN","EUR","BRL"]},"date_range":{"type":"string","description":"Date range. Accepts named ranges (lastDay, last7Day, last30Day, last60Day, last90Day, last180Day, last365Day), a natural date range in `yyyy-MM-dd~yyyy-MM-dd` form, or a natural month `yyyy-MM`. Some endpoints restrict this set — see the per-endpoint description.","example":"last7Day"},"sort_field":{"$ref":"#/components/schemas/MarketIntelligenceSortFieldReq"},"rank_field":{"type":"string","description":"Legacy shortcut for the sort field name; prefer `sort_field`. Ignored when `sort_field` is set.","example":"revenue"},"asc":{"type":"boolean","description":"Legacy ascending flag paired with `rank_field`. Default false (DESC).","example":false},"page_size":{"type":"integer","description":"Page size. Minimum 10 and maximum 100 records per query. Default 10.","format":"int32","example":20,"maximum":100,"minimum":10},"page_number":{"type":"integer","description":"Page number, starting at 1. ","format":"int32","example":1,"minimum":1},"category_ids":{"type":"array","description":"Restrict results to videos in the given category IDs.","example":["700645","223"],"items":{"type":"string","description":"Restrict results to videos in the given category IDs.","example":"[\"700645\",\"223\"]"}},"shop_id":{"type":"string","description":"Restrict results to videos promoting the given shop's products.","example":"7494965300835814281"},"creator_id":{"type":"string","description":"Restrict results to videos published by the given creator.","example":"7146196785349985326"},"product_id":{"type":"string","description":"Restrict results to videos mounting the given product.","example":"1729587769570529799"},"revenue_range":{"type":"string","description":"Revenue range filter, in the same currency as the request `currency`. Also supports `<100` / `>1000` forms.","example":"1-100"},"followers_range":{"type":"string","description":"Follower count range of the video's creator.","example":"1000-10000"},"ads_roas":{"type":"string","description":"Estimated ad ROAS filter. Accepts a single value, a range (`1-2.5`), or open-ended (`<1`, `>5`).","example":"1-2.5"},"keyword":{"type":"string","description":"Keyword for video search","example":"fashion"},"is_ai_video":{"type":"integer","description":"Filter videos by AI-generated flag. 1: only AI videos; 0: only non-AI videos; null: no filter","format":"int32","example":1}},"additionalProperties":false},"MarketIntelligenceVideoRankRes":{"type":"object","properties":{"video_id":{"type":"string","description":"Video ID","example":"7627814494370057503"},"video_title":{"type":"string","description":"Video title content","example":"Sweet girl essential!"},"belonged_creator_id":{"type":"string","description":"Creator ID that the video belongs to","example":"7434060602055984170"},"belonged_creator_handle":{"type":"string","description":"Creator handle that the video belongs to","example":"techreviewer"},"revenue":{"type":"number","description":"Revenue of the video under specified date and category","format":"double","example":3500.25},"views":{"type":"integer","description":"Views of the video within the selected time range","format":"int32","example":250000},"revenue_growth_rate":{"type":"number","description":"Revenue growth rate of the video","format":"double","example":15.5},"ads_roas":{"type":"number","description":"ROAS (Return on Ad Spend) of the video within the selected time range","format":"double","example":4.2},"digg_count":{"type":"integer","description":"Like count","format":"int32","example":15000},"share_count":{"type":"integer","description":"Share count","format":"int32","example":2500},"comment_count":{"type":"integer","description":"Comment count","format":"int32","example":800},"ad_revenue_ratio":{"type":"number","description":"Ad revenue ratio","format":"double","example":0.35},"ad_view_ratio":{"type":"number","description":"Ad view ratio","format":"double","example":0.12},"creator_debut":{"type":"string","description":"Video debut time","example":"2024-01-15"},"ad":{"type":"integer","description":"Whether this video is an ad video. 1 = ad, 0 = organic.","format":"int32","example":1,"enum":[0,1]},"ai_video":{"type":"integer","description":"Whether the video is AI-generated (1: yes, 0: no)","format":"int32","example":1}}},"MarketIntelligenceError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"securitySchemes":{"openApiKey":{"type":"http","scheme":"bearer","bearerFormat":"Euka OpenAPI key","description":"Use `Authorization: Bearer euka_openapi_...`."}}}}