> ## 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 # Update 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. Changes an ad's budget, targeting or status. Changes an ad's status, budget, targeting or creative and applies the change on the platform. Patch one or more fields on an ad. Status, budget, targeting, and creative changes are propagated to the platform. ### Per-platform support Meta (Facebook + Instagram): all fields supported. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. ## Request contract * **Method and path:** PUT /apis/v1/ads/\{adId} * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/ads/{adId}` * **adId:** path; required * **connectionId:** query; required * **X-Aisa-Confirm:** header; optional * **Runtime facts:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-ads.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "put_aisa_ads_apis_v1_ads_adid", "method": "PUT", "path": "/apis/v1/ads/{adId}", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "in": "path", "name": "adId", "required": true, "schema": { "type": "string" } }, { "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.", "in": "query", "name": "connectionId", "required": true, "schema": { "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" } }, { "description": "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" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "example": { "connectionId": "adc_7f3k2m9q", "descriptions": [ { "pinnedField": "DESCRIPTION_1", "text": "Connect social accounts and schedule posts with the AIsa API." }, { "text": "Build social publishing into your application." } ], "finalUrls": [ "https://example.com/landing" ], "headlines": [ { "pinnedField": "HEADLINE_1", "text": "Social Media API" }, { "text": "Schedule Your Posts" }, { "text": "Build With AIsa" } ] }, "schema": { "additionalProperties": true, "properties": { "assetGroup": { "additionalProperties": false, "description": "Google Performance Max only. Replaces whole asset roles on the ad's asset group. Returns 422 on any other platform or channel.", "properties": { "businessName": { "description": "Replaces the BUSINESS_NAME asset.", "maxLength": 25, "minLength": 1, "type": "string" }, "descriptions": { "description": "Replaces every DESCRIPTION asset. At least one must be 60 characters or fewer.", "items": { "maxLength": 90, "minLength": 1, "type": "string" }, "maxItems": 5, "minItems": 2, "type": "array", "uniqueItems": true }, "finalUrl": { "description": "Replaces the asset group's final URL.", "format": "uri", "pattern": "^https?://", "type": "string" }, "headlines": { "description": "Replaces every HEADLINE asset on the group.", "items": { "maxLength": 30, "minLength": 1, "type": "string" }, "maxItems": 15, "minItems": 3, "type": "array", "uniqueItems": true }, "images": { "additionalProperties": false, "description": "Public HTTP(S) image URLs. Each role you send replaces that role's images; roles you omit stay. GIF, JPEG or PNG, at most 5120 KB per image.", "properties": { "landscape": { "description": "Replaces MARKETING_IMAGE assets. Aspect ratio 1.91:1, minimum 600 x 314 pixels.", "items": { "format": "uri", "pattern": "^https?://", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "logo": { "description": "Replaces LOGO assets. Aspect ratio 1:1, minimum 128 x 128 pixels.", "items": { "format": "uri", "pattern": "^https?://", "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "square": { "description": "Replaces SQUARE_MARKETING_IMAGE assets. Aspect ratio 1:1, minimum 300 x 300 pixels.", "items": { "format": "uri", "pattern": "^https?://", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" } }, "type": "object" }, "longHeadline": { "description": "Replaces the LONG_HEADLINE asset.", "maxLength": 90, "minLength": 1, "type": "string" }, "youtubeVideoIds": { "description": "Replaces YOUTUBE_VIDEO assets with existing YouTube video ids. Video uploads and arbitrary video URLs are not supported.", "items": { "pattern": "^[A-Za-z0-9_-]{11}$", "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" } }, "type": "object" }, "budget": { "properties": { "amount": { "description": "Minimum varies by platform: TikTok=$20, Pinterest=$5, others=$1", "type": "number" }, "type": { "description": "OpenAI Ads accepts both and sets the campaign's single spend cap, replacing the previous daily or lifetime cap. A daily cap cannot go back to lifetime (422).", "enum": [ "daily", "lifetime" ], "type": "string" } }, "type": "object" }, "connectionId": { "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.", "pattern": "^adc_[0-9A-Za-z]+$", "type": "string" }, "creative": { "description": "Replace or patch the ad's creative. Meta, TikTok, and LinkedIn. Meta: patch-style. Pass any subset: omitted fields are preserved from the live creative, including media (`image_hash`/`video_id` reused, no re-upload) and `url_tags`.", "properties": { "body": { "type": "string" }, "businessName": { "description": "Google Display only. Replaces the responsive display ad's business name.", "maxLength": 25, "minLength": 1, "type": "string" }, "callToAction": { "type": "string" }, "catalogFormat": { "description": "Meta catalog template ads only. Rebuilds the creative with this `template_data.format_option` (same mapping as on create) and repoints the ad at the new creative.", "enum": [ "single_image", "carousel_images_multi_items", "carousel_images_single_item", "carousel_slideshows" ], "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" }, "description": { "description": "Link description slot (Meta `link_data.description` / `video_data.link_description`, LinkedIn creative description).", "maxLength": 255, "type": "string" }, "existingCreativeId": { "description": "Meta only. Repoint the ad at an existing library creative (from GET /apis/v1/ads/creatives); all other creative fields are ignored.", "type": "string" }, "headline": { "description": "Meta and LinkedIn (TikTok has no headline slot)", "type": "string" }, "imageUrl": { "format": "uri", "type": "string" }, "linkUrl": { "format": "uri", "type": "string" }, "longHeadline": { "description": "Google Display only. Replaces the responsive display ad's long headline.", "maxLength": 90, "minLength": 1, "type": "string" }, "promotion": { "description": "Not supported. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Any object is rejected with 400 invalid_field_value.", "type": [ "object", "null" ] }, "squareImageUrl": { "description": "Google Display only. Uploaded as a new square (1:1) marketing image asset that replaces the current one.", "format": "uri", "type": "string" }, "videoId": { "description": "Meta only. Reuse an already-uploaded ad video (from POST /apis/v1/ads/videos or GET /apis/v1/ads/videos) instead of re-uploading via videoUrl.", "type": "string" }, "videoUrl": { "format": "uri", "type": "string" } }, "type": "object" }, "demandGen": { "additionalProperties": false, "description": "Google Demand Gen only. Returns 422 on any other platform or channel.", "properties": { "audience": { "additionalProperties": false, "description": "Created as a Google Audience and attached to the ad group. Send at least one dimension. Ids are numeric Google ids (user lists, interest categories, custom audiences) from the same customer.", "properties": { "ageRanges": { "items": { "properties": { "max": { "description": "Omit for no upper bound.", "enum": [ 24, 34, 44, 54, 64 ], "type": "integer" }, "min": { "enum": [ 18, 25, 35, 45, 55, 65 ], "type": "integer" } }, "required": [ "min" ], "type": "object" }, "maxItems": 6, "minItems": 1, "type": "array" }, "customAudiences": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "genders": { "items": { "enum": [ "male", "female", "undetermined" ], "type": "string" }, "maxItems": 3, "minItems": 1, "type": "array" }, "userInterests": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "userLists": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" } }, "type": "object" }, "audienceId": { "description": "Attach an existing Google Audience by numeric id instead of audience. 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" }, "businessName": { "maxLength": 25, "type": "string" }, "callToAction": { "description": "Image and carousel ads only.", "maxLength": 25, "type": "string" }, "channels": { "description": "Replaces the ad group's channel controls. Only the listed channels serve; Google Maps, which this list cannot select, is turned off. Omit to leave the ad group's channel controls unchanged.", "items": { "enum": [ "youtube_in_stream", "youtube_in_feed", "youtube_shorts", "discover", "gmail", "display" ], "type": "string" }, "minItems": 1, "type": "array" }, "descriptions": { "items": { "maxLength": 90, "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "finalUrl": { "format": "uri", "type": "string" }, "headlines": { "items": { "maxLength": 40, "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "images": { "additionalProperties": false, "properties": { "landscape": { "items": { "format": "uri", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "logo": { "items": { "format": "uri", "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "portrait": { "items": { "format": "uri", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" }, "square": { "items": { "format": "uri", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" } }, "type": "object" }, "longHeadlines": { "description": "Video ads only.", "items": { "maxLength": 90, "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "youtubeVideoIds": { "description": "Video ads only.", "items": { "pattern": "^[A-Za-z0-9_-]{11}$", "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" } }, "type": "object" }, "descriptions": { "description": "Google Search and Display only. Replaces the complete description list. Search takes 2-4, Display 1-5 and rejects pinnedField. No padding or truncation on update.", "items": { "properties": { "pinnedField": { "description": "Optional fixed description position. Omit to leave the asset unpinned.", "enum": [ "DESCRIPTION_1", "DESCRIPTION_2" ], "type": "string" }, "text": { "maxLength": 90, "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "maxItems": 5, "minItems": 1, "type": "array" }, "finalUrls": { "description": "Google Search and Display only. Replaces final URLs. Omitted lists stay unchanged. For Performance Max use assetGroup.finalUrl.", "items": { "format": "uri", "type": "string" }, "minItems": 1, "type": "array" }, "headlines": { "description": "Google Search and Display only. Replaces the complete headline list. Search takes 3-15, Display 1-5 and rejects pinnedField; the count is checked once the ad's channel is known. No padding or truncation on update.", "items": { "properties": { "pinnedField": { "description": "Optional fixed headline position. Omit to leave the asset unpinned.", "enum": [ "HEADLINE_1", "HEADLINE_2", "HEADLINE_3" ], "type": "string" }, "text": { "maxLength": 30, "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "maxItems": 15, "minItems": 1, "type": "array" }, "name": { "description": "Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501.", "maxLength": 255, "type": "string" }, "status": { "enum": [ "active", "paused" ], "type": "string" }, "targeting": { "description": "Targeting update. Meta + TikTok: demographics/interests. Google: keyword and device bid adjustment edits only. LinkedIn: locations, B2B facets, audiences. Pinterest / X: return 501.", "properties": { "advantage_audience": { "description": "Meta only. Omit to preserve the existing setting on update. 0 = disabled, 1 = enabled.", "enum": [ 0, 1 ], "type": "integer" }, "ageMax": { "maximum": 65, "minimum": 13, "type": "integer" }, "ageMin": { "maximum": 65, "minimum": 13, "type": "integer" }, "countries": { "description": "ISO 3166-1 alpha-2 codes. On Google this is the FULL new country set for the campaign (same contract as `locations`); on LinkedIn it replaces the campaign's geo criteria.", "items": { "type": "string" }, "type": "array" }, "devices": { "description": "Google only. The FULL new set of device bid modifiers for the campaign. Entries are a device name alone (targeted, bid modifier reset to 1) or { device, bidModifier }.", "items": { "oneOf": [ { "enum": [ "MOBILE", "DESKTOP", "TABLET", "CONNECTED_TV" ], "type": "string" }, { "properties": { "bidModifier": { "description": "Google device bid modifier. 0 switches the device off (minus 100%); otherwise 0.1 to 10 (minus 90% to plus 900%). Google rejects any value between 0 and 0.1.", "maximum": 10, "minimum": 0, "type": "number" }, "device": { "enum": [ "MOBILE", "DESKTOP", "TABLET", "CONNECTED_TV" ], "type": "string" } }, "required": [ "device" ], "type": "object" } ] }, "type": "array" }, "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" }, "keywords": { "description": "Google only. The FULL desired set of positive keywords for the entire ad group. Omit to leave positives unchanged; [] removes all positives. Negatives are independent.", "items": { "oneOf": [ { "type": "string" }, { "properties": { "matchType": { "enum": [ "exact", "phrase", "broad" ], "type": "string" }, "text": { "maxLength": 80, "type": "string" } }, "required": [ "text" ], "type": "object" } ] }, "type": "array" }, "languages": { "description": "Google only. The FULL new language set for the campaign, as Google language codes (ISO 639-1, plus variants such as `zh_CN`). An unknown code returns 400.", "items": { "type": "string" }, "type": "array" }, "locations": { "description": "Google and LinkedIn. The FULL new location set for the campaign. Bare country-code array, or an object with countries/regions/cities/zips/metros key lists (`key` from GET /apis/v1/ads/targeting/search?dimension=geo).", "oneOf": [ { "items": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string" }, "type": "array" }, { "properties": { "cities": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "countries": { "items": { "type": "string" }, "type": "array" }, "metros": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "regions": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" }, "zips": { "items": { "properties": { "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "type": "array" } }, "type": "object" } ] }, "negativeKeywords": { "description": "Google only. The FULL desired set of negative keywords for the entire ad group, independent of positives. Omit to leave negatives unchanged; [] removes all negatives.", "items": { "oneOf": [ { "type": "string" }, { "properties": { "matchType": { "enum": [ "exact", "phrase", "broad" ], "type": "string" }, "text": { "maxLength": 80, "type": "string" } }, "required": [ "text" ], "type": "object" } ] }, "type": "array" } }, "type": "object" } }, "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" } } } } ``` ## Cost and request rules A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar. ## OpenAPI ````yaml reference-contracts/aisa-ads.json PUT /apis/v1/ads/{adId} openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/{adId}: put: summary: Update 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. Changes an ad's budget, targeting or status. Changes an ad's status, budget, targeting or creative and applies the change on the platform. Patch one or more fields on an ad. Status, budget, targeting, and creative changes are propagated to the platform. ### Per-platform support Meta (Facebook + Instagram): all fields supported. A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. operationId: put_aisa_ads_apis_v1_ads_adid parameters: - in: path name: adId required: true schema: type: string - description: >- The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead. in: query name: connectionId required: true schema: pattern: ^adc_[0-9A-Za-z]+$ type: string - description: >- 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 requestBody: content: application/json: example: connectionId: adc_7f3k2m9q descriptions: - pinnedField: DESCRIPTION_1 text: >- Connect social accounts and schedule posts with the AIsa API. - text: Build social publishing into your application. finalUrls: - https://example.com/landing headlines: - pinnedField: HEADLINE_1 text: Social Media API - text: Schedule Your Posts - text: Build With AIsa schema: additionalProperties: true properties: assetGroup: additionalProperties: false description: >- Google Performance Max only. Replaces whole asset roles on the ad's asset group. Returns 422 on any other platform or channel. properties: businessName: description: Replaces the BUSINESS_NAME asset. maxLength: 25 minLength: 1 type: string descriptions: description: >- Replaces every DESCRIPTION asset. At least one must be 60 characters or fewer. items: maxLength: 90 minLength: 1 type: string maxItems: 5 minItems: 2 type: array uniqueItems: true finalUrl: description: Replaces the asset group's final URL. format: uri pattern: ^https?:// type: string headlines: description: Replaces every HEADLINE asset on the group. items: maxLength: 30 minLength: 1 type: string maxItems: 15 minItems: 3 type: array uniqueItems: true images: additionalProperties: false description: >- Public HTTP(S) image URLs. Each role you send replaces that role's images; roles you omit stay. GIF, JPEG or PNG, at most 5120 KB per image. properties: landscape: description: >- Replaces MARKETING_IMAGE assets. Aspect ratio 1.91:1, minimum 600 x 314 pixels. items: format: uri pattern: ^https?:// type: string maxItems: 20 minItems: 1 type: array logo: description: >- Replaces LOGO assets. Aspect ratio 1:1, minimum 128 x 128 pixels. items: format: uri pattern: ^https?:// type: string maxItems: 5 minItems: 1 type: array square: description: >- Replaces SQUARE_MARKETING_IMAGE assets. Aspect ratio 1:1, minimum 300 x 300 pixels. items: format: uri pattern: ^https?:// type: string maxItems: 20 minItems: 1 type: array type: object longHeadline: description: Replaces the LONG_HEADLINE asset. maxLength: 90 minLength: 1 type: string youtubeVideoIds: description: >- Replaces YOUTUBE_VIDEO assets with existing YouTube video ids. Video uploads and arbitrary video URLs are not supported. items: pattern: ^[A-Za-z0-9_-]{11}$ type: string maxItems: 5 minItems: 1 type: array type: object budget: properties: amount: description: >- Minimum varies by platform: TikTok=$20, Pinterest=$5, others=$1 type: number type: description: >- OpenAI Ads accepts both and sets the campaign's single spend cap, replacing the previous daily or lifetime cap. A daily cap cannot go back to lifetime (422). enum: - daily - lifetime type: string type: object connectionId: description: >- The ads connection (adc_...), when not sent as the connectionId query parameter. pattern: ^adc_[0-9A-Za-z]+$ type: string creative: description: >- Replace or patch the ad's creative. Meta, TikTok, and LinkedIn. Meta: patch-style. Pass any subset: omitted fields are preserved from the live creative, including media (`image_hash`/`video_id` reused, no re-upload) and `url_tags`. properties: body: type: string businessName: description: >- Google Display only. Replaces the responsive display ad's business name. maxLength: 25 minLength: 1 type: string callToAction: type: string catalogFormat: description: >- Meta catalog template ads only. Rebuilds the creative with this `template_data.format_option` (same mapping as on create) and repoints the ad at the new creative. enum: - single_image - carousel_images_multi_items - carousel_images_single_item - carousel_slideshows 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 description: description: >- Link description slot (Meta `link_data.description` / `video_data.link_description`, LinkedIn creative description). maxLength: 255 type: string existingCreativeId: description: >- Meta only. Repoint the ad at an existing library creative (from GET /apis/v1/ads/creatives); all other creative fields are ignored. type: string headline: description: Meta and LinkedIn (TikTok has no headline slot) type: string imageUrl: format: uri type: string linkUrl: format: uri type: string longHeadline: description: >- Google Display only. Replaces the responsive display ad's long headline. maxLength: 90 minLength: 1 type: string promotion: description: >- Not supported. Send null or omit the field, and set the Promotion on the ad in Ads Manager. Any object is rejected with 400 invalid_field_value. type: - object - 'null' squareImageUrl: description: >- Google Display only. Uploaded as a new square (1:1) marketing image asset that replaces the current one. format: uri type: string videoId: description: >- Meta only. Reuse an already-uploaded ad video (from POST /apis/v1/ads/videos or GET /apis/v1/ads/videos) instead of re-uploading via videoUrl. type: string videoUrl: format: uri type: string type: object demandGen: additionalProperties: false description: >- Google Demand Gen only. Returns 422 on any other platform or channel. properties: audience: additionalProperties: false description: >- Created as a Google Audience and attached to the ad group. Send at least one dimension. Ids are numeric Google ids (user lists, interest categories, custom audiences) from the same customer. properties: ageRanges: items: properties: max: description: Omit for no upper bound. enum: - 24 - 34 - 44 - 54 - 64 type: integer min: enum: - 18 - 25 - 35 - 45 - 55 - 65 type: integer required: - min type: object maxItems: 6 minItems: 1 type: array customAudiences: items: type: string maxItems: 20 minItems: 1 type: array genders: items: enum: - male - female - undetermined type: string maxItems: 3 minItems: 1 type: array userInterests: items: type: string maxItems: 20 minItems: 1 type: array userLists: items: type: string maxItems: 20 minItems: 1 type: array type: object audienceId: description: >- Attach an existing Google Audience by numeric id instead of audience. 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 businessName: maxLength: 25 type: string callToAction: description: Image and carousel ads only. maxLength: 25 type: string channels: description: >- Replaces the ad group's channel controls. Only the listed channels serve; Google Maps, which this list cannot select, is turned off. Omit to leave the ad group's channel controls unchanged. items: enum: - youtube_in_stream - youtube_in_feed - youtube_shorts - discover - gmail - display type: string minItems: 1 type: array descriptions: items: maxLength: 90 type: string maxItems: 5 minItems: 1 type: array finalUrl: format: uri type: string headlines: items: maxLength: 40 type: string maxItems: 5 minItems: 1 type: array images: additionalProperties: false properties: landscape: items: format: uri type: string maxItems: 20 minItems: 1 type: array logo: items: format: uri type: string maxItems: 5 minItems: 1 type: array portrait: items: format: uri type: string maxItems: 20 minItems: 1 type: array square: items: format: uri type: string maxItems: 20 minItems: 1 type: array type: object longHeadlines: description: Video ads only. items: maxLength: 90 type: string maxItems: 5 minItems: 1 type: array youtubeVideoIds: description: Video ads only. items: pattern: ^[A-Za-z0-9_-]{11}$ type: string maxItems: 5 minItems: 1 type: array type: object descriptions: description: >- Google Search and Display only. Replaces the complete description list. Search takes 2-4, Display 1-5 and rejects pinnedField. No padding or truncation on update. items: properties: pinnedField: description: >- Optional fixed description position. Omit to leave the asset unpinned. enum: - DESCRIPTION_1 - DESCRIPTION_2 type: string text: maxLength: 90 minLength: 1 type: string required: - text type: object maxItems: 5 minItems: 1 type: array finalUrls: description: >- Google Search and Display only. Replaces final URLs. Omitted lists stay unchanged. For Performance Max use assetGroup.finalUrl. items: format: uri type: string minItems: 1 type: array headlines: description: >- Google Search and Display only. Replaces the complete headline list. Search takes 3-15, Display 1-5 and rejects pinnedField; the count is checked once the ad's channel is known. No padding or truncation on update. items: properties: pinnedField: description: >- Optional fixed headline position. Omit to leave the asset unpinned. enum: - HEADLINE_1 - HEADLINE_2 - HEADLINE_3 type: string text: maxLength: 30 minLength: 1 type: string required: - text type: object maxItems: 15 minItems: 1 type: array name: description: >- Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501. maxLength: 255 type: string status: enum: - active - paused type: string targeting: description: >- Targeting update. Meta + TikTok: demographics/interests. Google: keyword and device bid adjustment edits only. LinkedIn: locations, B2B facets, audiences. Pinterest / X: return 501. properties: advantage_audience: description: >- Meta only. Omit to preserve the existing setting on update. 0 = disabled, 1 = enabled. enum: - 0 - 1 type: integer ageMax: maximum: 65 minimum: 13 type: integer ageMin: maximum: 65 minimum: 13 type: integer countries: description: >- ISO 3166-1 alpha-2 codes. On Google this is the FULL new country set for the campaign (same contract as `locations`); on LinkedIn it replaces the campaign's geo criteria. items: type: string type: array devices: description: >- Google only. The FULL new set of device bid modifiers for the campaign. Entries are a device name alone (targeted, bid modifier reset to 1) or { device, bidModifier }. items: oneOf: - enum: - MOBILE - DESKTOP - TABLET - CONNECTED_TV type: string - properties: bidModifier: description: >- Google device bid modifier. 0 switches the device off (minus 100%); otherwise 0.1 to 10 (minus 90% to plus 900%). Google rejects any value between 0 and 0.1. maximum: 10 minimum: 0 type: number device: enum: - MOBILE - DESKTOP - TABLET - CONNECTED_TV type: string required: - device type: object type: array 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 keywords: description: >- Google only. The FULL desired set of positive keywords for the entire ad group. Omit to leave positives unchanged; [] removes all positives. Negatives are independent. items: oneOf: - type: string - properties: matchType: enum: - exact - phrase - broad type: string text: maxLength: 80 type: string required: - text type: object type: array languages: description: >- Google only. The FULL new language set for the campaign, as Google language codes (ISO 639-1, plus variants such as `zh_CN`). An unknown code returns 400. items: type: string type: array locations: description: >- Google and LinkedIn. The FULL new location set for the campaign. Bare country-code array, or an object with countries/regions/cities/zips/metros key lists (`key` from GET /apis/v1/ads/targeting/search?dimension=geo). oneOf: - items: description: ISO 3166-1 alpha-2 country code. type: string type: array - properties: cities: items: properties: key: type: string name: type: string required: - key type: object type: array countries: items: type: string type: array metros: items: properties: key: type: string name: type: string required: - key type: object type: array regions: items: properties: key: type: string name: type: string required: - key type: object type: array zips: items: properties: key: type: string name: type: string required: - key type: object type: array type: object negativeKeywords: description: >- Google only. The FULL desired set of negative keywords for the entire ad group, independent of positives. Omit to leave negatives unchanged; [] removes all negatives. items: oneOf: - type: string - properties: matchType: enum: - exact - phrase - broad type: string text: maxLength: 80 type: string required: - text type: object type: array type: object type: object required: true responses: '200': content: application/json: schema: properties: ad: properties: _id: type: string adSetName: type: string adType: enum: - boost - standalone type: string bidAmount: description: >- Bid amount in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100). Meta: `bid_amount` on the ad set (smallest-denomination int, decoded here). type: - number - 'null' bidStrategy: anyOf: - description: >- Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set) overrides campaign-level. Cross-field rules: `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`. enum: - LOWEST_COST_WITHOUT_CAP - LOWEST_COST_WITH_BID_CAP - COST_CAP - LOWEST_COST_WITH_MIN_ROAS type: string - type: 'null' description: >- Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and TikTok. budget: properties: amount: type: number daily: description: >- LinkedIn and X only. The daily budget (LinkedIn: the parent campaign's `dailyBudget`; X: the line item's, or the campaign's when the line item has none). type: number lifetime: description: >- LinkedIn and X only. The lifetime total (LinkedIn: the parent campaign's `totalBudget`; X: `total_budget_amount_local_micro`, for example the `lifetimeBudgetCap` of a boost), readable even when a daily budget is also set. type: number pacing: description: >- LinkedIn only. The campaign's `pacingStrategy`: how fast LinkedIn may spend the budget. Typically LINEAR or ACCELERATED; the list is open. type: string type: enum: - daily - lifetime type: string type: - object - 'null' campaignName: type: string configuredStatus: description: >- The ad's own on/off switch as configured on the platform, independent of its parents. An ACTIVE ad under a paused ad set or campaign still reads ACTIVE here while `status` reads `paused`. Sources: Meta: `configured_status`. type: - string - 'null' costType: description: >- LinkedIn only. The campaign's EFFECTIVE cost model (billing event) as applied by LinkedIn, refreshed on every sync rather than echoing what was passed on create. `null` for non-LinkedIn ads. `CPM`: cost per thousand impressions. type: - string - 'null' createdAt: format: date-time type: string creative: description: >- Platform-specific creative data. Fields vary by platform. properties: adFormat: description: >- LinkedIn only. The LinkedIn ad format, in LinkedIn's own vocabulary: STANDARD_UPDATE, SINGLE_VIDEO, CAROUSEL, NATIVE_DOCUMENT, EVENT, TEXT_AD, SPOTLIGHT, FOLLOW_COMPANY, JOBS, SPONSORED_INMAILS and others. type: - string - 'null' assetGroup: description: >- Google Performance Max creative assets. At least one description must be 60 characters or fewer. Texts within each list must be distinct. properties: businessName: maxLength: 25 minLength: 1 type: string descriptions: description: >- At least one description must be 60 characters or fewer. items: maxLength: 90 minLength: 1 type: string maxItems: 5 minItems: 2 type: array uniqueItems: true finalUrl: description: Required destination URL. format: uri pattern: ^https?:// type: string headlines: items: maxLength: 30 minLength: 1 type: string maxItems: 15 minItems: 3 type: array uniqueItems: true images: additionalProperties: true description: >- Public HTTP(S) image URLs. GIF, JPEG or PNG, at most 5120 KB per image. Google validates dimensions and aspect ratios. type: object longHeadline: maxLength: 90 minLength: 1 type: string name: description: Defaults to the request name. maxLength: 128 minLength: 1 type: string youtubeVideoId: description: >- Optional existing YouTube video id. Google can generate video when omitted. Video uploads and arbitrary video URLs are not supported. pattern: ^[A-Za-z0-9_-]{11}$ type: string required: - businessName - descriptions - finalUrl - headlines - images - longHeadline type: object assetGroupResourceName: description: >- Google resource name of the created Performance Max asset group. type: string assetResourceName: description: >- Google Display only. Resource name of the landscape marketing image asset (`creative.imageUrl`), for example customers/1234567890/assets/123. type: string assets: description: >- Google Display only. Native Google asset resource name of each image on the responsive display ad, keyed by Google's image role. properties: marketingImages: description: >- Landscape (1.91:1) marketing images. The first item matches `assetResourceName`. items: additionalProperties: true type: object type: array squareMarketingImages: description: Square (1:1) marketing images. items: additionalProperties: true type: object type: array type: object bodies: description: >- Meta: every primary text variation of the creative (`asset_feed_spec.bodies`), the same shape as the `bodies` create input. Present only with 2 or more texts; a single text is `body`. items: type: string type: array body: description: Ad copy/text type: string callToAction: description: >- Meta: the call to action type (`call_to_action.type`, or the first `asset_feed_spec.call_to_action_types` entry), e.g. LEARN_MORE or SIGN_UP. type: string carouselCards: description: >- Meta only today. The carousel's cards in display order, one per Meta `link_data.child_attachments` entry, using the same field names as the `carouselCards` create input. Absent on non-carousel ads and other platforms. items: additionalProperties: true type: object type: array catalog: properties: format: description: >- object_story_spec.template_data.format_option, from catalogFormat. enum: - single_image - carousel_images_multi_items - carousel_images_single_item - carousel_slideshows type: string formatTransformationSpec: description: >- The format_transformation_spec sent on the creative, as Meta's raw objects. Present for single_image. items: additionalProperties: true type: object type: array productSetId: description: The creative's product_set_id. type: string type: object creativeFeatures: additionalProperties: enum: - OPT_IN - OPT_OUT type: string description: >- Meta Advantage+ creative enhancements. Map snake_case feature names to OPT_IN or OPT_OUT; Meta validates supported keys and unspecified features default to OPT_OUT. type: object creativeId: description: >- Meta ad creative id backing this ad, refreshed from Meta on every sync. Reusable via existingCreativeId on POST /apis/v1/ads/create, and readable raw through GET /apis/v1/ads/creatives/{creativeId}. type: - string - 'null' description: description: >- Meta: the creative's description under the title (`link_data.description`, `video_data.link_description`, or the first `asset_feed_spec.descriptions` entry). type: string descriptions: description: >- Google RSA: the description assets as objects (2 to 4). Meta: every description variation of the creative (`asset_feed_spec.descriptions`) as strings, the same shape as the `descriptions` create input. items: oneOf: - type: string - additionalProperties: true type: object maxItems: 4 type: array effectiveInstagramMediaId: description: >- Meta `effective_instagram_media_id`, the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /apis/v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad. type: - string - 'null' effectiveObjectStoryId: description: >- Meta `effective_object_story_id`, the `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. type: - string - 'null' finalUrls: description: >- Google RSA only. Replaces final URLs. Omitted lists stay unchanged. items: format: uri type: string minItems: 1 type: array googleDescription: description: Google Ads description type: string googleHeadline: description: Google Ads headline type: string headline: description: >- Meta: the creative's title (`link_data.name`, `video_data.title`, or the first `asset_feed_spec.titles` entry). Absent when the creative has none. type: string headlines: description: >- Google RSA: the headline assets as objects (3 to 15). Meta: every title variation of the creative (`asset_feed_spec.titles`) as strings, the same shape as the `headlines` create input. items: oneOf: - type: string - additionalProperties: true type: object maxItems: 15 type: array imageHash: description: >- Meta: the ad image hash (`image_hash`), reusable as `imageHash` on POST /apis/v1/ads/create within the same ad account. `thumbnailUrl` and `mediaUrls` carry its stable full resolution permalink when Meta resolves it. type: string imageUrl: description: Alternative image URL type: string instagramPermalinkUrl: description: >- Meta `instagram_permalink_url`, the public Instagram post URL of the boosted media. type: - string - 'null' instagramUserId: description: >- Meta `instagram_user_id`, the Instagram-scoped business ID that owns the boosted media. type: - string - 'null' instagramVideoFallback: description: >- Meta only. `instagram_video_reuploaded`: the video was copied into the ad account, and the ad still references the original post. properties: kind: enum: - instagram_video_reuploaded - instagram_video_rehosted_copy type: string linkedToOriginalPost: description: >- True when the ad still references the original Instagram post and keeps its engagement. type: boolean platformError: additionalProperties: true description: Meta's original refusal. type: object videoId: description: >- instagram_video_reuploaded: the copy in the ad account video library (possibly one made by an earlier boost of the same media, reused). type: string required: - kind - linkedToOriginalPost - platformError - videoId type: object isServing: description: >- LinkedIn only. Whether LinkedIn is currently serving this specific creative. Complements the ad-level `servingStatuses`, which describes the parent campaign. type: - boolean - 'null' leadGenFormId: description: >- Meta: the instant form the call to action opens (`call_to_action.value.lead_gen_form_id`, or the asset feed's `call_to_actions` on a dynamic creative), the same value as the `leadGenFormId` create input. Absent on ads without a lead form. type: string linkUrl: description: Destination URL type: string mediaUrls: description: >- All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts). items: type: string type: array objectStoryId: description: >- Meta creative `object_story_id` (the SHARE reference). Frequently absent, because Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead. type: - string - 'null' objectType: description: >- Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews: when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available. type: string pageId: description: >- Facebook Page backing the creative (Meta only). What the `pageId` filter on /apis/v1/ads, /apis/v1/ads/campaigns and /apis/v1/ads/tree matches against. Absent for non-Meta ads and rare Meta creatives with no page signal. type: - string - 'null' pinterestDescription: type: string pinterestImageUrl: type: string pinterestTitle: type: string servingHoldReasons: description: >- LinkedIn only. Why this specific creative is not being served. Empty when it is serving. items: type: string type: array thumbnailUrl: description: Primary thumbnail/image URL type: - string - 'null' urlTags: description: >- Meta: the creative's `url_tags` query string appended to the destination URL. type: - string - 'null' videoId: description: >- Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token. type: - string - 'null' videoUrl: description: Null for non-video ads. type: - string - 'null' whatsappPhoneNumber: description: >- Explicit E.164 WhatsApp number supplied when creating a Meta boost or messaging ad. Absent when omitted by the caller or on older records. type: string youtubeVideoIds: description: >- Google only. YouTube video ids behind a Video campaign ad (video and responsive video ads) or a Demand Gen video ad, same id as `youtubeVideoId` on Performance Max asset groups. items: type: string type: array type: - object - 'null' creativeType: description: >- Creative format, classified from the media the creative carries. `null` when the creative carries no media to classify. An unsynced creative and a genuine text-only ad are indistinguishable, so neither is guessed at. enum: - carousel - video - document - image - null type: - string - 'null' goal: description: 'Available goals vary by platform:' enum: - engagement - traffic - awareness - video_views - lead_generation - lead_conversion - conversions - app_promotion - catalog_sales - page_likes - page_visits - job_applicants type: string isExternal: description: True for ads synced from platform ad managers type: boolean metrics: anyOf: - properties: actionValues: additionalProperties: type: number description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: type: integer description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: type: number description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number engagement: type: integer engagementBreakdown: description: >- The single `engagement` total, split into the interactions behind it. properties: comments: description: Comments on the ad's post. type: integer linkClicks: description: >- Attributed link clicks (`link_click`). This is the attribution-window count, which differs from the in-session count in the sibling `inlineLinkClicks` field. type: integer pageEngagement: description: >- Meta's own page-engagement total (`page_engagement`). Meta-only. type: integer pageLikes: description: >- New Page likes attributed to the ad (`like`). type: integer postEngagement: description: >- Meta's own post-engagement total (`post_engagement`). Meta-only. type: integer reactions: description: >- Reactions on the ad's post (`post_reaction`). For TikTok these are its paid likes. type: integer saves: description: >- Saves of the ad's post (`onsite_conversion.post_save`). type: integer shares: description: >- Shares of the ad's post. Meta reports these under the action type literally named `post`; TikTok under `share`. type: integer videoViews: description: >- Video views, from the `video_view` action. Meta counts a 3-second view; LinkedIn's own `videoViews` threshold (2 continuous seconds, or 25% of the video) lands under the same key, so compare across platforms with care. type: integer type: object funnel: description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. properties: appInstalls: description: Mobile app installs attributed to the ad. type: integer cartAdds: description: >- Adds to cart (Meta `AddToCart` pixel event). type: integer checkoutsInitiated: description: >- Checkouts started (Meta `InitiateCheckout` pixel event). type: integer contentViews: description: >- Content views (Meta `ViewContent` pixel event). type: integer landingPageViews: description: >- Landing page views: the visitor actually loaded the destination, unlike a link click. Meta `landing_page_view`. type: integer leads: description: >- Leads, from either the website pixel or an instant form, whichever the ad uses. type: integer messagingConversationsStarted: description: >- Messaging conversations started within 7 days, the headline metric for click-to-WhatsApp and click-to-Messenger ads. type: integer messagingFirstReplies: description: >- Messaging threads where the person sent a first reply. type: integer paymentInfoAdds: description: >- Payment details added at checkout (Meta `AddPaymentInfo` pixel event). type: integer purchases: description: >- Purchases. Pair with `purchaseValue` for revenue. type: integer registrationsCompleted: description: >- Completed registrations (Meta `CompleteRegistration` pixel event). type: integer searches: description: >- On-site searches (Meta `Search` pixel event). type: integer wishlistAdds: description: >- Adds to wishlist (Meta `AddToWishlist` pixel event). type: integer type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object - type: 'null' name: type: string optimizationGoal: description: >- What the delivery system optimizes for, at ad-set level. The value space depends on `platform`: Meta: ad set `optimization_goal` (e.g. OFFSITE_CONVERSIONS, VALUE, LEAD_GENERATION, LINK_CLICKS). type: - string - 'null' platform: enum: - facebook - instagram - tiktok - linkedin - pinterest - google - twitter - openai - reddit - microsoft type: string platformAdAccountId: type: string platformAdAccountName: description: >- Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok `advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every sync so platform-side renames propagate within one cycle. type: - string - 'null' platformAdId: type: string platformAdSetId: type: string platformCampaignId: type: string platformCreatedAt: description: >- Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`). Read this field to sort or filter by when the ad was actually created on the platform. format: date-time type: - string - 'null' platformObjective: description: >- The platform's own campaign objective, verbatim, alongside the normalized `goal` it maps to. The mapping is many-to-one, so `goal` alone cannot be mapped back to it. Meta: campaign `objective` (e.g. type: - string - 'null' promotedObject: description: >- Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads. properties: application_id: description: Facebook app ID type: string custom_event_type: description: >- Conversion event type (e.g. PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART) type: string page_id: description: Facebook page ID type: string pixel_id: description: Meta pixel ID type: string product_set_id: description: Product catalog set ID type: string type: - object - 'null' rejectionReason: type: string reviewStatus: description: >- Platform review state of this ad, independent of delivery `status` / `configuredStatus`. Absent when the platform reports no review signal. enum: - in_review - approved - rejected - with_issues type: string roasAverageFloor: description: >- Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy is `LOWEST_COST_WITH_MIN_ROAS`. type: - number - 'null' schedule: description: Delivery window as UTC instants. properties: endDate: format: date-time type: string startDate: format: date-time type: string type: - object - 'null' servingStatuses: description: >- LinkedIn only. Why the parent campaign is (or is not) delivering, verbatim from LinkedIn. A campaign can report `status: ACTIVE` and still serve nothing; this array says so. items: type: string type: array status: description: >- Delivery status. Derived from the platform `effective_status`, so it inherits ancestor pauses (an ACTIVE ad under a PAUSED campaign reads `paused`). enum: - active - paused - pending_review - rejected - completed - cancelled - error type: string synced: description: >- Only on GET /apis/v1/ads/{adId}. An unsynced ad has no `id`. type: boolean targeting: description: >- The ad set's targeting (age, gender, geo, interests, placements, audience inclusions/exclusions). May be absent if the ad set exposes no targeting or the lookup fails. type: object updatedAt: format: date-time type: string type: object message: type: string type: object description: Ad updated 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.