> ## 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 campaigns > Ad Campaigns. Read only. Lists your campaigns with spend, impressions and clicks summed across their ads, plus each campaign's status and budget. Campaigns are virtual aggregations over ad documents grouped by platform campaign ID. Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 ## 请求规范 * **方法与路径:** GET /apis/v1/ads/campaigns * **可用状态:** enabled * **请求 URL 模板:** `https://api.aisa.one/apis/v1/ads/campaigns` * **connectionId:** query; 必填 * **includeEmpty:** query; 可选 * **page:** query; 可选 * **limit:** query; 可选 * **source:** query; 可选 * **platform:** query; 可选 * **status:** query; 可选 * **adAccountId:** query; 可选 * **campaignId:** query; 可选 * **pageId:** query; 可选 * **fromDate:** query; 可选 * **toDate:** query; 可选 * **hasDelivery:** query; 可选 * **minSpend:** query; 可选 * **live:** query; 可选 * **Runtime 事实版本:** fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 [完整 OpenAPI 定义](https://aisa.one/docs/reference-contracts/zh/aisa-ads.json) 有效请求与价格声明（包括认证和引用的 schema）： ```json theme={null} { "operationId": "get_aisa_ads_apis_v1_ads_campaigns", "method": "GET", "path": "/apis/v1/ads/campaigns", "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": "Meta only. Set true to also list campaigns with ZERO ads, with `adCount: 0` and zeroed metrics. Campaign reads aggregate over ad documents, so such campaigns are normally invisible.", "in": "query", "name": "includeEmpty", "required": false, "schema": { "type": "boolean" } }, { "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": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Matches the web UI's default view. Status is NOT filtered by default; use the `status` param for that.", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "aisa", "all" ], "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": "Filter by derived campaign status (post-aggregation)", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "active", "paused", "pending_review", "rejected", "completed", "cancelled", "error" ], "type": "string" } }, { "description": "Platform ad account ID (e.g. act_123 for Meta)", "in": "query", "name": "adAccountId", "required": false, "schema": { "type": "string" } }, { "description": "Platform campaign ID (the `platformCampaignId` on each returned campaign). Returns only that campaign, or an empty list when it is not visible to the caller. Mirrors the same filter on /apis/v1/ads and /apis/v1/ads/tree. 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": "Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only.", "in": "query", "name": "pageId", "required": false, "schema": { "type": "string" } }, { "description": "Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End of metrics date range (YYYY-MM-DD, inclusive). Defaults to today. Max 730-day range.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Return only campaigns that delivered between `fromDate` and `toDate`: spend above zero, or impressions served at zero spend. Unlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window.", "in": "query", "name": "hasDelivery", "required": false, "schema": { "type": "boolean" } }, { "description": "Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount, in each campaign's OWN currency (the `currency` field on the campaign). Implies `hasDelivery`; `minSpend=0` applies no filter.", "in": "query", "name": "minSpend", "required": false, "schema": { "minimum": 0, "type": "number" } }, { "description": "Read the on/off switches live from the platform instead of returning synced values. See \"Status freshness\" in the operation description.", "in": "query", "name": "live", "required": false, "schema": { "default": false, "type": "boolean" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.", "kind": "no_customer_charge" }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## 费用与请求规则 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 公开参考值不是你的账户报价或最终扣费。对于支持 X-AISA-Cost-Mode: quote 的接口，执行前请针对完整请求获取免费报价；执行后通过响应费用元数据和 Usage Logs 核对结算费用。1 USD 等于 1,000,000 个整数 micro-USD。 ## OpenAPI ````yaml reference-contracts/zh/aisa-ads.json GET /apis/v1/ads/campaigns 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/campaigns: get: summary: List campaigns description: >- Ad Campaigns. Read only. Lists your campaigns with spend, impressions and clicks summed across their ads, plus each campaign's status and budget. Campaigns are virtual aggregations over ad documents grouped by platform campaign ID. Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign. 当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。 operationId: get_aisa_ads_apis_v1_ads_campaigns 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: >- Meta only. Set true to also list campaigns with ZERO ads, with `adCount: 0` and zeroed metrics. Campaign reads aggregate over ad documents, so such campaigns are normally invisible. in: query name: includeEmpty required: false schema: type: boolean - 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: 20 maximum: 100 minimum: 1 type: integer - description: >- Matches the web UI's default view. Status is NOT filtered by default; use the `status` param for that. in: query name: source required: false schema: default: all enum: - aisa - all 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: Filter by derived campaign status (post-aggregation) in: query name: status required: false schema: enum: - active - paused - pending_review - rejected - completed - cancelled - error type: string - description: Platform ad account ID (e.g. act_123 for Meta) in: query name: adAccountId required: false schema: type: string - description: >- Platform campaign ID (the `platformCampaignId` on each returned campaign). Returns only that campaign, or an empty list when it is not visible to the caller. Mirrors the same filter on /apis/v1/ads and /apis/v1/ads/tree. 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: >- Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only. in: query name: pageId required: false schema: type: string - description: >- Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted. in: query name: fromDate required: false schema: format: date type: string - description: >- End of metrics date range (YYYY-MM-DD, inclusive). Defaults to today. Max 730-day range. in: query name: toDate required: false schema: format: date type: string - description: >- Return only campaigns that delivered between `fromDate` and `toDate`: spend above zero, or impressions served at zero spend. Unlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window. in: query name: hasDelivery required: false schema: type: boolean - description: >- Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount, in each campaign's OWN currency (the `currency` field on the campaign). Implies `hasDelivery`; `minSpend=0` applies no filter. in: query name: minSpend required: false schema: minimum: 0 type: number - description: >- Read the on/off switches live from the platform instead of returning synced values. See "Status freshness" in the operation description. in: query name: live required: false schema: default: false type: boolean responses: '200': content: application/json: schema: properties: campaigns: items: properties: adCount: type: integer advertisingChannelType: description: >- Google-only. Raw campaign.advertising_channel_type. See AdTreeCampaign.advertisingChannelType. type: - string - 'null' bidAmount: description: >- Representative bid from the top-spending ad set (whole currency units). Meta: populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. LinkedIn: the campaign unitCost, ungated, where 0 is a real delivery-stopping value. 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: >- Campaign-level bid strategy. Ad sets inherit this unless they override. budget: anyOf: - description: >- Budget amount in the ad account's native currency (see the campaign's `currency` field for the code). properties: amount: type: number amountMicros: description: >- Google only. Exact decimal micros; DAILY uses amount_micros and CUSTOM_PERIOD uses total_amount_micros. pattern: ^\d+$ type: string deliveryMethod: description: >- Google only. campaign_budget.delivery_method, typically STANDARD, or null when unavailable. type: - string - 'null' explicitlyShared: description: >- Google only. True for a shared budget; null when unavailable. Shared writes require allowSharedBudgetUpdate=true; unknown sharing status cannot be overridden. type: - boolean - 'null' resourceName: description: >- Google only. campaign_budget.resource_name, or null when unavailable. type: - string - 'null' type: enum: - daily - lifetime type: string required: - amount - type type: object - type: 'null' description: >- Effective budget. Google metadata arrives after the next successful sync. budgetLevel: description: >- Canonical CBO/ABO indicator. See AdTreeCampaign.budgetLevel. enum: - campaign - adset type: - string - 'null' campaignBudget: anyOf: - description: >- Budget amount in the ad account's native currency (see the campaign's `currency` field for the code). properties: amount: type: number amountMicros: description: >- Google only. Exact decimal micros; DAILY uses amount_micros and CUSTOM_PERIOD uses total_amount_micros. pattern: ^\d+$ type: string deliveryMethod: description: >- Google only. campaign_budget.delivery_method, typically STANDARD, or null when unavailable. type: - string - 'null' explicitlyShared: description: >- Google only. True for a shared budget; null when unavailable. Shared writes require allowSharedBudgetUpdate=true; unknown sharing status cannot be overridden. type: - boolean - 'null' resourceName: description: >- Google only. campaign_budget.resource_name, or null when unavailable. type: - string - 'null' type: enum: - daily - lifetime type: string required: - amount - type type: object - type: 'null' description: Campaign-level budget. Null for ad-set budgets. campaignIssuesInfo: description: >- Platform-reported campaign issues (Meta `issues_info[]`). items: additionalProperties: true type: object type: - array - 'null' campaignName: type: string configReadAt: description: >- Only on GET /apis/v1/ads/campaigns with `live=true`. When `nativeSettings` was read from the platform. Null whenever native settings were not read now. format: date-time type: - string - 'null' connectionId: description: The ads connection (adc_...) the object belongs to. type: - string - 'null' currency: description: >- ISO 4217 currency code for all budget amounts. Budgets are NOT normalized to USD. type: - string - 'null' earliestAd: format: date-time type: string isBudgetScheduleEnabled: default: false description: >- Meta-only. Mirrors Campaign.is_budget_schedule_enabled. type: boolean isSmartPlus: description: >- TikTok only. true when the campaign is an Upgraded Smart+ campaign. See AdTreeCampaign.isSmartPlus. type: boolean latestAd: format: date-time type: string metrics: 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 nativeSettings: additionalProperties: true description: >- TikTok only, only on GET /apis/v1/ads/campaigns with `live=true` and only on campaigns read live. type: object optimizationGoal: anyOf: - type: string - items: type: string type: array description: >- The campaign's optimization goal. Every ad set shares one goal: a single string. Ad sets differ: a JSON array of the distinct goals (never a comma-joined string). Element order is not guaranteed; treat it as an unordered set. platform: enum: - facebook - instagram - tiktok - linkedin - pinterest - google - twitter - openai - reddit - microsoft type: string platformAdAccountId: type: string platformAdAccountName: description: >- Human-readable advertiser/account name from the platform. Refreshed on every sync. type: - string - 'null' platformCampaignId: type: string platformCampaignStatus: description: >- Raw platform-level campaign status (Meta `effective_status`; ChatGPT (OpenAI): the campaign's own switch, active / paused / archived; TikTok: the campaign's own switch `operation_status`, ENABLE / DISABLE; Reddit: the campaign's… type: - string - 'null' platformObjective: description: >- Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC) type: - string - 'null' promotedObject: description: >- Meta promoted object at campaign level (conversion event details) properties: custom_event_type: type: string page_id: type: string pixel_id: type: string type: - object - 'null' reviewStatus: anyOf: - description: >- Platform-side review state, independent of the delivery `status` and the `configuredStatus` on/off toggle. `in_review` means the platform is still reviewing. Absent when the platform reports no review signal (e.g. enum: - in_review - approved - rejected - with_issues type: string - type: 'null' description: >- Platform-side review state of the campaign. See AdTreeCampaign.reviewStatus for the full description. roasAverageFloor: description: >- Representative ROAS floor from the top-spending ad set. Decimal multiplier (2.0 = 2.0x). type: - number - 'null' status: description: >- Delivery status derived from child ad statuses. Distinct from `reviewStatus`. enum: - active - paused - pending_review - rejected - completed - cancelled - error type: string statusReadAt: description: >- Only on GET /apis/v1/ads/campaigns with `live=true`. When `platformCampaignStatus` was read from the platform; null when this campaign could not be read live. format: date-time type: - string - 'null' type: object type: array pagination: properties: limit: type: integer page: type: integer pages: type: integer total: type: integer type: object type: object description: Paginated campaigns 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.