> ## 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 ad accounts > Ad Accounts. Read only. Lists the ad accounts a connection can manage, such as Meta ad accounts, TikTok advertisers or Google Ads customers. Returns the platform ad accounts available for the given account (e.g. Meta ad accounts, TikTok advertiser IDs, Google Ads customer IDs). ### Meta Meta business-login accounts use their own system-user token. 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/accounts * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/ads/accounts` * **connectionId:** query; required * **adAccountId:** query; optional * **limit:** query; optional * **inScopeOnly:** 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_accounts", "method": "GET", "path": "/apis/v1/ads/accounts", "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": "Filter response to a single platform ad account ID (e.g. `act_123` for Meta, advertiser_id for TikTok). Returns at most one item.", "in": "query", "name": "adAccountId", "required": false, "schema": { "type": "string" } }, { "description": "Clamp the returned `accounts[]` length. Useful for typeahead pickers on agency tokens with hundreds of advertisers.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "`true` returns only the ad accounts this connection accepts as `adAccountId` on the other /apis/v1/ads endpoints, i.e. those inside its ad-account selection (every item then has `selected: true`).", "in": "query", "name": "inScopeOnly", "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" } } } } ``` ## 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/accounts 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/accounts: get: summary: List ad accounts description: >- Ad Accounts. Read only. Lists the ad accounts a connection can manage, such as Meta ad accounts, TikTok advertisers or Google Ads customers. Returns the platform ad accounts available for the given account (e.g. Meta ad accounts, TikTok advertiser IDs, Google Ads customer IDs). ### Meta Meta business-login accounts use their own system-user token. 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_accounts 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: >- Filter response to a single platform ad account ID (e.g. `act_123` for Meta, advertiser_id for TikTok). Returns at most one item. in: query name: adAccountId required: false schema: type: string - description: >- Clamp the returned `accounts[]` length. Useful for typeahead pickers on agency tokens with hundreds of advertisers. in: query name: limit required: false schema: maximum: 1000 minimum: 1 type: integer - description: >- `true` returns only the ad accounts this connection accepts as `adAccountId` on the other /apis/v1/ads endpoints, i.e. those inside its ad-account selection (every item then has `selected: true`). in: query name: inScopeOnly required: false schema: default: false type: boolean responses: '200': content: application/json: schema: properties: accounts: items: properties: accountStatus: description: >- The platform's own account status, forwarded unchanged. No JSON type is declared because it differs per platform: Meta sends an integer; Google, TikTok and Pinterest send a string. approvalStatus: description: >- X and Reddit only. X's own ad account approval status, or Reddit's `admin_approval`. Observed X values are `ACCEPTED`, `PENDING` and `REJECTED`, but X does not publish the full vocabulary, so treat an unrecognised value as not usable. type: string balance: description: >- TikTok only. Total balance the advertiser can spend (cash plus grant), in whole units of `currency`. type: number billingStatus: description: >- Meta only. Whether the ad account has a payment method: enum: - ok - missing - unknown type: string businessId: description: >- Meta only. Owning Business Manager ID when available on the grant. type: string businessName: description: Owning business name when supplied by the platform. type: string cashBalance: description: >- TikTok only. Cash part of `balance`, in whole units of `currency`. Absent when the connection has no finance role in the advertiser's Business Center. type: number currency: type: string disableReason: description: >- Meta only. Meta's `disable_reason` code, forwarded unchanged. Present when `accountStatus` is `2` (DISABLED) and Meta gives a reason; this separates a policy action from a payment problem. type: integer fundingSource: description: >- Meta only. Meta's `funding_source` ID for the ad account, forwarded unchanged. ABSENT both when this connection's token cannot see billing and when the account has no payment method; read `billingStatus` to tell the two apart. type: string fundingSourceDetails: description: >- Meta only. Meta's `funding_source_details` object, forwarded unchanged. ABSENT under exactly the same conditions as `fundingSource`, never sent as null or as an empty object. Read `billingStatus` for what the absence means. properties: displayString: description: >- Meta's own human-readable label for the funding instrument, e.g. 'Available Balance (EUR)' or a masked card. Meta composes this string; do not parse it. type: string id: description: >- Meta's ID for the funding instrument. Matches `fundingSource`. type: string type: description: >- Meta's raw numeric funding-source type, forwarded unchanged. Meta publishes no mapping from these numbers to payment-method kinds, so none is documented here and none should be inferred. type: integer type: object grantBalance: description: >- TikTok only. Grant (ad credit) part of `balance`, in whole units of `currency`. Absent when the connection has no finance role in the advertiser's Business Center. type: number id: description: Platform ad account ID (e.g. act_123) type: string minimumDailyBudget: description: >- Meta only. Minimum daily budget for the account, in the account currency's major units. This is the impressions-billed minimum; other billing events have higher minimums. Absent when the connected token cannot read it. type: number name: type: string selectable: description: >- Meta and X only. Whether the account can create/run ads now. Always present on every Meta and X account. Absent (treat as true) on other platforms. type: boolean selected: description: >- Always present. True when the ad account is in this connection's ad-account selection, or when the connection has no selection (then every ad account is usable). For a posting account (e.g. type: boolean status: description: >- LinkedIn only. LinkedIn's own ad account status. In practice always `ACTIVE`, because the LinkedIn query filters to active accounts. Meta, Google, TikTok and Pinterest report `accountStatus` instead; X reports `approvalStatus`. type: string timezone: description: >- Reddit only. The ad account's time zone as Reddit reports it (`time_zone_id`). Schedules on Reddit ads are read in this zone. type: string timezoneName: description: >- IANA timezone of the ad account (Meta only). Drives daily-budget reset and Insights day boundaries. type: string timezoneOffsetHoursUtc: description: >- Signed UTC offset in hours, reflecting current DST (Meta only). type: number type: description: >- Reddit only. Reddit's ad account type, forwarded unchanged. type: string unusableReason: description: >- Meta and X only. Always present on every Meta and X account. Human-readable reason when selectable is false; null when selectable. type: - string - 'null' type: object type: array cachedAt: description: >- Google only. When this list was fetched from Google. Null when it was never served from cache. Absent on other platforms. format: date-time type: - string - 'null' stale: description: >- Google only. True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read. Absent on other platforms. type: boolean type: object description: Ad accounts 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.