> ## 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 # Boost post as ad > Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Boosts a published post as an ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Turns an already published post into a paid ad that keeps the post's likes and comments, creating the campaign around it. By default it provisions the whole hierarchy (campaign, ad set, ad). ### Attach shape (Meta) Send `adSetId` to put the ad under an EXISTING ad set instead, so that ad set keeps its learning phase. That ad set then owns `budget`, `schedule` and `targeting`. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** POST /apis/v1/ads/boost * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/boost` * **connectionId:** query; 必填 * **X-Aisa-Confirm:** header; 可选 * **Idempotency-Key:** header; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "post_aisa_ads_apis_v1_ads_boost", "method": "POST", "path": "/apis/v1/ads/boost", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "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": "Required with the value \"spend\" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform.", "in": "header", "name": "X-Aisa-Confirm", "required": false, "schema": { "enum": [ "spend" ], "type": "string" } }, { "description": "Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 191, "minLength": 1, "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "adAccountId": "act_757082720485182", "budget": { "amount": 2.61, "type": "daily" }, "callToAction": "WHATSAPP_MESSAGE", "connectionId": "adc_7f3k2m9q", "goal": "engagement", "name": "WhatsApp post boost", "platformPostId": "811889972008357_123456789", "status": "PAUSED", "whatsappPhoneNumber": "+12025550123" }, "schema": { "additionalProperties": true, "properties": { "adAccountId": { "description": "Platform ad account ID", "type": "string" }, "adSetId": { "description": "Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign. Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "type": "string" }, "adSetName": { "description": "Exact name for the ad-group level this boost provisions. Omitted keeps the default ` - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group.", "maxLength": 255, "type": "string" }, "adSetStatus": { "description": "Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`.", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "adStatus": { "description": "Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused`…", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "attributionSpec": { "description": "Meta only. Ad-set attribution windows, same shape as POST /apis/v1/ads/create.", "items": { "properties": { "eventType": { "enum": [ "CLICK_THROUGH", "VIEW_THROUGH", "ENGAGED_VIDEO_VIEW" ], "type": "string" }, "windowDays": { "enum": [ 1, 7, 28 ], "type": "integer" } }, "required": [ "eventType", "windowDays" ], "type": "object" }, "maxItems": 3, "minItems": 1, "type": "array" }, "bidAmount": { "description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.", "type": "number" }, "bidStrategy": { "description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.", "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP", "COST_CAP", "LOWEST_COST_WITH_MIN_ROAS" ], "type": "string" }, "bodies": { "description": "Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media.", "items": { "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "budget": { "description": "Alias of budgetAmount + budgetType, kept for existing callers", "properties": { "amount": { "description": "Minimum varies: TikTok=$20, Pinterest=$5, others=$1", "type": "number" }, "type": { "enum": [ "daily", "lifetime" ], "type": "string" } }, "required": [ "amount", "type" ], "type": "object" }, "budgetAmount": { "description": "Budget in whole currency units, the same flat field as POST /apis/v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1", "type": "number" }, "budgetLevel": { "description": "Meta only, same semantics as POST /apis/v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId.", "enum": [ "adset", "campaign" ], "type": "string" }, "budgetType": { "description": "Goes together with budgetAmount. lifetime requires schedule.endDate.", "enum": [ "daily", "lifetime" ], "type": "string" }, "callToAction": { "description": "CTA button label. Non-messaging CTAs require `linkUrl`. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl.", "type": "string" }, "campaignName": { "description": "Exact name for the campaign this boost provisions. Omitted keeps the default ` - Campaign`. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (`adSetId`), which creates no campaign.", "maxLength": 255, "type": "string" }, "campaignStatus": { "description": "Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides `status` for it. When omitted, it follows `status`.", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "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" }, "currency": { "description": "ISO 4217 currency code matching the ad account's currency. Meta only.", "maxLength": 3, "minLength": 3, "type": "string" }, "destinationType": { "description": "Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal.", "enum": [ "INSTAGRAM_PROFILE", "WEBSITE", "ON_AD", "MESSENGER", "WHATSAPP", "INSTAGRAM_DIRECT" ], "type": "string" }, "dsaBeneficiary": { "description": "Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26).", "maxLength": 100, "type": "string" }, "dsaPayor": { "description": "Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor.", "maxLength": 100, "type": "string" }, "endDate": { "description": "Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /apis/v1/ads/create. Maps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates).", "format": "date-time", "type": "string" }, "existingCampaignId": { "description": "TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit `goal`). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "type": "string" }, "goal": { "description": "Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion.", "enum": [ "engagement", "traffic", "awareness", "video_views", "lead_generation", "conversions", "app_promotion" ], "type": "string" }, "identityId": { "description": "TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /apis/v1/ads/tiktok-identities. Default: the connected TikTok account's own identity.", "type": "string" }, "identityType": { "description": "TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted.", "enum": [ "TT_USER", "CUSTOMIZED_USER", "BC_AUTH_TT" ], "type": "string" }, "instagramAccountId": { "description": "Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative.", "type": "string" }, "leadGenFormId": { "description": "Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals. Meta: the leadgen_forms ID (create one via POST /apis/v1/ads/lead-forms).", "type": "string" }, "lifetimeBudgetCap": { "description": "X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount.", "exclusiveMinimum": 0, "type": "number" }, "linkUrl": { "description": "Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts. Meta: adds a top-level `call_to_action` to the post-reference creative.", "format": "uri", "type": "string" }, "locationTargetingType": { "description": "Google only (400 elsewhere). Written on the campaign the boost creates.", "enum": [ "presence", "presence_or_interest" ], "type": "string" }, "metaObjective": { "description": "Meta only, with `goal: engagement` and without `adSetId` (400 otherwise).", "enum": [ "OUTCOME_ENGAGEMENT" ], "type": "string" }, "name": { "maxLength": 255, "type": "string" }, "optimizationGoal": { "description": "Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`. TikTok: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400.", "type": "string" }, "platformPostId": { "description": "Platform post ID (alternative to postId). Reddit: the post id, with or without the `t3_` prefix. Meta: a Page post id (`_` or the bare post id) or an Instagram media id.", "type": "string" }, "platformSpecificData": { "description": "Platform-specific options. The platform is derived from `connectionId`; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today.", "oneOf": [ { "additionalProperties": false, "description": "LinkedIn-specific options for POST /apis/v1/ads/boost and POST /apis/v1/ads/create: campaign bidding and delivery controls, plus the LinkedIn-only creative formats on /apis/v1/ads/create. Unknown keys are rejected.", "properties": { "audienceExpansionEnabled": { "description": "Enable LinkedIn audience expansion. Defaults to false.", "type": "boolean" }, "carousel": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Carousel ad with 2-10 image cards. Mutually exclusive with the other creative sources.", "properties": { "cards": { "items": { "additionalProperties": false, "properties": { "headline": { "description": "Card title. Falls back to the ad-level headline.", "type": "string" }, "imageUrl": { "format": "uri", "type": "string" }, "landingUrl": { "description": "Per-card click destination. LinkedIn requires one on every card; the ad-level `linkUrl` backfills cards that omit it.", "format": "uri", "type": "string" } }, "required": [ "imageUrl" ], "type": "object" }, "maxItems": 10, "minItems": 2, "type": "array" } }, "required": [ "cards" ], "type": "object" }, "connectedTelevisionOnly": { "description": "Restrict delivery to Connected TV inventory.", "type": "boolean" }, "conversation": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Conversation Ad: a choose-your-path message tree delivered to the member's LinkedIn inbox. Messages are flat nodes wired by local ids. Each button either opens a url or leads to nextMessageId.", "properties": { "body": { "description": "Optional intro body (HTML allowed).", "type": "string" }, "firstMessageId": { "type": "string" }, "footer": { "description": "Terms shown at the bottom of the message.", "type": "string" }, "headline": { "description": "Conversation headline. Defaults to the first message's first line.", "type": "string" }, "messages": { "items": { "additionalProperties": false, "properties": { "buttons": { "items": { "additionalProperties": true, "type": "object" }, "maxItems": 5, "minItems": 1, "type": "array" }, "id": { "type": "string" }, "text": { "maxLength": 500, "type": "string" } }, "required": [ "id", "text" ], "type": "object" }, "maxItems": 25, "minItems": 1, "type": "array" }, "sender": { "description": "Person or organization URN. Defaults to the authoring Company Page. The sender must be approved for the ad account first (Campaign Manager > Manage message ad senders) or LinkedIn rejects the create with SINMAIL_SENDER_NOT_APPROVED.", "type": "string" }, "subject": { "description": "InMail subject shown in the inbox.", "type": "string" } }, "required": [ "firstMessageId", "messages", "subject" ], "type": "object" }, "costType": { "description": "Campaign cost model (billing event). Defaults to `CPM`. Required when `unitCost` is set so the manual bid applies to an explicit cost model.", "enum": [ "CPM", "CPC", "CPV" ], "type": "string" }, "creativeSelection": { "description": "How LinkedIn rotates creatives within the campaign. Defaults to `OPTIMIZED`.", "enum": [ "OPTIMIZED", "ROUND_ROBIN" ], "type": "string" }, "document": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Document ad rendered as an in-feed viewer. PDF, PPT or DOC up to 100MB. Mutually exclusive with the other creative sources.", "properties": { "title": { "description": "Document title.", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "title", "url" ], "type": "object" }, "event": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Promotes an existing LinkedIn Event; no headline needed. Mutually exclusive with the other creative sources.", "properties": { "urn": { "description": "LinkedIn Event URN, urn:li:event:N.", "pattern": "^urn:li:event:\\d+$", "type": "string" } }, "required": [ "urn" ], "type": "object" }, "follower": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Dynamic Follower Ad promoting the Company Page. Supported goals: engagement, awareness. headline and description take exactly one of preApproved or custom. Mutually exclusive with the other creative sources.", "properties": { "callToAction": { "enum": [ "VISIT_ORGANIZATION_COMPANY_PAGE", "VISIT_ORGANIZATION_LIFE_PAGE", "VISIT_ORGANIZATION_JOBS_PAGE", "VISIT_ORGANIZATION_CAREERS_PAGE" ], "type": "string" }, "description": { "additionalProperties": false, "properties": { "custom": { "description": "Free text, reviewed by LinkedIn.", "type": "string" }, "preApproved": { "description": "LinkedIn preset id, not reviewed. Example GET_LATEST_JOBS_AND_INDUSTRY_NEWS.", "type": "string" } }, "type": "object" }, "headline": { "additionalProperties": false, "properties": { "custom": { "description": "Free text, reviewed by LinkedIn.", "type": "string" }, "preApproved": { "description": "LinkedIn preset id, not reviewed. Example GROW_YOUR_BUSINESS_INSIGHTS.", "type": "string" } }, "type": "object" }, "logoUrl": { "format": "uri", "type": "string" }, "organizationName": { "type": "string" }, "showMemberProfilePhoto": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "callToAction", "description", "headline" ], "type": "object" }, "jobs": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Dynamic Jobs Ad promoting your open roles, personalized with the viewer's profile photo. Mutually exclusive with the other creative sources.", "properties": { "buttonLabel": { "additionalProperties": false, "properties": { "custom": { "description": "Free text, reviewed by LinkedIn.", "type": "string" }, "preApproved": { "description": "LinkedIn preset id, not reviewed. One of SEE_MORE_JOBS, VIEW_MORE, CAREERS_AT_COMPANY.", "type": "string" } }, "type": "object" }, "headline": { "additionalProperties": false, "properties": { "custom": { "description": "Free text, reviewed by LinkedIn.", "type": "string" }, "preApproved": { "description": "LinkedIn preset id, not reviewed. Example MEMBER_READY_FOR_YOUR_DREAM_JOB.", "type": "string" } }, "type": "object" }, "logoUrl": { "format": "uri", "type": "string" }, "organizationName": { "type": "string" }, "showMemberProfilePhoto": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "buttonLabel", "headline" ], "type": "object" }, "offsiteDeliveryEnabled": { "description": "Deliver on the LinkedIn Audience Network. Defaults to false.", "type": "boolean" }, "optimizationTargetType": { "description": "Campaign `optimizationTargetType` (e.g. `MAX_CLICK`, `TARGET_COST_PER_CLICK`, `MAX_IMPRESSION`). Forwarded verbatim; LinkedIn validates compatibility with the objective and `costType`. Default when omitted, derived from the objective:", "type": "string" }, "spotlight": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Dynamic Spotlight Ad personalized with the viewer's profile photo. Supported goals: traffic, awareness.", "properties": { "backgroundImageUrl": { "description": "Custom background. Replaces the description and the profile photo.", "format": "uri", "type": "string" }, "callToAction": { "description": "Button label text.", "type": "string" }, "description": { "description": "Mutually exclusive with backgroundImageUrl.", "type": "string" }, "headline": { "type": "string" }, "landingUrl": { "format": "uri", "type": "string" }, "logoUrl": { "format": "uri", "type": "string" }, "organizationName": { "type": "string" }, "showMemberProfilePhoto": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "callToAction", "headline", "landingUrl" ], "type": "object" }, "textAd": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Classic right-rail Text Ad. The copy lives here; ad-level body and headline are not used. Mutually exclusive with the other creative sources.", "properties": { "description": { "maxLength": 75, "type": "string" }, "headline": { "maxLength": 25, "type": "string" }, "imageUrl": { "description": "Optional 100x100 image.", "format": "uri", "type": "string" }, "landingUrl": { "format": "uri", "type": "string" } }, "required": [ "description", "headline", "landingUrl" ], "type": "object" }, "thoughtLeader": { "additionalProperties": false, "description": "POST /apis/v1/ads/create only. Sponsors an existing LinkedIn post (a share or ugcPost authored by your organization's Company Page) as the creative, keeping its commentary, author and engagement.", "properties": { "postUrn": { "description": "LinkedIn share or ugcPost URN: urn:li:share:N or urn:li:ugcPost:N. Get it via \"Copy link to post\" on the target LinkedIn post. The URL contains -share- (share) or -ugcPost- (ugcPost), then the numeric id.", "pattern": "^urn:li:(share|ugcPost):\\d+$", "type": "string" } }, "required": [ "postUrn" ], "type": "object" }, "unitCost": { "description": "Manual bid in WHOLE account-currency units (e.g. 2.5 = $2.50). Requires `costType`. Omit for LinkedIn's automated (max delivery) bidding. LinkedIn enforces its own per-audience min/max bid bounds.", "type": "number" } }, "type": "object" }, { "additionalProperties": false, "description": "Meta (facebook/instagram) options for platformSpecificData on POST /apis/v1/ads/boost and /apis/v1/ads/create. Unknown keys are rejected, not dropped.", "properties": { "adSchedule": { "description": "Dayparting on the ad set being created (Meta `adset_schedule` with `pacing_type: [\"day_parting\"]`). Change it later with `PUT /apis/v1/ads/ad-sets/{adSetId}`. A 400 with `param: platformSpecificData.adSchedule` when:", "items": { "additionalProperties": false, "properties": { "dayOfWeek": { "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "type": "string" }, "endHour": { "description": "Must be after startHour. 24 is midnight at the end of the day.", "maximum": 24, "minimum": 1, "type": "integer" }, "startHour": { "maximum": 23, "minimum": 0, "type": "integer" }, "timezoneType": { "default": "USER", "description": "Meta `timezone_type`: USER runs the hours in each viewer's time zone, ADVERTISER in the ad account time zone.", "enum": [ "USER", "ADVERTISER" ], "type": "string" } }, "required": [ "dayOfWeek", "endHour", "startHour" ], "type": "object" }, "maxItems": 168, "minItems": 1, "type": "array" }, "bidAmount": { "description": "Whole currency units (USD: 5 = $5.00). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.", "type": "number" }, "bidStrategy": { "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" }, "customerLifecycle": { "additionalProperties": false, "description": "Meta's Customer Lifecycle Strategy on a Sales ad set (Meta `ad_set_goal`). Rejected with 400 in adSetId attach mode: use PUT /apis/v1/ads/ad-sets/{adSetId} for an ad set that already exists.", "properties": { "engagedAudienceIds": { "description": "Custom audience ids of people who engaged but have not bought. Required with new_customers_excluding_engaged, not allowed with the other strategies. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "type": "array" }, "existingCustomerAudienceIds": { "description": "Custom audience ids that define your existing customers. Required with both new_customers strategies (Meta answers 400 subcode 1870251 without them); not allowed with all_customers. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "items": { "type": "string" }, "type": "array" }, "strategy": { "description": "`all_customers` is \"Maximize conversions from all customers\". `new_customers` is \"Acquire new customers\" (excludes existing customers). `new_customers_excluding_engaged` also excludes people who engaged with you but have not bought yet.", "enum": [ "all_customers", "new_customers", "new_customers_excluding_engaged" ], "type": "string" } }, "required": [ "strategy" ], "type": "object" }, "dailyMinSpendTarget": { "description": "Meta daily_min_spend_target on the ad set being created: the least it should spend per day, in whole currency units. A target, not a guarantee.", "type": "number" }, "lifetimeMinSpendTarget": { "description": "Meta lifetime_min_spend_target: the lifetime-budget flavour of dailyMinSpendTarget, in whole currency units. Same rules and same rejections.", "type": "number" }, "roasAverageFloor": { "description": "Decimal ROAS multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; sending it without bidStrategy is a 400.", "type": "number" } }, "type": "object" } ] }, "postId": { "type": "string" }, "promoCodes": { "description": "TikTok Smart+ Web Conversions only (requires `smartPlus: true`, goal `conversions`). Promo codes or offers TikTok highlights on the ad (Ads Manager's \"Add promo code or offer\"). A promo code needs shoppers to enter it at checkout.", "items": { "properties": { "discountCurrency": { "description": "ISO 4217; required for CASH.", "type": "string" }, "discountType": { "enum": [ "PERCENTAGE", "CASH" ], "type": "string" }, "discountValue": { "description": "PERCENTAGE: integer 1-100. CASH: amount greater than 0 in discountCurrency.", "type": "number" }, "minimumPurchaseCurrency": { "description": "ISO 4217; required for SUBTOTAL.", "type": "string" }, "minimumPurchaseType": { "enum": [ "QUANTITY", "SUBTOTAL" ], "type": "string" }, "minimumPurchaseValue": { "description": "Required with minimumPurchaseType; QUANTITY is an integer >= 0, SUBTOTAL an amount > 0.", "type": "number" }, "promoCode": { "description": "Code entered at checkout; omit for an automatic offer.", "maxLength": 30, "type": "string" } }, "required": [ "discountType", "discountValue" ], "type": "object" }, "maxItems": 10, "minItems": 1, "type": "array" }, "promotedObject": { "description": "Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic.", "properties": { "customConversionId": { "description": "Meta only. Custom Conversion to optimize against, instead of pixelId + customEventType.", "type": "string" }, "customEventStr": { "description": "Meta only. Pixel custom event name as it appears in Events Manager; requires customEventType OTHER.", "type": "string" }, "customEventType": { "description": "Meta: standard pixel event (PURCHASE, LEAD, ...) or OTHER with customEventStr. TikTok: optimization_event code (e.g.", "type": "string" }, "pixelId": { "description": "Meta Pixel id, TikTok Pixel (numeric id or the alphanumeric pixel code from Events Manager, resolved for you), or Reddit pixel id.", "type": "string" } }, "type": "object" }, "rawTargeting": { "additionalProperties": true, "description": "Meta only. A Meta-native targeting spec (e.g. `{ \"geo_locations\": { \"cities\": [{ \"key\": \"...\", \"radius\": 15, \"distance_unit\": \"kilometer\" }] } }`). Sent alone, it is forwarded unchanged.", "type": "object" }, "regionalRegulatedCategories": { "description": "Meta only. Regional regulation categories required when the ad set targets certain countries (e.g.", "items": { "type": "string" }, "type": "array" }, "regionalRegulationIdentities": { "additionalProperties": { "type": [ "string", "integer" ] }, "description": "Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set.", "type": "object" }, "rehostOnInstagramVideoRejection": { "default": true, "description": "Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279).", "type": "boolean" }, "roasAverageFloor": { "description": "Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.", "type": "number" }, "schedule": { "description": "Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400.", "properties": { "endDate": { "description": "Alias of endDate, kept for existing callers", "format": "date-time", "type": "string" }, "startDate": { "description": "Alias of startDate, kept for existing callers", "format": "date-time", "type": "string" } }, "type": "object" }, "smartPlus": { "description": "TikTok only. Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms. Requires:", "type": "boolean" }, "smartTargeting": { "description": "TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: `audience` is TikTok's `smart_audience_enabled`, `interestsBehaviors` its `smart_interest_behavior_enabled`.", "properties": { "audience": { "description": "TikTok smart_audience_enabled.", "type": "boolean" }, "interestsBehaviors": { "description": "TikTok smart_interest_behavior_enabled.", "type": "boolean" } }, "type": "object" }, "sparkAuthCode": { "description": "TikTok-only. Spark Code (the creator's `auth_code`) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Maps to `auth_code` on the creative entry of /v2/ad/create/.", "type": "string" }, "sparkPosts": { "description": "TikTok Smart+ only (requires `smartPlus: true`; a 400 on other platforms). Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`.", "items": { "properties": { "platformPostId": { "description": "TikTok post (item) id.", "type": "string" }, "sparkAuthCode": { "description": "That post's Spark code.", "type": "string" } }, "required": [ "platformPostId", "sparkAuthCode" ], "type": "object" }, "maxItems": 50, "minItems": 1, "type": "array" }, "specialAdCategories": { "description": "Meta only. Required for housing, employment, credit, or political ads.", "items": { "enum": [ "HOUSING", "EMPLOYMENT", "CREDIT", "FINANCIAL_PRODUCTS_SERVICES", "ISSUES_ELECTIONS_POLITICS", "ONLINE_GAMBLING_AND_GAMING" ], "type": "string" }, "type": "array" }, "specialAdCategoryCountry": { "description": "Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise).", "items": { "type": "string" }, "type": "array" }, "startDate": { "description": "Ad-set start time (ISO 8601, e.g. \"2026-06-10T09:00:00Z\"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately.", "format": "date-time", "type": "string" }, "status": { "description": "Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on:", "enum": [ "ACTIVE", "PAUSED" ], "type": "string" }, "targeting": { "description": "Same geo/demographic fields as the `TargetingSpec` used by /apis/v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /apis/v1/ads/targeting/search?dimension=geo. Meta only: city radius and lat/lng `customLocations`.", "properties": { "advantage_audience": { "description": "Meta only. 0 = disabled (default), 1 = enabled.", "enum": [ 0, 1 ], "type": "integer" }, "ageMax": { "maximum": 65, "minimum": 13, "type": "integer" }, "ageMin": { "maximum": 65, "minimum": 13, "type": "integer" }, "cities": { "description": "City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits (both set together, Meta only).", "items": { "properties": { "distanceUnit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "description": "Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng).", "type": "number" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "countries": { "description": "ISO country codes. Required for TikTok boosts (TikTok's ad group requires location_ids); optional on other platforms.", "items": { "type": "string" }, "type": "array" }, "customLocations": { "description": "Point-radius (lat/lng) targeting (Meta custom_locations). No geo `key` lookup needed.", "items": { "properties": { "address": { "description": "Optional label, sent to Meta as `address_string`.", "type": "string" }, "distanceUnit": { "enum": [ "mile", "kilometer" ], "type": "string" }, "latitude": { "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "maximum": 180, "minimum": -180, "type": "number" }, "name": { "type": "string" }, "radius": { "type": "number" } }, "required": [ "distanceUnit", "latitude", "longitude", "radius" ], "type": "object" }, "type": "array" }, "gender": { "description": "Applied on Meta, TikTok, Pinterest and Reddit. Ignored on Google, LinkedIn and X.", "enum": [ "all", "male", "female" ], "type": "string" }, "interests": { "description": "Interest objects from /apis/v1/ads/interests. Each must include id and name.", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "languages": { "description": "Meta locale ids (numeric), passed through as given. Reddit: language codes (e.g. `en`).", "items": { "type": "string" }, "type": "array" }, "metros": { "description": "DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`).", "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "regions": { "description": "Region/state targeting. `key` from /apis/v1/ads/targeting/search?dimension=geo&geoType=region.", "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "zips": { "description": "Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`).", "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" } }, "type": "object" }, "tracking": { "description": "Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags).", "properties": { "pixelId": { "type": "string" }, "urlTags": { "description": "URL parameters appended to the ad link, rendered as `key=value` pairs joined with `&`.", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "validateOnly": { "default": false, "description": "Meta only (facebook, instagram and Meta ads connections). Returns 200 with the same body as a validateOnly POST /apis/v1/ads/create (`validateOnly`, `results` per node, `message`).", "type": "boolean" }, "whatsappPhoneNumber": { "description": "Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad.", "pattern": "^\\+[1-9]\\d{6,14}$", "type": "string" }, "workflowId": { "description": "Meta messaging boosts only (callToAction MESSAGE_PAGE, WHATSAPP_MESSAGE or INSTAGRAM_MESSAGE). A workflow in the account's profile, started in the conversation a click on the ad opens. Stored on the ad.", "pattern": "^[a-fA-F0-9]{24}$", "type": "string" } }, "required": [ "adAccountId", "goal", "name" ], "type": "object" } } }, "required": true }, "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 POST /apis/v1/ads/boost 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/boost: post: summary: Boost post as ad description: >- Ad Campaigns. Can spend money or change spend: needs the ads:spend scope and X-Aisa-Confirm: spend; without the header the request is refused with confirmation_required and nothing is sent. Boosts a published post as an ad that spends the given budget. validateOnly=true checks the request without acting and needs no confirmation. Turns an already published post into a paid ad that keeps the post's likes and comments, creating the campaign around it. By default it provisions the whole hierarchy (campaign, ad set, ad). ### Attach shape (Meta) Send `adSetId` to put the ad under an EXISTING ad set instead, so that ad set keeps its learning phase. That ad set then owns `budget`, `schedule` and `targeting`. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: post_aisa_ads_apis_v1_ads_boost parameters: - 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: >- Required with the value "spend" when the request can spend money or change spend. Without it the request is refused with 409 confirmation_required, which describes what would happen; nothing is sent to the ad platform. in: header name: X-Aisa-Confirm required: false schema: enum: - spend type: string - description: >- Passed to the ad platform integration: a retry with the same key returns the first result instead of acting twice. AIsa never retries a write for you. in: header name: Idempotency-Key required: false schema: maxLength: 191 minLength: 1 type: string requestBody: content: application/json: example: adAccountId: act_757082720485182 budget: amount: 2.61 type: daily callToAction: WHATSAPP_MESSAGE connectionId: adc_7f3k2m9q goal: engagement name: WhatsApp post boost platformPostId: 811889972008357_123456789 status: PAUSED whatsappPhoneNumber: '+12025550123' schema: additionalProperties: true properties: adAccountId: description: Platform ad account ID type: string adSetId: description: >- Meta, or TikTok with `smartPlus: true`. Attach the boosted post to this existing ad set instead of creating a campaign. Meta: the ad set then owns budget, schedule and targeting; sending those too is a 400. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. type: string adSetName: description: >- Exact name for the ad-group level this boost provisions. Omitted keeps the default ` - Ad Group`. Meta: ad set; TikTok, Pinterest, Google: ad group; X: line item; LinkedIn: the campaign under the campaign group. maxLength: 255 type: string adSetStatus: description: >- Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new ad set alone and overrides `status` for it. Omitted, it follows `status`. enum: - ACTIVE - PAUSED type: string adStatus: description: >- Request-side publish switch for `adStatus` on ad creation endpoints only (`status`, `campaignStatus` and `adSetStatus` carry their own inline ACTIVE/PAUSED enum there; the status-update endpoints are a separate lowercase `active`/`paused`… enum: - ACTIVE - PAUSED type: string attributionSpec: description: >- Meta only. Ad-set attribution windows, same shape as POST /apis/v1/ads/create. items: properties: eventType: enum: - CLICK_THROUGH - VIEW_THROUGH - ENGAGED_VIDEO_VIEW type: string windowDays: enum: - 1 - 7 - 28 type: integer required: - eventType - windowDays type: object maxItems: 3 minItems: 1 type: array bidAmount: description: >- Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. type: number bidStrategy: description: >- Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string bodies: description: >- Meta only. Extra primary-text options Meta rotates on the boosted post (asset_feed_spec.bodies with DEGREES_OF_FREEDOM). The post keeps its own text as one of the options. Works for Facebook posts and Instagram media. items: type: string maxItems: 5 minItems: 1 type: array budget: description: >- Alias of budgetAmount + budgetType, kept for existing callers properties: amount: description: 'Minimum varies: TikTok=$20, Pinterest=$5, others=$1' type: number type: enum: - daily - lifetime type: string required: - amount - type type: object budgetAmount: description: >- Budget in whole currency units, the same flat field as POST /apis/v1/ads/create. Required unless adSetId is set. Minimum varies: TikTok=$20, Pinterest=$5, others=$1 type: number budgetLevel: description: >- Meta only, same semantics as POST /apis/v1/ads/create: campaign = Advantage campaign budget (CBO), the budget and bid strategy sit on the campaign and the ad set inherits them. Default adset. Not allowed with adSetId. enum: - adset - campaign type: string budgetType: description: >- Goes together with budgetAmount. lifetime requires schedule.endDate. enum: - daily - lifetime type: string callToAction: description: >- CTA button label. Non-messaging CTAs require `linkUrl`. WHATSAPP_MESSAGE, MESSAGE_PAGE, and INSTAGRAM_MESSAGE do not require a URL and reject linkUrl. type: string campaignName: description: >- Exact name for the campaign this boost provisions. Omitted keeps the default ` - Campaign`. Every platform: on LinkedIn it names the campaign group. Ignored on the Meta attach shape (`adSetId`), which creates no campaign. maxLength: 255 type: string campaignStatus: description: >- Every platform, same semantics as POST /apis/v1/ads/create. Sets the switch of the new campaign alone (LinkedIn: the campaign group) and overrides `status` for it. When omitted, it follows `status`. enum: - ACTIVE - PAUSED type: string connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string 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 currency: description: >- ISO 4217 currency code matching the ad account's currency. Meta only. maxLength: 3 minLength: 3 type: string destinationType: description: >- Meta only. Ad-set destination_type: where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Independent of plain link CTAs and their goal. enum: - INSTAGRAM_PROFILE - WEBSITE - ON_AD - MESSENGER - WHATSAPP - INSTAGRAM_DIRECT type: string dsaBeneficiary: description: >- Legal entity that benefits from the ad. Required when targeting EU users (EU DSA, Article 26). maxLength: 100 type: string dsaPayor: description: >- Legal entity that pays for the ad. Can differ from `dsaBeneficiary` (for example, an agency paying for a client's ads). Same rules as `dsaBeneficiary`: required for EU targeting unless the ad account has a default payor. maxLength: 100 type: string endDate: description: >- Ad-set end time (ISO 8601). Required for lifetime budgets. Same field as on POST /apis/v1/ads/create. Maps to the ad set's `end_time` (on X, the line item's `end_time`; X campaigns carry no flight dates). format: date-time type: string existingCampaignId: description: >- TikTok only. Create the ad group and the Spark ad under this existing TikTok campaign instead of creating a new campaign. The campaign keeps its own status and objective (the objective must fit `goal`). Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. type: string goal: description: >- Available goals vary by platform. Meta (Facebook/Instagram) and TikTok support all 7. LinkedIn supports all except app_promotion. X supports engagement, traffic, awareness, video_views, app_promotion. enum: - engagement - traffic - awareness - video_views - lead_generation - conversions - app_promotion type: string identityId: description: >- TikTok only. The identity the ad runs as (the profile shown on the ad), from GET /apis/v1/ads/tiktok-identities. Default: the connected TikTok account's own identity. type: string identityType: description: >- TikTok only. Type of identityId; resolved from the advertiser's identity list when omitted. enum: - TT_USER - CUSTOMIZED_USER - BC_AUTH_TT type: string instagramAccountId: description: >- Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative. type: string leadGenFormId: description: >- Lead Gen form ID to attach to the boosted ad's creative. REQUIRED when `goal` is `lead_generation`; ignored for other goals. Meta: the leadgen_forms ID (create one via POST /apis/v1/ads/lead-forms). type: string lifetimeBudgetCap: description: >- X only (400 on another platform or on a lifetime budget). A lifetime total, in whole currency units, that caps a daily budget (budgetType daily). Must be at least budgetAmount. exclusiveMinimum: 0 type: number linkUrl: description: >- Website URL for non-messaging CTA buttons. Send it with `callToAction`. Omit for messaging boosts. Meta: adds a top-level `call_to_action` to the post-reference creative. format: uri type: string locationTargetingType: description: >- Google only (400 elsewhere). Written on the campaign the boost creates. enum: - presence - presence_or_interest type: string metaObjective: description: >- Meta only, with `goal: engagement` and without `adSetId` (400 otherwise). enum: - OUTCOME_ENGAGEMENT type: string name: maxLength: 255 type: string optimizationGoal: description: >- Ad-set optimization goal override. Meta, or TikTok with `goal: video_views`. TikTok: ENGAGED_VIEW (6-second Focused View, the default) or ENGAGED_VIEW_FIFTEEN (15-second views), both billed per view (CPV). Any other value is a 400. type: string platformPostId: description: >- Platform post ID (alternative to postId). Reddit: the post id, with or without the `t3_` prefix. Meta: a Page post id (`_` or the bare post id) or an Instagram media id. type: string platformSpecificData: description: >- Platform-specific options. The platform is derived from `connectionId`; sending options for a different platform returns a 400. LinkedIn (campaign bidding and delivery controls) and Meta (the bid trio) have options today. oneOf: - additionalProperties: false description: >- LinkedIn-specific options for POST /apis/v1/ads/boost and POST /apis/v1/ads/create: campaign bidding and delivery controls, plus the LinkedIn-only creative formats on /apis/v1/ads/create. Unknown keys are rejected. properties: audienceExpansionEnabled: description: >- Enable LinkedIn audience expansion. Defaults to false. type: boolean carousel: additionalProperties: false description: >- POST /apis/v1/ads/create only. Carousel ad with 2-10 image cards. Mutually exclusive with the other creative sources. properties: cards: items: additionalProperties: false properties: headline: description: >- Card title. Falls back to the ad-level headline. type: string imageUrl: format: uri type: string landingUrl: description: >- Per-card click destination. LinkedIn requires one on every card; the ad-level `linkUrl` backfills cards that omit it. format: uri type: string required: - imageUrl type: object maxItems: 10 minItems: 2 type: array required: - cards type: object connectedTelevisionOnly: description: Restrict delivery to Connected TV inventory. type: boolean conversation: additionalProperties: false description: >- POST /apis/v1/ads/create only. Conversation Ad: a choose-your-path message tree delivered to the member's LinkedIn inbox. Messages are flat nodes wired by local ids. Each button either opens a url or leads to nextMessageId. properties: body: description: Optional intro body (HTML allowed). type: string firstMessageId: type: string footer: description: Terms shown at the bottom of the message. type: string headline: description: >- Conversation headline. Defaults to the first message's first line. type: string messages: items: additionalProperties: false properties: buttons: items: additionalProperties: true type: object maxItems: 5 minItems: 1 type: array id: type: string text: maxLength: 500 type: string required: - id - text type: object maxItems: 25 minItems: 1 type: array sender: description: >- Person or organization URN. Defaults to the authoring Company Page. The sender must be approved for the ad account first (Campaign Manager > Manage message ad senders) or LinkedIn rejects the create with SINMAIL_SENDER_NOT_APPROVED. type: string subject: description: InMail subject shown in the inbox. type: string required: - firstMessageId - messages - subject type: object costType: description: >- Campaign cost model (billing event). Defaults to `CPM`. Required when `unitCost` is set so the manual bid applies to an explicit cost model. enum: - CPM - CPC - CPV type: string creativeSelection: description: >- How LinkedIn rotates creatives within the campaign. Defaults to `OPTIMIZED`. enum: - OPTIMIZED - ROUND_ROBIN type: string document: additionalProperties: false description: >- POST /apis/v1/ads/create only. Document ad rendered as an in-feed viewer. PDF, PPT or DOC up to 100MB. Mutually exclusive with the other creative sources. properties: title: description: Document title. type: string url: format: uri type: string required: - title - url type: object event: additionalProperties: false description: >- POST /apis/v1/ads/create only. Promotes an existing LinkedIn Event; no headline needed. Mutually exclusive with the other creative sources. properties: urn: description: LinkedIn Event URN, urn:li:event:N. pattern: ^urn:li:event:\d+$ type: string required: - urn type: object follower: additionalProperties: false description: >- POST /apis/v1/ads/create only. Dynamic Follower Ad promoting the Company Page. Supported goals: engagement, awareness. headline and description take exactly one of preApproved or custom. Mutually exclusive with the other creative sources. properties: callToAction: enum: - VISIT_ORGANIZATION_COMPANY_PAGE - VISIT_ORGANIZATION_LIFE_PAGE - VISIT_ORGANIZATION_JOBS_PAGE - VISIT_ORGANIZATION_CAREERS_PAGE type: string description: additionalProperties: false properties: custom: description: Free text, reviewed by LinkedIn. type: string preApproved: description: >- LinkedIn preset id, not reviewed. Example GET_LATEST_JOBS_AND_INDUSTRY_NEWS. type: string type: object headline: additionalProperties: false properties: custom: description: Free text, reviewed by LinkedIn. type: string preApproved: description: >- LinkedIn preset id, not reviewed. Example GROW_YOUR_BUSINESS_INSIGHTS. type: string type: object logoUrl: format: uri type: string organizationName: type: string showMemberProfilePhoto: description: Defaults to true. type: boolean required: - callToAction - description - headline type: object jobs: additionalProperties: false description: >- POST /apis/v1/ads/create only. Dynamic Jobs Ad promoting your open roles, personalized with the viewer's profile photo. Mutually exclusive with the other creative sources. properties: buttonLabel: additionalProperties: false properties: custom: description: Free text, reviewed by LinkedIn. type: string preApproved: description: >- LinkedIn preset id, not reviewed. One of SEE_MORE_JOBS, VIEW_MORE, CAREERS_AT_COMPANY. type: string type: object headline: additionalProperties: false properties: custom: description: Free text, reviewed by LinkedIn. type: string preApproved: description: >- LinkedIn preset id, not reviewed. Example MEMBER_READY_FOR_YOUR_DREAM_JOB. type: string type: object logoUrl: format: uri type: string organizationName: type: string showMemberProfilePhoto: description: Defaults to true. type: boolean required: - buttonLabel - headline type: object offsiteDeliveryEnabled: description: >- Deliver on the LinkedIn Audience Network. Defaults to false. type: boolean optimizationTargetType: description: >- Campaign `optimizationTargetType` (e.g. `MAX_CLICK`, `TARGET_COST_PER_CLICK`, `MAX_IMPRESSION`). Forwarded verbatim; LinkedIn validates compatibility with the objective and `costType`. Default when omitted, derived from the objective: type: string spotlight: additionalProperties: false description: >- POST /apis/v1/ads/create only. Dynamic Spotlight Ad personalized with the viewer's profile photo. Supported goals: traffic, awareness. properties: backgroundImageUrl: description: >- Custom background. Replaces the description and the profile photo. format: uri type: string callToAction: description: Button label text. type: string description: description: Mutually exclusive with backgroundImageUrl. type: string headline: type: string landingUrl: format: uri type: string logoUrl: format: uri type: string organizationName: type: string showMemberProfilePhoto: description: Defaults to true. type: boolean required: - callToAction - headline - landingUrl type: object textAd: additionalProperties: false description: >- POST /apis/v1/ads/create only. Classic right-rail Text Ad. The copy lives here; ad-level body and headline are not used. Mutually exclusive with the other creative sources. properties: description: maxLength: 75 type: string headline: maxLength: 25 type: string imageUrl: description: Optional 100x100 image. format: uri type: string landingUrl: format: uri type: string required: - description - headline - landingUrl type: object thoughtLeader: additionalProperties: false description: >- POST /apis/v1/ads/create only. Sponsors an existing LinkedIn post (a share or ugcPost authored by your organization's Company Page) as the creative, keeping its commentary, author and engagement. properties: postUrn: description: >- LinkedIn share or ugcPost URN: urn:li:share:N or urn:li:ugcPost:N. Get it via "Copy link to post" on the target LinkedIn post. The URL contains -share- (share) or -ugcPost- (ugcPost), then the numeric id. pattern: ^urn:li:(share|ugcPost):\d+$ type: string required: - postUrn type: object unitCost: description: >- Manual bid in WHOLE account-currency units (e.g. 2.5 = $2.50). Requires `costType`. Omit for LinkedIn's automated (max delivery) bidding. LinkedIn enforces its own per-audience min/max bid bounds. type: number type: object - additionalProperties: false description: >- Meta (facebook/instagram) options for platformSpecificData on POST /apis/v1/ads/boost and /apis/v1/ads/create. Unknown keys are rejected, not dropped. properties: adSchedule: description: >- Dayparting on the ad set being created (Meta `adset_schedule` with `pacing_type: ["day_parting"]`). Change it later with `PUT /apis/v1/ads/ad-sets/{adSetId}`. A 400 with `param: platformSpecificData.adSchedule` when: items: additionalProperties: false properties: dayOfWeek: enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY type: string endHour: description: >- Must be after startHour. 24 is midnight at the end of the day. maximum: 24 minimum: 1 type: integer startHour: maximum: 23 minimum: 0 type: integer timezoneType: default: USER description: >- Meta `timezone_type`: USER runs the hours in each viewer's time zone, ADVERTISER in the ad account time zone. enum: - USER - ADVERTISER type: string required: - dayOfWeek - endHour - startHour type: object maxItems: 168 minItems: 1 type: array bidAmount: description: >- Whole currency units (USD: 5 = $5.00). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. type: number bidStrategy: 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 customerLifecycle: additionalProperties: false description: >- Meta's Customer Lifecycle Strategy on a Sales ad set (Meta `ad_set_goal`). Rejected with 400 in adSetId attach mode: use PUT /apis/v1/ads/ad-sets/{adSetId} for an ad set that already exists. properties: engagedAudienceIds: description: >- Custom audience ids of people who engaged but have not bought. Required with new_customers_excluding_engaged, not allowed with the other strategies. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string type: array existingCustomerAudienceIds: description: >- Custom audience ids that define your existing customers. Required with both new_customers strategies (Meta answers 400 subcode 1870251 without them); not allowed with all_customers. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. items: type: string type: array strategy: description: >- `all_customers` is "Maximize conversions from all customers". `new_customers` is "Acquire new customers" (excludes existing customers). `new_customers_excluding_engaged` also excludes people who engaged with you but have not bought yet. enum: - all_customers - new_customers - new_customers_excluding_engaged type: string required: - strategy type: object dailyMinSpendTarget: description: >- Meta daily_min_spend_target on the ad set being created: the least it should spend per day, in whole currency units. A target, not a guarantee. type: number lifetimeMinSpendTarget: description: >- Meta lifetime_min_spend_target: the lifetime-budget flavour of dailyMinSpendTarget, in whole currency units. Same rules and same rejections. type: number roasAverageFloor: description: >- Decimal ROAS multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS; sending it without bidStrategy is a 400. type: number type: object postId: type: string promoCodes: description: >- TikTok Smart+ Web Conversions only (requires `smartPlus: true`, goal `conversions`). Promo codes or offers TikTok highlights on the ad (Ads Manager's "Add promo code or offer"). A promo code needs shoppers to enter it at checkout. items: properties: discountCurrency: description: ISO 4217; required for CASH. type: string discountType: enum: - PERCENTAGE - CASH type: string discountValue: description: >- PERCENTAGE: integer 1-100. CASH: amount greater than 0 in discountCurrency. type: number minimumPurchaseCurrency: description: ISO 4217; required for SUBTOTAL. type: string minimumPurchaseType: enum: - QUANTITY - SUBTOTAL type: string minimumPurchaseValue: description: >- Required with minimumPurchaseType; QUANTITY is an integer >= 0, SUBTOTAL an amount > 0. type: number promoCode: description: Code entered at checkout; omit for an automatic offer. maxLength: 30 type: string required: - discountType - discountValue type: object maxItems: 10 minItems: 1 type: array promotedObject: description: >- Meta, TikTok and Reddit. What the conversion ad set optimizes toward, so a boost of an existing organic post can run for a conversion instead of only engagement or traffic. properties: customConversionId: description: >- Meta only. Custom Conversion to optimize against, instead of pixelId + customEventType. type: string customEventStr: description: >- Meta only. Pixel custom event name as it appears in Events Manager; requires customEventType OTHER. type: string customEventType: description: >- Meta: standard pixel event (PURCHASE, LEAD, ...) or OTHER with customEventStr. TikTok: optimization_event code (e.g. type: string pixelId: description: >- Meta Pixel id, TikTok Pixel (numeric id or the alphanumeric pixel code from Events Manager, resolved for you), or Reddit pixel id. type: string type: object rawTargeting: additionalProperties: true description: >- Meta only. A Meta-native targeting spec (e.g. `{ "geo_locations": { "cities": [{ "key": "...", "radius": 15, "distance_unit": "kilometer" }] } }`). Sent alone, it is forwarded unchanged. type: object regionalRegulatedCategories: description: >- Meta only. Regional regulation categories required when the ad set targets certain countries (e.g. items: type: string type: array regionalRegulationIdentities: additionalProperties: type: - string - integer description: >- Meta only. Verified identity IDs of the beneficiary and payer for each declared regionalRegulatedCategories value. Ignored when adSetId adds the ad to an existing ad set. type: object rehostOnInstagramVideoRejection: default: true description: >- Meta only (a 400 elsewhere). Controls the fallback when Meta refuses an existing Instagram video as the ad (subcode 1815279). type: boolean roasAverageFloor: description: >- Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400. type: number schedule: description: >- Alias of the top-level `startDate` / `endDate`, kept for existing callers. Sending both forms with differing values is a 400. properties: endDate: description: Alias of endDate, kept for existing callers format: date-time type: string startDate: description: Alias of startDate, kept for existing callers format: date-time type: string type: object smartPlus: description: >- TikTok only. Run the Spark post in a Smart+ campaign instead of a regular one: goal `conversions` = Smart+ Web Conversions, `lead_generation` = Smart+ Lead Generation. Rejected with a 400 on other platforms. Requires: type: boolean smartTargeting: description: >- TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: `audience` is TikTok's `smart_audience_enabled`, `interestsBehaviors` its `smart_interest_behavior_enabled`. properties: audience: description: TikTok smart_audience_enabled. type: boolean interestsBehaviors: description: TikTok smart_interest_behavior_enabled. type: boolean type: object sparkAuthCode: description: >- TikTok-only. Spark Code (the creator's `auth_code`) authorizing cross-creator Spark Ads: the advertiser can boost a video owned by a DIFFERENT TikTok account. Maps to `auth_code` on the creative entry of /v2/ad/create/. type: string sparkPosts: description: >- TikTok Smart+ only (requires `smartPlus: true`; a 400 on other platforms). Several Spark posts as creatives of ONE Smart+ ad, each with its own post code. Replaces `platformPostId` + `sparkAuthCode`. items: properties: platformPostId: description: TikTok post (item) id. type: string sparkAuthCode: description: That post's Spark code. type: string required: - platformPostId - sparkAuthCode type: object maxItems: 50 minItems: 1 type: array specialAdCategories: description: >- Meta only. Required for housing, employment, credit, or political ads. items: enum: - HOUSING - EMPLOYMENT - CREDIT - FINANCIAL_PRODUCTS_SERVICES - ISSUES_ELECTIONS_POLITICS - ONLINE_GAMBLING_AND_GAMING type: string type: array specialAdCategoryCountry: description: >- Meta (metaads) only. 2-letter ISO country codes the special ad category applies to. Requires specialAdCategories to be set (400 otherwise). items: type: string type: array startDate: description: >- Ad-set start time (ISO 8601, e.g. "2026-06-10T09:00:00Z"), mapped to the ad set's `start_time`. When omitted the ad starts delivering immediately. format: date-time type: string status: description: >- Publish state of the created entities, on every platform. Omitted or ACTIVE publishes live (default). PAUSED pauses only the top-most object this boost creates and switches everything below it on: enum: - ACTIVE - PAUSED type: string targeting: description: >- Same geo/demographic fields as the `TargetingSpec` used by /apis/v1/ads/create. Geo keys (`regions`/`cities`/`zips`/`metros`) resolve via GET /apis/v1/ads/targeting/search?dimension=geo. Meta only: city radius and lat/lng `customLocations`. properties: advantage_audience: description: Meta only. 0 = disabled (default), 1 = enabled. enum: - 0 - 1 type: integer ageMax: maximum: 65 minimum: 13 type: integer ageMin: maximum: 65 minimum: 13 type: integer cities: description: >- City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits (both set together, Meta only). items: properties: distanceUnit: enum: - mile - kilometer type: string key: type: string name: type: string radius: description: >- Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng). type: number required: - key type: object type: array countries: description: >- ISO country codes. Required for TikTok boosts (TikTok's ad group requires location_ids); optional on other platforms. items: type: string type: array customLocations: description: >- Point-radius (lat/lng) targeting (Meta custom_locations). No geo `key` lookup needed. items: properties: address: description: Optional label, sent to Meta as `address_string`. type: string distanceUnit: enum: - mile - kilometer type: string latitude: maximum: 90 minimum: -90 type: number longitude: maximum: 180 minimum: -180 type: number name: type: string radius: type: number required: - distanceUnit - latitude - longitude - radius type: object type: array gender: description: >- Applied on Meta, TikTok, Pinterest and Reddit. Ignored on Google, LinkedIn and X. enum: - all - male - female type: string interests: description: >- Interest objects from /apis/v1/ads/interests. Each must include id and name. items: properties: id: type: string name: type: string required: - id - name type: object type: array languages: description: >- Meta locale ids (numeric), passed through as given. Reddit: language codes (e.g. `en`). items: type: string type: array metros: description: >- DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`). items: properties: key: type: string name: type: string required: - key type: object type: array regions: description: >- Region/state targeting. `key` from /apis/v1/ads/targeting/search?dimension=geo&geoType=region. items: properties: key: type: string name: type: string required: - key type: object type: array zips: description: >- Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). items: properties: key: type: string name: type: string required: - key type: object type: array type: object tracking: description: >- Meta only, except `pixelId`, which also picks the Reddit pixel of the new ad group (`promotedObject.pixelId` wins when both are sent). Tracking specs (pixel, URL tags). properties: pixelId: type: string urlTags: description: >- URL parameters appended to the ad link, rendered as `key=value` pairs joined with `&`. items: properties: key: type: string value: type: string type: object type: array type: object validateOnly: default: false description: >- Meta only (facebook, instagram and Meta ads connections). Returns 200 with the same body as a validateOnly POST /apis/v1/ads/create (`validateOnly`, `results` per node, `message`). type: boolean whatsappPhoneNumber: description: >- Meta WhatsApp only. E.164 number already paired with the Page. Omit to use the default pairing. Requires WHATSAPP_MESSAGE callToAction. Stored as creative.whatsappPhoneNumber on the ad. pattern: ^\+[1-9]\d{6,14}$ type: string workflowId: description: >- Meta messaging boosts only (callToAction MESSAGE_PAGE, WHATSAPP_MESSAGE or INSTAGRAM_MESSAGE). A workflow in the account's profile, started in the conversation a click on the ad opens. Stored on the ad. pattern: ^[a-fA-F0-9]{24}$ type: string required: - adAccountId - goal - name type: object required: true responses: '200': content: application/json: schema: properties: message: type: string results: items: properties: node: enum: - campaign - adSet - creative - ad type: string reason: description: >- Why the node was skipped (it already exists with adSetId), why Meta could not dry-run it (on unverified), or what the dry run could not check (on validated). type: string status: enum: - validated - skipped - unverified type: string type: object type: array validateOnly: description: Always true in a validate-only response. type: boolean type: object description: validateOnly dry-run passed (Meta), nothing was created '201': 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 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: description: Meta's original refusal. properties: code: type: integer fbtraceId: type: string message: type: string subcode: type: integer required: - message 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 message: type: string warnings: description: >- Human-readable notes about the boost. With instagramVideoFallback: one line saying how the Instagram video was boosted. `activation_failed:` (Meta): Meta refused the final switch to ACTIVE of the campaign, ad set or ad this boost created. items: type: string type: array type: object description: Ad created 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.