> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # Get ad analytics > Ad Insights. Read only. Returns one ad's performance summary and daily timeline, with optional audience breakdowns on Meta, TikTok and LinkedIn. It includes summary metrics, a daily timeline over the requested date range, and optional demographic breakdowns (Meta, TikTok and LinkedIn only). If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max. ### History 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** GET /apis/v1/ads/\{adId}/analytics * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/{adId}/analytics` * **adId:** path; 必填 * **connectionId:** query; 必填 * **fromDate:** query; 可选 * **toDate:** query; 可选 * **breakdowns:** query; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "get_aisa_ads_apis_v1_ads_adid_analytics", "method": "GET", "path": "/apis/v1/ads/{adId}/analytics", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "in": "path", "name": "adId", "required": true, "schema": { "type": "string" } }, { "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.", "in": "query", "name": "connectionId", "required": true, "schema": { "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" } }, { "description": "Start of date range (YYYY-MM-DD). Defaults to 90 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.", "in": "query", "name": "breakdowns", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-ads.json GET /apis/v1/ads/{adId}/analytics openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/{adId}/analytics: get: summary: Get ad analytics description: >- Ad Insights. Read only. Returns one ad's performance summary and daily timeline, with optional audience breakdowns on Meta, TikTok and LinkedIn. It includes summary metrics, a daily timeline over the requested date range, and optional demographic breakdowns (Meta, TikTok and LinkedIn only). If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max. ### History 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: get_aisa_ads_apis_v1_ads_adid_analytics parameters: - in: path name: adId required: true schema: type: string - description: >- The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead. in: query name: connectionId required: true schema: pattern: ^adc_[0-9A-Za-z]+$ type: string - description: Start of date range (YYYY-MM-DD). Defaults to 90 days ago. in: query name: fromDate required: false schema: format: date type: string - description: >- End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range. in: query name: toDate required: false schema: format: date type: string - description: >- Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset. in: query name: breakdowns required: false schema: type: string responses: '200': content: application/json: schema: properties: ad: properties: currency: description: >- ISO 4217 code of the ad account that owns this ad (e.g. USD, THB, INR). All money values in `summary` and `daily` are in this currency. Null only on legacy ads synced before currency was persisted. type: - string - 'null' id: type: string name: type: string platform: type: string status: type: string type: object analytics: properties: breakdownDroppedMetrics: additionalProperties: items: type: string type: array description: >- TikTok only: metric names TikTok refused for a breakdown, keyed by the requested breakdown (e.g. total_purchase and total_purchase_value have no relation to platform, ac or language). Absent when no metric was refused. type: object breakdownErrors: description: >- TikTok only: breakdowns the platform failed to return (rate limit, permission, rejected query). Each one is an empty array under breakdowns; summary and daily are unaffected. Absent when every breakdown answered. items: properties: breakdown: type: string message: description: The platform's error message. type: string type: object type: array breakdownHints: additionalProperties: type: string description: >- Guidance for some names in unsupportedBreakdowns, keyed by that name (e.g. placement on Meta points at publisher_platform and platform_position; platform_position on TikTok points at placement). Absent when no unsupported name has a hint. type: object breakdowns: additionalProperties: items: additionalProperties: true type: object type: array description: >- Requested demographic breakdowns, keyed by dimension. Fetched live from the platform per request and never stored, so these rows can carry fields the stored `summary` and `daily` series do not. type: object breakdownsRange: description: >- TikTok only, present when the requested range is longer than the 365 days TikTok serves per breakdown: the window the breakdowns cover (the last 365 days of the range). summary and daily still cover the full range. properties: fromDate: format: date type: string toDate: format: date type: string type: object daily: items: properties: actionValues: additionalProperties: true description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: true description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: true description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number date: format: date type: string engagement: type: integer engagementBreakdown: additionalProperties: true description: >- The single `engagement` total, split into the interactions behind it. type: object funnel: additionalProperties: true description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object type: array summary: properties: actionValues: additionalProperties: type: number description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: type: integer description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: type: number description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number engagement: type: integer engagementBreakdown: description: >- The single `engagement` total, split into the interactions behind it. properties: comments: description: Comments on the ad's post. type: integer linkClicks: description: >- Attributed link clicks (`link_click`). This is the attribution-window count, which differs from the in-session count in the sibling `inlineLinkClicks` field. type: integer pageEngagement: description: >- Meta's own page-engagement total (`page_engagement`). Meta-only. type: integer pageLikes: description: New Page likes attributed to the ad (`like`). type: integer postEngagement: description: >- Meta's own post-engagement total (`post_engagement`). Meta-only. type: integer reactions: description: >- Reactions on the ad's post (`post_reaction`). For TikTok these are its paid likes. type: integer saves: description: >- Saves of the ad's post (`onsite_conversion.post_save`). type: integer shares: description: >- Shares of the ad's post. Meta reports these under the action type literally named `post`; TikTok under `share`. type: integer videoViews: description: >- Video views, from the `video_view` action. Meta counts a 3-second view; LinkedIn's own `videoViews` threshold (2 continuous seconds, or 25% of the video) lands under the same key, so compare across platforms with care. type: integer type: object funnel: description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. properties: appInstalls: description: Mobile app installs attributed to the ad. type: integer cartAdds: description: Adds to cart (Meta `AddToCart` pixel event). type: integer checkoutsInitiated: description: >- Checkouts started (Meta `InitiateCheckout` pixel event). type: integer contentViews: description: >- Content views (Meta `ViewContent` pixel event). type: integer landingPageViews: description: >- Landing page views: the visitor actually loaded the destination, unlike a link click. Meta `landing_page_view`. type: integer leads: description: >- Leads, from either the website pixel or an instant form, whichever the ad uses. type: integer messagingConversationsStarted: description: >- Messaging conversations started within 7 days, the headline metric for click-to-WhatsApp and click-to-Messenger ads. type: integer messagingFirstReplies: description: >- Messaging threads where the person sent a first reply. type: integer paymentInfoAdds: description: >- Payment details added at checkout (Meta `AddPaymentInfo` pixel event). type: integer purchases: description: >- Purchases. Pair with `purchaseValue` for revenue. type: integer registrationsCompleted: description: >- Completed registrations (Meta `CompleteRegistration` pixel event). type: integer searches: description: On-site searches (Meta `Search` pixel event). type: integer wishlistAdds: description: >- Adds to wishlist (Meta `AddToWishlist` pixel event). type: integer type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object unsupportedBreakdowns: description: >- Requested breakdowns this platform cannot break down by (e.g. region on TikTok, any breakdown on Google). Absent when every requested breakdown is supported. items: type: string type: array type: object backfillPending: description: >- Meta only. Present and true while historical data is being backfilled. type: boolean type: object description: Ad analytics '202': content: application/json: schema: properties: ad: properties: currency: description: >- ISO 4217 code of the ad account that owns this ad (e.g. USD, THB, INR). All money values in `summary` and `daily` are in this currency. Null only on legacy ads synced before currency was persisted. type: - string - 'null' id: type: string name: type: string platform: type: string status: type: string type: object analytics: properties: breakdownDroppedMetrics: additionalProperties: items: type: string type: array description: >- TikTok only: metric names TikTok refused for a breakdown, keyed by the requested breakdown (e.g. total_purchase and total_purchase_value have no relation to platform, ac or language). Absent when no metric was refused. type: object breakdownErrors: description: >- TikTok only: breakdowns the platform failed to return (rate limit, permission, rejected query). Each one is an empty array under breakdowns; summary and daily are unaffected. Absent when every breakdown answered. items: properties: breakdown: type: string message: description: The platform's error message. type: string type: object type: array breakdownHints: additionalProperties: type: string description: >- Guidance for some names in unsupportedBreakdowns, keyed by that name (e.g. placement on Meta points at publisher_platform and platform_position; platform_position on TikTok points at placement). Absent when no unsupported name has a hint. type: object breakdowns: additionalProperties: items: additionalProperties: true type: object type: array description: >- Requested demographic breakdowns, keyed by dimension. Fetched live from the platform per request and never stored, so these rows can carry fields the stored `summary` and `daily` series do not. type: object breakdownsRange: description: >- TikTok only, present when the requested range is longer than the 365 days TikTok serves per breakdown: the window the breakdowns cover (the last 365 days of the range). summary and daily still cover the full range. properties: fromDate: format: date type: string toDate: format: date type: string type: object daily: items: properties: actionValues: additionalProperties: true description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: true description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: true description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number date: format: date type: string engagement: type: integer engagementBreakdown: additionalProperties: true description: >- The single `engagement` total, split into the interactions behind it. type: object funnel: additionalProperties: true description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object type: array summary: properties: actionValues: additionalProperties: type: number description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: type: integer description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: type: number description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number engagement: type: integer engagementBreakdown: description: >- The single `engagement` total, split into the interactions behind it. properties: comments: description: Comments on the ad's post. type: integer linkClicks: description: >- Attributed link clicks (`link_click`). This is the attribution-window count, which differs from the in-session count in the sibling `inlineLinkClicks` field. type: integer pageEngagement: description: >- Meta's own page-engagement total (`page_engagement`). Meta-only. type: integer pageLikes: description: New Page likes attributed to the ad (`like`). type: integer postEngagement: description: >- Meta's own post-engagement total (`post_engagement`). Meta-only. type: integer reactions: description: >- Reactions on the ad's post (`post_reaction`). For TikTok these are its paid likes. type: integer saves: description: >- Saves of the ad's post (`onsite_conversion.post_save`). type: integer shares: description: >- Shares of the ad's post. Meta reports these under the action type literally named `post`; TikTok under `share`. type: integer videoViews: description: >- Video views, from the `video_view` action. Meta counts a 3-second view; LinkedIn's own `videoViews` threshold (2 continuous seconds, or 25% of the video) lands under the same key, so compare across platforms with care. type: integer type: object funnel: description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. properties: appInstalls: description: Mobile app installs attributed to the ad. type: integer cartAdds: description: Adds to cart (Meta `AddToCart` pixel event). type: integer checkoutsInitiated: description: >- Checkouts started (Meta `InitiateCheckout` pixel event). type: integer contentViews: description: >- Content views (Meta `ViewContent` pixel event). type: integer landingPageViews: description: >- Landing page views: the visitor actually loaded the destination, unlike a link click. Meta `landing_page_view`. type: integer leads: description: >- Leads, from either the website pixel or an instant form, whichever the ad uses. type: integer messagingConversationsStarted: description: >- Messaging conversations started within 7 days, the headline metric for click-to-WhatsApp and click-to-Messenger ads. type: integer messagingFirstReplies: description: >- Messaging threads where the person sent a first reply. type: integer paymentInfoAdds: description: >- Payment details added at checkout (Meta `AddPaymentInfo` pixel event). type: integer purchases: description: >- Purchases. Pair with `purchaseValue` for revenue. type: integer registrationsCompleted: description: >- Completed registrations (Meta `CompleteRegistration` pixel event). type: integer searches: description: On-site searches (Meta `Search` pixel event). type: integer wishlistAdds: description: >- Adds to wishlist (Meta `AddToWishlist` pixel event). type: integer type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object unsupportedBreakdowns: description: >- Requested breakdowns this platform cannot break down by (e.g. region on TikTok, any breakdown on Google). Absent when every requested breakdown is supported. items: type: string type: array type: object backfillPending: description: >- Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200. type: boolean required: - backfillPending type: object description: >- Meta only. Historical data is incomplete and backfill remains pending. default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.