> ## 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 # List ads > Ad Campaigns. Read only. Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager. Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, it defaults to the last 90 days. The date range is capped at 730 days max. ### History 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:** GET /apis/v1/ads * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/ads` * **connectionId:** query; required * **page:** query; optional * **limit:** query; optional * **source:** query; optional * **status:** query; optional * **platform:** query; optional * **adAccountId:** query; optional * **pageId:** query; optional * **campaignId:** query; optional * **adSetId:** query; optional * **platformAdId:** query; optional * **effectiveObjectStoryId:** query; optional * **effectiveInstagramMediaId:** query; optional * **fromDate:** query; optional * **toDate:** query; 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": "get_aisa_ads_apis_v1_ads", "method": "GET", "path": "/apis/v1/ads", "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": "Page number (1-based)", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "aisa", "all" ], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "pending_review", "rejected", "completed", "cancelled", "error" ], "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "facebook", "instagram", "tiktok", "linkedin", "pinterest", "google", "twitter", "openai", "reddit", "microsoft", "meta", "x" ], "type": "string" } }, { "description": "Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /apis/v1/ads/campaigns and /apis/v1/ads/tree.", "in": "query", "name": "adAccountId", "required": false, "schema": { "type": "string" } }, { "description": "Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager).", "in": "query", "name": "pageId", "required": false, "schema": { "type": "string" } }, { "description": "Platform campaign ID (filter ads within a campaign) Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "in": "query", "name": "campaignId", "required": false, "schema": { "type": "string" } }, { "description": "Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "in": "query", "name": "adSetId", "required": false, "schema": { "type": "string" } }, { "description": "Meta ad ID. Returns the ad with this platform-side ad ID. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.", "in": "query", "name": "platformAdId", "required": false, "schema": { "type": "string" } }, { "description": "Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`).", "in": "query", "name": "effectiveObjectStoryId", "required": false, "schema": { "type": "string" } }, { "description": "Instagram media ID of the boosted post (Meta `effective_instagram_media_id`).", "in": "query", "name": "effectiveInstagramMediaId", "required": false, "schema": { "type": "string" } }, { "description": "Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 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 GET /apis/v1/ads 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: get: summary: List ads description: >- Ad Campaigns. Read only. Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager. Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, it defaults to the last 90 days. The date range is capped at 730 days max. ### History A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. operationId: get_aisa_ads_apis_v1_ads 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: Page number (1-based) in: query name: page required: false schema: default: 1 minimum: 1 type: integer - in: query name: limit required: false schema: default: 50 maximum: 500 minimum: 1 type: integer - in: query name: source required: false schema: default: all enum: - aisa - all type: string - in: query name: status required: false schema: enum: - active - paused - pending_review - rejected - completed - cancelled - error type: string - in: query name: platform required: false schema: enum: - facebook - instagram - tiktok - linkedin - pinterest - google - twitter - openai - reddit - microsoft - meta - x type: string - description: >- Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /apis/v1/ads/campaigns and /apis/v1/ads/tree. in: query name: adAccountId required: false schema: type: string - description: >- Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). in: query name: pageId required: false schema: type: string - description: >- Platform campaign ID (filter ads within a campaign) Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. in: query name: campaignId required: false schema: type: string - description: >- Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. in: query name: adSetId required: false schema: type: string - description: >- Meta ad ID. Returns the ad with this platform-side ad ID. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found. in: query name: platformAdId required: false schema: type: string - description: >- Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`). in: query name: effectiveObjectStoryId required: false schema: type: string - description: >- Instagram media ID of the boosted post (Meta `effective_instagram_media_id`). in: query name: effectiveInstagramMediaId required: false schema: type: string - description: Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago. in: query name: fromDate required: false schema: format: date type: string - description: >- End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range. in: query name: toDate required: false schema: format: date type: string responses: '200': content: application/json: schema: properties: ads: items: 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: additionalProperties: true description: >- Google Performance Max creative assets. At least one description must be 60 characters or fewer. Texts within each list must be distinct. 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: additionalProperties: true description: >- Google Display only. Native Google asset resource name of each image on the responsive display ad, keyed by Google's image role. 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: additionalProperties: true type: object creativeFeatures: additionalProperties: true 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: additionalProperties: true description: >- Meta only. `instagram_video_reuploaded`: the video was copied into the ad account, and the ad still references the original post. 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: true description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: true description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: true description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number engagement: type: integer engagementBreakdown: additionalProperties: true description: >- The single `engagement` total, split into the interactions behind it. type: object funnel: additionalProperties: true description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object - type: '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 type: array backfillPending: description: >- Meta only. Present and true while historical data is being backfilled. type: boolean pagination: properties: limit: type: integer page: type: integer pages: type: integer total: type: integer type: object type: object description: Paginated ads '202': content: application/json: schema: properties: ads: items: 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: additionalProperties: true description: >- Google Performance Max creative assets. At least one description must be 60 characters or fewer. Texts within each list must be distinct. 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: additionalProperties: true description: >- Google Display only. Native Google asset resource name of each image on the responsive display ad, keyed by Google's image role. 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: additionalProperties: true type: object creativeFeatures: additionalProperties: true 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: additionalProperties: true description: >- Meta only. `instagram_video_reuploaded`: the video was copied into the ad account, and the ad still references the original post. 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: true description: >- Monetary mirror of `actions`, from Meta's Insights `action_values[]` array. Meta and TikTok; other platforms return {}. Same history note as `actions`. type: object actions: additionalProperties: true description: >- Per-action-type counts summed over the date range, keyed by the platform's action-type names. Keys differ by platform, so branch on the ad's platform when interpreting them. Empty object when no actions are reported. type: object allConversions: description: >- All conversions, including actions excluded from the Conversions column (Google metrics.all_conversions). 0 on platforms without the concept. type: number clicks: type: integer conversions: description: >- Count of conversion events over the requested date range. FRACTIONAL: attribution splits one conversion across touchpoints and Google also reports modeled conversions, so values like 0.347 are normal. type: number costPerAction: additionalProperties: true description: >- Derived `spend / actions[type]` for every action type with a non-zero count, in ad-account native currency. Same keys as `actions`. Rounded to 4 decimals, because cheap actions cost well under a cent. type: object costPerConversion: description: >- Derived spend / conversions in the same currency as spend. 0 when conversions is 0. type: number costPerThruplay: description: >- Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only). type: number cpc: description: Cost per click type: number cpm: description: Cost per 1000 impressions type: number ctr: description: Click-through rate (%) type: number engagement: type: integer engagementBreakdown: additionalProperties: true description: >- The single `engagement` total, split into the interactions behind it. type: object funnel: additionalProperties: true description: >- Named conversion-funnel steps, resolved from the same data as `actions` so you never have to parse action-type strings yourself. type: object impressions: type: integer inlineLinkClickCtr: description: >- Derived `inlineLinkClicks / impressions * 100`, recomputed from sums at every rollup level. type: number inlineLinkClicks: description: >- In-session link clicks. Differs from the attributed `link_click` count in `actions`/`engagementBreakdown.linkClicks`, which uses the attribution window. Meta-only. type: integer lastSyncedAt: description: >- Present on individual ads only, not on campaign aggregations format: date-time type: string outboundClicks: description: >- Clicks leading off Meta's surfaces to the advertiser's destination. Meta-only; other platforms report 0. type: integer outboundClicksCtr: description: >- Derived `outboundClicks / impressions * 100`, recomputed from sums at every rollup level. type: number purchaseValue: description: >- Convenience sum of purchase-type action values, in ad-account native currency. 0 when the campaign has no purchase event configured. type: number reach: description: >- Unique people reached in the requested date range. Meta (facebook/instagram) and TikTok: the platform's own de-duplicated reach for the exact range, fetched live and cached up to ~1 hour (may lag recent delivery). type: integer roas: description: >- Return on ad spend, derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. type: number spend: type: number uniqueClicks: description: >- People who clicked at least once. NOT additive: summed across days/children it overcounts people who clicked on multiple days or ads, so treat rollups as an upper bound (same caveat as `reach`). Meta-only. type: integer uniqueCtr: description: >- Derived `uniqueClicks / impressions * 100` (NOT Meta's reach-based unique_ctr). Inherits the non-additivity caveat of `uniqueClicks`. type: number video2SecWatchedActions: description: >- Plays of at least 2 seconds, replays excluded. Hook rate = video2SecWatchedActions / impressions. Sources: TikTok `video_watched_2s` (TikTok only; Meta's closest field, 2-second continuous plays, is not synced). type: integer video30SecWatchedActions: description: >- Views of at least 30 seconds (or to the end, for shorter videos). type: integer video6SecFocusedViews: description: >- TikTok's 6-second focused views: plays of at least 6 seconds (or to the end, for shorter videos) or with an interaction in the first 6 seconds, so it is at least `video6SecWatchedActions`. Sources: TikTok `engaged_view` (TikTok only). type: integer video6SecWatchedActions: description: >- Plays of at least 6 seconds, replays excluded. Hold rate = video6SecWatchedActions / video2SecWatchedActions. Sources: TikTok `video_watched_6s` (TikTok only). Same history note as `video2SecWatchedActions`. type: integer videoAvgTimeWatchedActions: description: >- Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. type: number videoP100WatchedActions: description: Views reaching 100% of the video's length. type: integer videoP25WatchedActions: description: >- Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). type: integer videoP50WatchedActions: description: Views reaching 50% of the video's length. type: integer videoP75WatchedActions: description: Views reaching 75% of the video's length. type: integer videoP95WatchedActions: description: >- Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions`, Pinterest `TOTAL_VIDEO_P95_COMBINED`. type: integer videoPlayActions: description: >- Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. type: integer videoThruplayWatchedActions: description: >- ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only). type: integer type: object - type: '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 type: array backfillPending: description: >- Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200. type: boolean pagination: properties: limit: type: integer page: type: integer pages: type: integer total: type: integer type: object required: - backfillPending type: object description: >- Meta only. Historical data is incomplete and backfill remains pending. default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.