> ## 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 # Get follower stats > Accounts. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Without profileId or accountId it reads your default profile. Returns follower count history and growth metrics for connected accounts. Requires analytics add-on subscription. Follower counts are refreshed once per day. 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/social/accounts/follower-stats * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/social/accounts/follower-stats` * **accountIds:** query; optional * **profileId:** query; optional * **fromDate:** query; optional * **toDate:** query; optional * **granularity:** query; optional * **limit:** query; optional * **cursor:** query; optional * **Runtime facts:** 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/aisa-social.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "get_aisa_social_apis_v1_social_accounts_follower_stats", "method": "GET", "path": "/apis/v1/social/accounts/follower-stats", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "Your social accounts (acc_...). Comma-separated.", "in": "query", "name": "accountIds", "required": false, "schema": { "description": "Comma-separated.", "type": "string" } }, { "description": "One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent.", "in": "query", "name": "profileId", "required": false, "schema": { "pattern": "^prf_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Start date in YYYY-MM-DD format (defaults to 30 days ago)", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "End date in YYYY-MM-DD format (defaults to today)", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Data aggregation level", "in": "query", "name": "granularity", "required": false, "schema": { "default": "daily", "enum": [ "daily", "weekly", "monthly" ], "type": "string" } }, { "description": "Accounts per page, ordered by account id. Send it to page through accounts; the response then carries `pagination.nextCursor`. Without limit or cursor every matching account is returned.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response's `pagination.nextCursor`; returns the next page of `limit` accounts (25 when limit is omitted). A cursor we cannot parse returns 400.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "x-aisa-status": "enabled", "x-aisa-pricing": { "description": "Included with your connected social accounts: AIsa does not charge per call.", "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-social.json GET /apis/v1/social/accounts/follower-stats openapi: 3.1.0 info: description: '' title: AIsa Social 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: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:7f9742cb1ea233c648dcb290fdfbf24e53a27dcf900ec1386f83a8ef2e6b1bf9 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-social x-aisa-catalogs: aisa-social: title: AIsa Social description: '' x-aisa-document: facts_hash: 99acb5bddbedc8d3352e7c4fef86c3e6d8852c14772bcd18dbcf415237a642bd 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/social/accounts/follower-stats: get: summary: Get follower stats description: >- Accounts. Read only; needs social:read. Ids are yours: accounts acc_..., profiles prf_..., posts pst_...; every other object id is checked against your accounts before the call. Without profileId or accountId it reads your default profile. Returns follower count history and growth metrics for connected accounts. Requires analytics add-on subscription. Follower counts are refreshed once per day. 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_social_apis_v1_social_accounts_follower_stats parameters: - description: Your social accounts (acc_...). Comma-separated. in: query name: accountIds required: false schema: description: Comma-separated. type: string - description: >- One of your profiles (prf_...). Defaults to your default profile when neither profileId nor accountId is sent. in: query name: profileId required: false schema: pattern: ^prf_[0-9A-Za-z]{22}$ type: string - description: Start date in YYYY-MM-DD format (defaults to 30 days ago) in: query name: fromDate required: false schema: format: date type: string - description: End date in YYYY-MM-DD format (defaults to today) in: query name: toDate required: false schema: format: date type: string - description: Data aggregation level in: query name: granularity required: false schema: default: daily enum: - daily - weekly - monthly type: string - description: >- Accounts per page, ordered by account id. Send it to page through accounts; the response then carries `pagination.nextCursor`. Without limit or cursor every matching account is returned. in: query name: limit required: false schema: maximum: 25 minimum: 1 type: integer - description: >- Opaque cursor from a previous response's `pagination.nextCursor`; returns the next page of `limit` accounts (25 when limit is omitted). A cursor we cannot parse returns 400. in: query name: cursor required: false schema: type: string responses: '200': content: application/json: schema: properties: accounts: items: properties: _id: type: string accountStats: description: >- Platform-specific account stats from the latest daily snapshot. Fields vary by platform. Only present if metadata has been captured. properties: boardCount: description: Total boards (Pinterest) type: number followingCount: description: Number of accounts being followed type: number likesCount: description: Total likes received (TikTok) type: number listedCount: description: Lists the user appears on (X) type: number mediaCount: description: Total media posts (Instagram) type: number monthlyViews: description: Monthly profile views (Pinterest) type: number pinCount: description: Total pins (Pinterest) type: number postsCount: description: Total posts (Bluesky) type: number totalViews: description: Total channel views (YouTube) type: number tweetCount: description: Total tweets (X) type: number videoCount: description: Total videos (YouTube, TikTok) type: number type: object currentFollowers: description: Current follower count type: number dataPoints: description: Number of historical snapshots type: number displayName: type: string enabled: description: >- Whether the user explicitly activated this account. false means the account was created as a side effect (e.g., a posting account auto-created when the user connected ads first). - GET /apis/v1/social/accounts still returns such accounts unless `excludeHidden=true` is passed. - They cannot be posted to (`ACCOUNT_NOT_ENABLED_FOR_POSTING`) and are not billed as connected accounts. - On an ads account (`metaads`, `googleads`, ...) the value does not hide the connection: ads accounts are listed whatever their `enabled` value and keep working for ads. type: boolean followersCount: description: >- Follower count (only included if user has analytics add-on) type: number followersLastUpdated: description: >- Last time follower count was updated (only included if user has analytics add-on) format: date-time type: string growth: description: Follower change over period type: number growthPercentage: description: Percentage growth type: number isActive: type: boolean lastUpdated: format: date-time type: string metadata: description: >- Platform-specific metadata. Fields vary by platform. **WhatsApp accounts:** - qualityRating: phone number quality rating from Meta (GREEN, YELLOW, RED, or UNKNOWN). - nameStatus: display name review status (APPROVED, PENDING_REVIEW, DECLINED, or NONE). A declined or pending name does not by itself block sending; sendability is reported separately via health_status (can_send_message). - messagingLimitTier: maximum unique business-initiated conversations per 24h rolling window (TIER_250, TIER_1K, TIER_10K, TIER_100K, or TIER_UNLIMITED). Scales automatically as quality rating improves. - verifiedName: Meta-verified business display name. - displayPhoneNumber: formatted phone number (e.g., "+1 555-123-4567"). - wabaId: WhatsApp Business Account ID. - phoneNumberId: Meta phone number ID. **Meta ads business-login accounts:** - tokenType: system-user. - businessId: the owning Business Manager ID when there is one owner; null for multiple owners. - businessIds: owning Business Manager IDs discovered from granted ad accounts. - grantedAdAccountIds: ad-account IDs granted to the token. - adAccountBusinesses: map from ad-account ID to its owning business ID or null. - availablePages: granted Page IDs and names. No Page tokens are exposed. - selectedPageId: the Page selected for creatives and lead forms, or null. - scopedAdAccountIds: existing sync scope preserved on reconnect. Non-expiring tokens have no tokenExpiresAt field. Parent posting reconnects do not replace this token. **LinkedIn accounts:** profileData carries profile details refreshed on each daily snapshot. - profileData.bio: the member's headline (personal accounts) or the organization description (organization accounts). null when not set. - profileData.extraData.vanityName: the member's profile slug, the /in/{vanityName} segment of profileUrl. Personal accounts only; an organization's slug is in metadata.organizationInfo.vanityName. **Instagram accounts:** - loginMethod: "facebook_login" when connected through Facebook Login; absent for Instagram Login. On facebook_login accounts, comment reads leave hidden comments out entirely instead of returning them with isHidden true. - instagramScopedId: the Instagram professional account id (`17841...`). On Instagram Login accounts it is the same whichever app connected the account, while platformUserId is app-scoped. Facebook Login accounts hold this id as platformUserId. **X (Twitter) accounts:** - profileData.extraData.isPremium: whether X reports a paid subscription (Basic, Premium, Premium+, or a blue verified badge), which raises the post length limit from 280 to 25,000 characters. Read live at connect and reconnect, refreshed by the daily follower snapshot. - Because X intermittently reports no subscription for subscribed accounts, a cancellation is stored on the fourth consecutive daily snapshot reporting it (about four days). Accounts connected before the extraData layout carry the flag at profileData.isPremium. type: object needsReconnection: description: >- The platform definitively reported the stored OAuth token as dead. While true, GET /apis/v1/social/connect/{platform}/ads returns a fresh authUrl (implicit force=true) instead of alreadyConnected, so re-running the connect flow recovers the account. Cleared automatically when the account is re-authorized. type: boolean parentAccountId: description: >- Reference to the parent posting social account. Set for ads accounts that share or derive from a posting account's OAuth token. null for standalone ads (Google Ads) and all posting accounts. Meta ads business-login accounts also have no parent. type: - string - 'null' platform: enum: - tiktok - instagram - facebook - youtube - linkedin - twitter - threads - pinterest - reddit - bluesky - googlebusiness - telegram - snapchat - discord - slack - whatsapp - shopify - wordpress - wix - linkedinads - metaads - pinterestads - tiktokads - xads - googleads - openaiads - redditads - sms - phone - rcs - whopads - google - microsoft - hubspot - webflow - googleanalytics - imessage - tiktokshop - microsoftads type: string platformUserId: description: >- The account's id on its platform, as the platform reports it to AIsa. Stable across reconnects, so use it to match an account against your own records. - **Instagram Login accounts:** the app-scoped user id (the professional account id is in `metadata.instagramScopedId`). - **Instagram via Facebook Login:** the professional account id (`17841...`). - **TikTok:** the open_id of AIsa's TikTok app, which differs from the open_id any other app sees for the same user. Either value can be passed back as `expectedPlatformUserId` on GET /apis/v1/social/connect/{platform}. type: string profileId: description: One of your profiles (prf_...). pattern: ^prf_[0-9A-Za-z]{22}$ type: string profilePicture: description: >- URL to the account's profile picture on the platform. May be null if the platform does not provide one. type: - string - 'null' profileUrl: description: >- Full profile URL for the connected account on its platform. type: string rateLimitedUntil: description: >- End of the account's publishing cooldown. Compare it with the current time: a value in the past means the cooldown has ended (the field is cleared on the next successful publish); null means no cooldown since the last successful publish. **When it starts.** A post to the account fails with `errorCategory` `user_abuse` (spam, abuse or rate-limit errors), or 10 or more posts to it fail within an hour with `user_content`, `platform_error`, `platform_rate_limit` or `unknown`. **How long.** It doubles with each start inside a 24-hour window that opens at the first one (10, 20, 40, 80 minutes and so on, capped at 24 hours). On a YouTube account with a recorded successful upload, it instead runs until 24 hours after that upload, or 1 hour when that upload is older than 24 hours. **Effect.** While it is in the future, POST /apis/v1/social/posts (drafts excepted) and POST /apis/v1/social/posts/{postId}/retry return 429 for this account. When it starts, this account's pending targets on posts scheduled before the cooldown ends are failed. format: date-time type: - string - 'null' scopeAreas: description: >- Accounts connected through your own OAuth app: the permission areas the connect requested. Null on accounts connected through AIsa's app. items: type: string type: - array - 'null' tiktokAccountType: description: >- TikTok accounts only. The account type TikTok reported when the account was connected. - `personal`: cannot use TikTok direct messages through the API (TikTok limits Business Messaging to Business Accounts). Skip the inbox for them and tell the user to switch to a Business Account in the TikTok app, then reconnect. - `business`: the prerequisite, not a guarantee. Messaging also needs the messaging scopes granted and TikTok's regional availability. - `unknown`: accounts connected before this was captured, or whose grant left out the account-type scope. enum: - business - personal - unknown type: string username: type: string required: - _id - isActive - platform - profileId type: object type: array dateRange: properties: from: format: date-time type: string to: format: date-time type: string type: object granularity: type: string pagination: properties: limit: type: integer nextCursor: description: >- Opaque cursor for the next page; pass it back as `cursor`. Null on the last page. type: - string - 'null' required: - limit - nextCursor type: object stats: additionalProperties: items: properties: date: format: date type: string followers: type: number type: object type: array type: object type: object description: Follower stats 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: enum: - never - after_delay - after_reconnect - reconcile_first - null 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.