> ## 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 details > Ad Campaigns. Read only. Shows one ad with its creative, targeting, status and performance metrics. ### Google Search ads Google Search ads include current creative.headlines, creative.descriptions and creative.finalUrls, preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read. RSA enrichment requires a stored advertisingChannelType of SEARCH. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** GET /apis/v1/ads/\{adId} * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/{adId}` * **adId:** path; 必填 * **connectionId:** query; 必填 * **live:** 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", "method": "GET", "path": "/apis/v1/ads/{adId}", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "See description for details.", "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": "Read the on/off switches live from the platform instead of returning synced values. See \"Status freshness\" in the operation description.", "in": "query", "name": "live", "required": false, "schema": { "default": false, "type": "boolean" } } ], "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} 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}: get: summary: Get ad details description: >- Ad Campaigns. Read only. Shows one ad with its creative, targeting, status and performance metrics. ### Google Search ads Google Search ads include current creative.headlines, creative.descriptions and creative.finalUrls, preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read. RSA enrichment requires a stored advertisingChannelType of SEARCH. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: get_aisa_ads_apis_v1_ads_adid parameters: - description: See description for details. 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: >- Read the on/off switches live from the platform instead of returning synced values. See "Status freshness" in the operation description. in: query name: live required: false schema: default: false type: boolean responses: '200': content: application/json: schema: properties: ad: properties: _id: type: string adSetName: type: string adType: enum: - boost - standalone type: string bidAmount: description: >- Bid amount in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100). Meta: `bid_amount` on the ad set (smallest-denomination int, decoded here). type: - number - 'null' bidStrategy: anyOf: - description: >- Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules: `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string - type: 'null' description: >- Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and TikTok. budget: properties: amount: type: number daily: description: >- LinkedIn and X only. The daily budget (LinkedIn: the parent campaign's `dailyBudget`; X: the line item's, or the campaign's when the line item has none). type: number lifetime: description: >- LinkedIn and X only. The lifetime total (LinkedIn: the parent campaign's `totalBudget`; X: `total_budget_amount_local_micro`, for example the `lifetimeBudgetCap` of a boost), readable even when a daily budget is also set. type: number pacing: description: >- LinkedIn only. The campaign's `pacingStrategy`: how fast LinkedIn may spend the budget. Typically LINEAR or ACCELERATED; the list is open. type: string type: enum: - daily - lifetime type: string type: - object - 'null' campaignName: type: string configuredStatus: description: >- The ad's own on/off switch as configured on the platform, independent of its parents. An ACTIVE ad under a paused ad set or campaign still reads ACTIVE here while `status` reads `paused`. Sources: Meta: `configured_status`. type: - string - 'null' costType: description: >- LinkedIn only. The campaign's EFFECTIVE cost model (billing event) as applied by LinkedIn, refreshed on every sync rather than echoing what was passed on create. `null` for non-LinkedIn ads. `CPM`: cost per thousand impressions. type: - string - 'null' createdAt: format: date-time type: string creative: description: >- Platform-specific creative data. Fields vary by platform. properties: adFormat: description: >- LinkedIn only. The LinkedIn ad format, in LinkedIn's own vocabulary: STANDARD_UPDATE, SINGLE_VIDEO, CAROUSEL, NATIVE_DOCUMENT, EVENT, TEXT_AD, SPOTLIGHT, FOLLOW_COMPANY, JOBS, SPONSORED_INMAILS and others. type: - string - 'null' assetGroup: description: >- Google Performance Max creative assets. At least one description must be 60 characters or fewer. Texts within each list must be distinct. properties: businessName: maxLength: 25 minLength: 1 type: string descriptions: description: >- At least one description must be 60 characters or fewer. items: maxLength: 90 minLength: 1 type: string maxItems: 5 minItems: 2 type: array uniqueItems: true finalUrl: description: Required destination URL. format: uri pattern: ^https?:// type: string headlines: items: maxLength: 30 minLength: 1 type: string maxItems: 15 minItems: 3 type: array uniqueItems: true images: additionalProperties: true description: >- Public HTTP(S) image URLs. GIF, JPEG or PNG, at most 5120 KB per image. Google validates dimensions and aspect ratios. type: object longHeadline: maxLength: 90 minLength: 1 type: string name: description: Defaults to the request name. maxLength: 128 minLength: 1 type: string youtubeVideoId: description: >- Optional existing YouTube video id. Google can generate video when omitted. Video uploads and arbitrary video URLs are not supported. pattern: ^[A-Za-z0-9_-]{11}$ type: string required: - businessName - descriptions - finalUrl - headlines - images - longHeadline type: object assetGroupResourceName: description: >- Google resource name of the created Performance Max asset group. type: string assetResourceName: description: >- Google Display only. Resource name of the landscape marketing image asset (`creative.imageUrl`), for example customers/1234567890/assets/123. type: string assets: description: >- Google Display only. Native Google asset resource name of each image on the responsive display ad, keyed by Google's image role. properties: marketingImages: description: >- Landscape (1.91:1) marketing images. The first item matches `assetResourceName`. items: additionalProperties: true type: object type: array squareMarketingImages: description: Square (1:1) marketing images. items: additionalProperties: true type: object type: array type: object bodies: description: >- Meta: every primary text variation of the creative (`asset_feed_spec.bodies`), the same shape as the `bodies` create input. Present only with 2 or more texts; a single text is `body`. items: type: string type: array body: description: Ad copy/text type: string callToAction: description: >- Meta: the call to action type (`call_to_action.type`, or the first `asset_feed_spec.call_to_action_types` entry), e.g. LEARN_MORE or SIGN_UP. type: string carouselCards: description: >- Meta only today. The carousel's cards in display order, one per Meta `link_data.child_attachments` entry, using the same field names as the `carouselCards` create input. Absent on non-carousel ads and other platforms. items: additionalProperties: true type: object type: array catalog: properties: format: description: >- object_story_spec.template_data.format_option, from catalogFormat. enum: - single_image - carousel_images_multi_items - carousel_images_single_item - carousel_slideshows type: string formatTransformationSpec: description: >- The format_transformation_spec sent on the creative, as Meta's raw objects. Present for single_image. items: additionalProperties: true type: object type: array productSetId: description: The creative's product_set_id. type: string type: object creativeFeatures: additionalProperties: enum: - OPT_IN - OPT_OUT type: string description: >- Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. type: object creativeId: description: >- Meta ad creative id backing this ad, refreshed from Meta on every sync. Reusable via existingCreativeId on POST /apis/v1/ads/create, and readable raw through GET /apis/v1/ads/creatives/{creativeId}. type: - string - 'null' description: description: >- Meta: the creative's description under the title (`link_data.description`, `video_data.link_description`, or the first `asset_feed_spec.descriptions` entry). type: string descriptions: description: >- Google RSA: the description assets as objects (2 to 4). Meta: every description variation of the creative (`asset_feed_spec.descriptions`) as strings, the same shape as the `descriptions` create input. items: oneOf: - type: string - additionalProperties: true type: object maxItems: 4 type: array effectiveInstagramMediaId: description: >- Meta `effective_instagram_media_id`, the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /apis/v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad. type: - string - 'null' effectiveObjectStoryId: description: >- Meta `effective_object_story_id`, the `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. type: - string - 'null' finalUrls: description: >- Google RSA only. Replaces final URLs. Omitted lists stay unchanged. items: format: uri type: string minItems: 1 type: array googleDescription: description: Google Ads description type: string googleHeadline: description: Google Ads headline type: string headline: description: >- Meta: the creative's title (`link_data.name`, `video_data.title`, or the first `asset_feed_spec.titles` entry). Absent when the creative has none. type: string headlines: description: >- Google RSA: the headline assets as objects (3 to 15). Meta: every title variation of the creative (`asset_feed_spec.titles`) as strings, the same shape as the `headlines` create input. items: oneOf: - type: string - additionalProperties: true type: object maxItems: 15 type: array imageHash: description: >- Meta: the ad image hash (`image_hash`), reusable as `imageHash` on POST /apis/v1/ads/create within the same ad account. `thumbnailUrl` and `mediaUrls` carry its stable full resolution permalink when Meta resolves it. type: string imageUrl: description: Alternative image URL type: string instagramPermalinkUrl: description: >- Meta `instagram_permalink_url`, the public Instagram post URL of the boosted media. type: - string - 'null' instagramUserId: description: >- Meta `instagram_user_id`, the Instagram-scoped business ID that owns the boosted media. type: - string - 'null' instagramVideoFallback: description: >- Meta only. `instagram_video_reuploaded`: the video was copied into the ad account, and the ad still references the original post. properties: kind: enum: - instagram_video_reuploaded - instagram_video_rehosted_copy type: string linkedToOriginalPost: description: >- True when the ad still references the original Instagram post and keeps its engagement. type: boolean platformError: additionalProperties: true description: Meta's original refusal. type: object videoId: description: >- instagram_video_reuploaded: the copy in the ad account video library (possibly one made by an earlier boost of the same media, reused). type: string required: - kind - linkedToOriginalPost - platformError - videoId type: object isServing: description: >- LinkedIn only. Whether LinkedIn is currently serving this specific creative. Complements the ad-level `servingStatuses`, which describes the parent campaign. type: - boolean - 'null' leadGenFormId: description: >- Meta: the instant form the call to action opens (`call_to_action.value.lead_gen_form_id`, or the asset feed's `call_to_actions` on a dynamic creative), the same value as the `leadGenFormId` create input. Absent on ads without a lead form. type: string linkUrl: description: Destination URL type: string mediaUrls: description: >- All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts). items: type: string type: array objectStoryId: description: >- Meta creative `object_story_id` (the SHARE reference). Frequently absent, because Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead. type: - string - 'null' objectType: description: >- Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews: when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available. type: string pageId: description: >- Facebook Page backing the creative (Meta only). What the `pageId` filter on /apis/v1/ads, /apis/v1/ads/campaigns and /apis/v1/ads/tree matches against. Absent for non-Meta ads and rare Meta creatives with no page signal. type: - string - 'null' pinterestDescription: type: string pinterestImageUrl: type: string pinterestTitle: type: string servingHoldReasons: description: >- LinkedIn only. Why this specific creative is not being served. Empty when it is serving. items: type: string type: array thumbnailUrl: description: Primary thumbnail/image URL type: - string - 'null' urlTags: description: >- Meta: the creative's `url_tags` query string appended to the destination URL. type: - string - 'null' videoId: description: >- Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token. type: - string - 'null' videoUrl: description: Null for non-video ads. type: - string - 'null' whatsappPhoneNumber: description: >- Explicit E.164 WhatsApp number supplied when creating a Meta boost or messaging ad. Absent when omitted by the caller or on older records. type: string youtubeVideoIds: description: >- Google only. YouTube video ids behind a Video campaign ad (video and responsive video ads) or a Demand Gen video ad, same id as `youtubeVideoId` on Performance Max asset groups. items: type: string type: array type: - object - 'null' creativeType: description: >- Creative format, classified from the media the creative carries. `null` when the creative carries no media to classify. An unsynced creative and a genuine text-only ad are indistinguishable, so neither is guessed at. enum: - carousel - video - document - image - null type: - string - 'null' goal: description: 'Available goals vary by platform:' enum: - engagement - traffic - awareness - video_views - lead_generation - lead_conversion - conversions - app_promotion - catalog_sales - page_likes - page_visits - job_applicants type: string isExternal: description: True for ads synced from platform ad managers type: boolean metrics: anyOf: - 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 - type: 'null' name: type: string optimizationGoal: description: >- What the delivery system optimizes for, at ad-set level. The value space depends on `platform`: Meta: ad set `optimization_goal` (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). type: - string - 'null' platform: enum: - facebook - instagram - tiktok - linkedin - pinterest - google - twitter - openai - reddit - microsoft type: string platformAdAccountId: type: string platformAdAccountName: description: >- Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok `advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every sync so platform-side renames propagate within one cycle. type: - string - 'null' platformAdId: type: string platformAdSetId: type: string platformCampaignId: type: string platformCreatedAt: description: >- Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`). Read this field to sort or filter by when the ad was actually created on the platform. format: date-time type: - string - 'null' platformObjective: description: >- The platform's own campaign objective, verbatim, alongside the normalized `goal` it maps to. The mapping is many-to-one, so `goal` alone cannot be mapped back to it. Meta: campaign `objective` (e.g. type: - string - 'null' promotedObject: description: >- Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads. properties: application_id: description: Facebook app ID type: string custom_event_type: description: >- Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART) type: string page_id: description: Facebook page ID type: string pixel_id: description: Meta pixel ID type: string product_set_id: description: Product catalog set ID type: string type: - object - 'null' rejectionReason: type: string reviewStatus: description: >- Platform review state of this ad, independent of delivery `status` / `configuredStatus`. Absent when the platform reports no review signal. enum: - in_review - approved - rejected - with_issues type: string roasAverageFloor: description: >- Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy is `LOWEST_COST_WITH_MIN_ROAS`. type: - number - 'null' schedule: description: Delivery window as UTC instants. properties: endDate: format: date-time type: string startDate: format: date-time type: string type: - object - 'null' servingStatuses: description: >- LinkedIn only. Why the parent campaign is (or is not) delivering, verbatim from LinkedIn. A campaign can report `status: ACTIVE` and still serve nothing; this array says so. items: type: string type: array status: description: >- Delivery status. Derived from the platform `effective_status`, so it inherits ancestor pauses (an ACTIVE ad under a PAUSED campaign reads `paused`). enum: - active - paused - pending_review - rejected - completed - cancelled - error type: string synced: description: >- Only on GET /apis/v1/ads/{adId}. An unsynced ad has no `id`. type: boolean targeting: description: >- The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions). May be absent if the ad set exposes no targeting or the lookup fails. type: object updatedAt: format: date-time type: string type: object cachedAt: description: Google RSA details cache timestamp. format: date-time type: - string - 'null' darkPost: description: >- Only when `{adId}` is a Facebook ad dark post with no resolvable ad (then `ad` is null). properties: adId: description: >- Always null: Meta exposes no link from a placement dark post to its ad. type: - string - 'null' connectionId: description: The ads connection (adc_...) the object belongs to. type: - string - 'null' firstSeenAt: format: date-time type: string isDarkPost: description: Always true. type: boolean lastActivityAt: format: date-time type: string pageId: type: string platform: enum: - facebook type: string platformAdAccountIds: description: >- Meta ad accounts (`act_...`) with synced ads on this Page. items: type: string type: array platformPostId: description: The dark post id, `{pageId}_{postId}`. type: string type: object stale: description: >- Whether Google RSA details use the last successful cached response. type: boolean statusReadAt: description: >- With `live=true`, when the switches were read from the platform; null when the live read failed and the stored values were returned. Always set on an unsynced Meta ad read with `connectionId`, the time of that read. format: date-time type: - string - 'null' type: object description: Ad details 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.