> ## 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 post analytics > Analytics. 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 analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats. - Accepts both AIsa Post IDs and External Post IDs (auto-resolved). - fromDate defaults to 90 days ago if omitted, max range 366 days. - Single post lookups may return 202 (sync pending) or 424 (all platforms failed). - For follower stats, use /apis/v1/social/accounts/follower-stats. ### LinkedIn personal accounts Analytics are only available for posts published through AIsa. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts. ### Facebook Page stories Stories on a connected Page, published through AIsa or natively, are collected while they are live and returned like any other post (platformPostUrl points to the story). Metrics for a story published through AIsa are available on its AIsa post ID. Their lifetime metrics refresh about hourly, with a final reading shortly before the story expires at 24 hours. After that the values stay at that last reading. Mapping: - impressions = story media views (Meta stopped accepting per-story impressions in October 2026, so impressions equals views) - reach = unique story media viewers - views = story media views - likes = story reactions - comments = story replies - shares = story shares - clicks: always 0, because Meta exposes no link-click metric for stories 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/analytics/posts * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/social/analytics/posts` * **postId:** query; optional * **platform:** query; optional * **profileId:** query; optional * **accountId:** query; optional * **source:** query; optional * **fromDate:** query; optional * **toDate:** query; optional * **limit:** query; optional * **page:** query; optional * **sortBy:** query; optional * **order:** query; optional * **tags:** 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_analytics_posts", "method": "GET", "path": "/apis/v1/social/analytics/posts", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [ { "description": "Returns analytics for a single post. Accepts AIsa Post IDs, External Post IDs and the platform's native post ID. AIsa IDs are auto-resolved to External Post analytics.", "in": "query", "name": "postId", "required": false, "schema": { "type": "string" } }, { "description": "Filter by platform (default \"all\")", "in": "query", "name": "platform", "required": false, "schema": { "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": "One of your social accounts (acc_...).", "in": "query", "name": "accountId", "required": false, "schema": { "pattern": "^acc_[0-9A-Za-z]{22}$", "type": "string" } }, { "description": "Filter by post source: late (posted via AIsa API), external (synced from platform), all (default)", "in": "query", "name": "source", "required": false, "schema": { "default": "all", "enum": [ "all", "late", "external" ], "type": "string" } }, { "description": "Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days.", "in": "query", "name": "fromDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted.", "in": "query", "name": "toDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Page size (default 50)", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Page number (default 1)", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Sort by date, engagement, or a specific metric. Platform-specific metrics (follows, reposts, reels_skip_rate, ig_reels_*, completion_rate, profile_views, website_clicks) sort a null value as 0.", "in": "query", "name": "sortBy", "required": false, "schema": { "default": "date", "enum": [ "date", "engagement", "impressions", "reach", "likes", "comments", "shares", "saves", "clicks", "views", "follows", "ig_reels_avg_watch_time", "ig_reels_video_view_total_time", "reposts", "reels_skip_rate", "completion_rate", "profile_views", "website_clicks" ], "type": "string" } }, { "description": "Sort order", "in": "query", "name": "order", "required": false, "schema": { "default": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Comma-separated tags (at most 20). Lists only posts created through AIsa that carry every listed tag, matched exactly and case-sensitively. Up to 200 published posts can match within the date range; more returns 400 asking to narrow fromDate and toDate. Ignored when postId is set.", "in": "query", "name": "tags", "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/analytics/posts 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/analytics/posts: get: summary: Get post analytics description: >- Analytics. 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 analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats. - Accepts both AIsa Post IDs and External Post IDs (auto-resolved). - fromDate defaults to 90 days ago if omitted, max range 366 days. - Single post lookups may return 202 (sync pending) or 424 (all platforms failed). - For follower stats, use /apis/v1/social/accounts/follower-stats. ### LinkedIn personal accounts Analytics are only available for posts published through AIsa. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts. ### Facebook Page stories Stories on a connected Page, published through AIsa or natively, are collected while they are live and returned like any other post (platformPostUrl points to the story). Metrics for a story published through AIsa are available on its AIsa post ID. Their lifetime metrics refresh about hourly, with a final reading shortly before the story expires at 24 hours. After that the values stay at that last reading. Mapping: - impressions = story media views (Meta stopped accepting per-story impressions in October 2026, so impressions equals views) - reach = unique story media viewers - views = story media views - likes = story reactions - comments = story replies - shares = story shares - clicks: always 0, because Meta exposes no link-click metric for stories 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_analytics_posts parameters: - description: >- Returns analytics for a single post. Accepts AIsa Post IDs, External Post IDs and the platform's native post ID. AIsa IDs are auto-resolved to External Post analytics. in: query name: postId required: false schema: type: string - description: Filter by platform (default "all") in: query name: platform required: false schema: 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: One of your social accounts (acc_...). in: query name: accountId required: false schema: pattern: ^acc_[0-9A-Za-z]{22}$ type: string - description: >- Filter by post source: late (posted via AIsa API), external (synced from platform), all (default) in: query name: source required: false schema: default: all enum: - all - late - external type: string - description: >- Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days. in: query name: fromDate required: false schema: format: date type: string - description: Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted. in: query name: toDate required: false schema: format: date type: string - description: Page size (default 50) in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer - description: Page number (default 1) in: query name: page required: false schema: default: 1 minimum: 1 type: integer - description: >- Sort by date, engagement, or a specific metric. Platform-specific metrics (follows, reposts, reels_skip_rate, ig_reels_*, completion_rate, profile_views, website_clicks) sort a null value as 0. in: query name: sortBy required: false schema: default: date enum: - date - engagement - impressions - reach - likes - comments - shares - saves - clicks - views - follows - ig_reels_avg_watch_time - ig_reels_video_view_total_time - reposts - reels_skip_rate - completion_rate - profile_views - website_clicks type: string - description: Sort order in: query name: order required: false schema: default: desc enum: - asc - desc type: string - description: >- Comma-separated tags (at most 20). Lists only posts created through AIsa that carry every listed tag, matched exactly and case-sensitively. Up to 200 published posts can match within the date range; more returns 400 asking to narrow fromDate and toDate. Ignored when postId is set. in: query name: tags required: false schema: type: string responses: '200': content: application/json: schema: oneOf: - properties: analytics: properties: audienceCountries: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days. At most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1. Empty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources. type: object audienceTypes: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h). - Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other. - Empty object when TikTok reports nothing, and for other platforms. - Views-weighted across accounts, like impressionSources. type: object clicks: description: >- Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories. type: integer comments: type: integer completionRate: description: >- Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app. - Delayed T+24-48h, and only for posts active in the last 7 days. - 0 for other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number engagementRate: description: >- Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. On the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator. The engagementRate on the LinkedIn account endpoints uses a different formula. type: number follows: description: >- Accounts that started following from this post. - Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane. - Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media. - 0 for other platforms. type: - integer - 'null' igReelsAvgWatchTime: description: >- Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos. type: integer igReelsVideoViewTotalTime: description: >- Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos. type: integer impressionSources: additionalProperties: type: number description: >- Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days). - Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name. - Empty object when TikTok reports nothing, and for other platforms. - When a post is published to several accounts, each share is weighted by views. type: object impressions: type: integer lastUpdated: format: date-time type: string likes: type: integer profileViews: description: >- Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms. type: integer reach: type: integer reelsSkipRate: description: >- Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta. - Meta labels the metric estimated and in development, so it can move between syncs. - 0 for non-Reels media and other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number replays: description: >- Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms. type: integer reposts: description: >- Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only. - Instagram Login accounts: always 0 (Meta does not expose this metric for them). - Other platforms: 0, including Threads, where reposts are counted in shares instead. type: integer retentionCurve: additionalProperties: type: number description: >- Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play ("3" is the share still watching at 3 s). Empty object for other media and platforms. - Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays. - Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys "0" to "12"). Meta returns at most 41 points, so a long Reel covers only its first 40 s. - TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s. On a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve. type: object saves: description: >- Number of saves/bookmarks (Instagram, Pinterest, X) type: integer shares: type: integer videoDurationSeconds: description: >- Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio). - YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload. - Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention. type: - integer - 'null' views: type: integer websiteClicks: description: >- TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms. type: integer type: object content: type: string isAiGenerated: description: >- Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it. type: boolean isExternal: type: boolean isSharedToFeed: description: >- Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it. type: boolean latePostId: description: Original AIsa post ID if scheduled via AIsa type: - string - 'null' mediaAudioType: description: >- Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it. type: string mediaItems: description: >- All media items for this post. Carousel posts have one entry per slide. - Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring). - Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse. items: properties: altText: description: >- Accessibility alt text set on the media, when present. type: string mediaStatus: description: >- unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field). enum: - available - unavailable type: string thumbnail: description: >- Thumbnail URL (same as url for images). Still present when url is null. format: uri type: - string - 'null' type: enum: - image - video type: string unavailableReason: description: >- Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help. enum: - platform_withheld type: string url: description: >- 'Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading. Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause), so type stays "video" while the file is permanently unreachable.' format: uri type: - string - 'null' type: object type: array mediaProductType: description: >- Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it. type: string mediaType: enum: - image - video - carousel - text type: - string - 'null' message: description: >- Human-readable status message for pending, partial, or failed states type: - string - 'null' platform: type: string platformAnalytics: items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string accountUsername: type: - string - 'null' analytics: anyOf: - properties: audienceCountries: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days. At most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1. Empty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources. type: object audienceTypes: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h). - Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other. - Empty object when TikTok reports nothing, and for other platforms. - Views-weighted across accounts, like impressionSources. type: object clicks: description: >- Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories. type: integer comments: type: integer completionRate: description: >- Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app. - Delayed T+24-48h, and only for posts active in the last 7 days. - 0 for other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number engagementRate: description: >- Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. On the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator. The engagementRate on the LinkedIn account endpoints uses a different formula. type: number follows: description: >- Accounts that started following from this post. - Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane. - Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media. - 0 for other platforms. type: - integer - 'null' igReelsAvgWatchTime: description: >- Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos. type: integer igReelsVideoViewTotalTime: description: >- Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos. type: integer impressionSources: additionalProperties: type: number description: >- Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days). - Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name. - Empty object when TikTok reports nothing, and for other platforms. - When a post is published to several accounts, each share is weighted by views. type: object impressions: type: integer lastUpdated: format: date-time type: string likes: type: integer profileViews: description: >- Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms. type: integer reach: type: integer reelsSkipRate: description: >- Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta. - Meta labels the metric estimated and in development, so it can move between syncs. - 0 for non-Reels media and other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number replays: description: >- Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms. type: integer reposts: description: >- Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only. - Instagram Login accounts: always 0 (Meta does not expose this metric for them). - Other platforms: 0, including Threads, where reposts are counted in shares instead. type: integer retentionCurve: additionalProperties: type: number description: >- Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play ("3" is the share still watching at 3 s). Empty object for other media and platforms. - Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays. - Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys "0" to "12"). Meta returns at most 41 points, so a long Reel covers only its first 40 s. - TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s. On a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve. type: object saves: description: >- Number of saves/bookmarks (Instagram, Pinterest, X) type: integer shares: type: integer videoDurationSeconds: description: >- Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio). - YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload. - Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention. type: - integer - 'null' views: type: integer websiteClicks: description: >- TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms. type: integer type: object - type: 'null' errorCode: description: >- Stable machine-readable reason for errorMessage. New values may be added. - post_not_found: the post was deleted or is no longer visible to the account. - not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token. - permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only). - null: no stable code; read errorMessage. enum: - post_not_found - not_post_owner - permission_missing - null type: - string - 'null' errorMessage: description: >- Failure detail: - Failed entries: why the post failed to publish. - Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id). - Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync. type: - string - 'null' isOwner: description: >- Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms. type: - boolean - 'null' platform: type: string platformPostId: description: >- The native post ID on the platform (e.g. Instagram media ID, tweet ID) type: - string - 'null' platformPostUrl: format: uri type: - string - 'null' status: enum: - published - failed type: string syncStatus: description: Sync state of analytics for this platform enum: - synced - pending - unavailable type: string type: object type: array platformPostUrl: format: uri type: - string - 'null' postId: type: string publishedAt: format: date-time type: - string - 'null' scheduledFor: format: date-time type: string status: description: >- Overall post status. "partial" when some platforms published and others failed. While any platform is still pending or processing, the post's own status is returned instead (usually scheduled or publishing), even if another platform already published. A post with no published or failed platform (for example every platform cancelled) returns its own status with syncStatus unavailable and no platformAnalytics. enum: - published - failed - partial - scheduled - publishing - draft - cancelled type: string syncStatus: description: Overall sync state across all platforms enum: - synced - pending - partial - unavailable type: string thumbnailUrl: description: >- Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached. format: uri type: - string - 'null' type: object - properties: accounts: description: >- Connected accounts (followerCount and followersLastUpdated only included if user has analytics add-on) items: properties: _id: type: string 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 isActive: type: boolean 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 hasAnalyticsAccess: description: Whether user has analytics add-on access type: boolean overview: properties: dataStaleness: properties: staleAccountCount: description: Number of accounts with stale analytics data type: integer syncTriggered: description: >- Whether a background sync was triggered for stale accounts type: boolean type: object lastSync: format: date-time type: - string - 'null' publishedPosts: type: integer scheduledPosts: type: integer totalPosts: type: integer type: object pagination: properties: limit: type: integer page: type: integer pages: type: integer total: type: integer type: object posts: items: properties: _id: type: string analytics: properties: audienceCountries: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days. At most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1. Empty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources. type: object audienceTypes: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h). - Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other. - Empty object when TikTok reports nothing, and for other platforms. - Views-weighted across accounts, like impressionSources. type: object clicks: description: >- Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories. type: integer comments: type: integer completionRate: description: >- Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app. - Delayed T+24-48h, and only for posts active in the last 7 days. - 0 for other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number engagementRate: description: >- Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. On the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator. The engagementRate on the LinkedIn account endpoints uses a different formula. type: number follows: description: >- Accounts that started following from this post. - Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane. - Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media. - 0 for other platforms. type: - integer - 'null' igReelsAvgWatchTime: description: >- Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos. type: integer igReelsVideoViewTotalTime: description: >- Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos. type: integer impressionSources: additionalProperties: type: number description: >- Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days). - Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name. - Empty object when TikTok reports nothing, and for other platforms. - When a post is published to several accounts, each share is weighted by views. type: object impressions: type: integer lastUpdated: format: date-time type: string likes: type: integer profileViews: description: >- Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms. type: integer reach: type: integer reelsSkipRate: description: >- Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta. - Meta labels the metric estimated and in development, so it can move between syncs. - 0 for non-Reels media and other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number replays: description: >- Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms. type: integer reposts: description: >- Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only. - Instagram Login accounts: always 0 (Meta does not expose this metric for them). - Other platforms: 0, including Threads, where reposts are counted in shares instead. type: integer retentionCurve: additionalProperties: type: number description: >- Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play ("3" is the share still watching at 3 s). Empty object for other media and platforms. - Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays. - Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys "0" to "12"). Meta returns at most 41 points, so a long Reel covers only its first 40 s. - TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s. On a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve. type: object saves: description: >- Number of saves/bookmarks (Instagram, Pinterest, X) type: integer shares: type: integer videoDurationSeconds: description: >- Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio). - YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload. - Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention. type: - integer - 'null' views: type: integer websiteClicks: description: >- TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms. type: integer type: object content: type: string isAd: description: >- True when this post's metrics include paid delivery, so organic reporting should exclude it. Set for LinkedIn dark posts and for TikTok posts one of your TikTok ads promotes (Spark / boosted). TikTok exposes no ad flag of its own. A video created by an uploaded-asset (non-Spark) TikTok ad is posted to the profile with a fresh organic id and cannot be detected, so those still report false. type: boolean isAiGenerated: description: >- Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it. type: boolean isExternal: type: boolean isSharedToFeed: description: >- Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it. type: boolean latePostId: description: Original AIsa post ID if scheduled via AIsa type: - string - 'null' mediaAudioType: description: >- Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it. type: string mediaItems: description: >- All media items for this post. Carousel posts contain one entry per slide. - Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring). - Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse. items: properties: altText: description: >- Accessibility alt text set on the media, when present. type: string thumbnail: description: Thumbnail URL (same as url for images) format: uri type: string type: enum: - image - video type: string url: description: Direct URL to the media format: uri type: string type: object type: array mediaProductType: description: >- Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it. type: string mediaType: enum: - image - video - gif - document - carousel - text type: string platform: type: string platformPostUrl: format: uri type: string platforms: items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string accountUsername: type: - string - 'null' analytics: anyOf: - properties: audienceCountries: type: object audienceTypes: type: object clicks: type: integer comments: type: integer completionRate: type: number engagementRate: type: number follows: type: object igReelsAvgWatchTime: type: integer igReelsVideoViewTotalTime: type: integer impressionSources: type: object impressions: type: integer lastUpdated: type: string likes: type: integer profileViews: type: integer reach: type: integer reelsSkipRate: type: number replays: type: integer reposts: type: integer retentionCurve: type: object saves: type: integer shares: type: integer videoDurationSeconds: type: object views: type: integer websiteClicks: type: integer type: object - type: 'null' errorCode: description: >- Stable machine-readable reason for errorMessage. New values may be added. - post_not_found: the post was deleted or is no longer visible to the account. - not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token. - permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only). - null: no stable code; read errorMessage. enum: - post_not_found - not_post_owner - permission_missing - null type: - string - 'null' errorMessage: description: >- Failure detail: - Failed entries: why the post failed to publish. - Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id). - Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync. type: - string - 'null' isOwner: description: >- Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms. type: - boolean - 'null' platform: type: string platformPostId: description: >- The native post ID on the platform (e.g. Instagram media ID, tweet ID) type: - string - 'null' platformPostUrl: format: uri type: - string - 'null' status: enum: - published - failed type: string syncStatus: description: Sync state of analytics for this platform enum: - synced - pending - unavailable type: string type: object type: array profileId: type: - string - 'null' publishedAt: format: date-time type: string scheduledFor: format: date-time type: string status: type: string thumbnailUrl: description: >- Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached. format: uri type: string type: object type: array type: object description: Analytics result '202': content: application/json: schema: properties: analytics: properties: audienceCountries: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days. At most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1. Empty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources. type: object audienceTypes: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h). - Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other. - Empty object when TikTok reports nothing, and for other platforms. - Views-weighted across accounts, like impressionSources. type: object clicks: description: >- Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories. type: integer comments: type: integer completionRate: description: >- Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app. - Delayed T+24-48h, and only for posts active in the last 7 days. - 0 for other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number engagementRate: description: >- Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. On the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator. The engagementRate on the LinkedIn account endpoints uses a different formula. type: number follows: description: >- Accounts that started following from this post. - Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane. - Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media. - 0 for other platforms. type: - integer - 'null' igReelsAvgWatchTime: description: >- Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos. type: integer igReelsVideoViewTotalTime: description: >- Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos. type: integer impressionSources: additionalProperties: type: number description: >- Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days). - Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name. - Empty object when TikTok reports nothing, and for other platforms. - When a post is published to several accounts, each share is weighted by views. type: object impressions: type: integer lastUpdated: format: date-time type: string likes: type: integer profileViews: description: >- Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms. type: integer reach: type: integer reelsSkipRate: description: >- Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta. - Meta labels the metric estimated and in development, so it can move between syncs. - 0 for non-Reels media and other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number replays: description: >- Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms. type: integer reposts: description: >- Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only. - Instagram Login accounts: always 0 (Meta does not expose this metric for them). - Other platforms: 0, including Threads, where reposts are counted in shares instead. type: integer retentionCurve: additionalProperties: type: number description: >- Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play ("3" is the share still watching at 3 s). Empty object for other media and platforms. - Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays. - Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys "0" to "12"). Meta returns at most 41 points, so a long Reel covers only its first 40 s. - TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s. On a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve. type: object saves: description: Number of saves/bookmarks (Instagram, Pinterest, X) type: integer shares: type: integer videoDurationSeconds: description: >- Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio). - YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload. - Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention. type: - integer - 'null' views: type: integer websiteClicks: description: >- TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms. type: integer type: object content: type: string isAiGenerated: description: >- Instagram only: whether Instagram labeled the media as AI-generated. Absent when the platform did not report it. type: boolean isExternal: type: boolean isSharedToFeed: description: >- Instagram reels only: whether the reel is also shared to the main feed. Absent when the platform did not report it. type: boolean latePostId: description: Original AIsa post ID if scheduled via AIsa type: - string - 'null' mediaAudioType: description: >- Instagram only: audio type of the media (MUSIC or ORIGINAL_SOUND). Absent when the platform did not report it. type: string mediaItems: description: >- All media items for this post. Carousel posts have one entry per slide. - Facebook and Instagram images and video covers whose Meta CDN links expired are re-read and served from AIsa storage (non-expiring). - Facebook and Instagram video file URLs, and LinkedIn media URLs, stay the platform's signed links and are refreshed on read once they lapse. items: properties: altText: description: >- Accessibility alt text set on the media, when present. type: string mediaStatus: description: >- unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field). enum: - available - unavailable type: string thumbnail: description: >- Thumbnail URL (same as url for images). Still present when url is null. format: uri type: - string - 'null' type: enum: - image - video type: string unavailableReason: description: >- Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help. enum: - platform_withheld type: string url: description: >- 'Direct URL to the media file. Null when the platform withholds it: check mediaStatus before downloading. Instagram omits the video file for Reels it flags as containing copyrighted material (its docs name audio as the usual cause), so type stays "video" while the file is permanently unreachable.' format: uri type: - string - 'null' type: object type: array mediaProductType: description: >- Instagram only: the platform media product type (e.g. FEED, REELS, STORY, AD). Absent when the platform did not report it. type: string mediaType: enum: - image - video - carousel - text type: - string - 'null' message: description: >- Human-readable status message for pending, partial, or failed states type: - string - 'null' platform: type: string platformAnalytics: items: properties: accountId: description: One of your social accounts (acc_...). pattern: ^acc_[0-9A-Za-z]{22}$ type: string accountUsername: type: - string - 'null' analytics: anyOf: - properties: audienceCountries: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: share of views by viewer country, as fractions 0 to 1, keyed by upper-case ISO-3166 alpha-2 code. Available T+24-48h, only for posts active in the last 7 days. At most 20 country keys plus `other`. The catch-all bucket TikTok sends, any country below 0.001 and anything past the twentieth all sum into `other`, so the values still add up to 1. Empty object when TikTok reports nothing, and for other platforms. Views-weighted across accounts like impressionSources. type: object audienceTypes: additionalProperties: type: number description: >- TikTok accounts connected through the TikTok for Business app only: two viewer splits as fractions 0 to 1 (T+24-48h). - Each pair sums to 1 when present: `follower` + `nonFollower`, and `newViewer` + `returnViewer`. TikTok can report one pair without the other. - Empty object when TikTok reports nothing, and for other platforms. - Views-weighted across accounts, like impressionSources. type: object clicks: description: >- Link clicks where the platform reports them. Always 0 on Facebook Page stories: Meta exposes no link-click metric for stories. type: integer comments: type: integer completionRate: description: >- Share of viewers who watched the video to the end, 0 to 1, as TikTok reports it. Only for TikTok accounts connected through the TikTok for Business app. - Delayed T+24-48h, and only for posts active in the last 7 days. - 0 for other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number engagementRate: description: >- Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so the basis varies by post: impressions if present, else reach, else views. For a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. On the post-level roll-up of a cross-posted post, the denominator is the SUM of the denominators resolved per platform entry. An entry reporting none of impressions, reach or views is excluded from both sides of the ratio. Each platformAnalytics entry below keeps its own single denominator. The engagementRate on the LinkedIn account endpoints uses a different formula. type: number follows: description: >- Accounts that started following from this post. - Reported for Instagram feed posts and stories (organic follows), Facebook Reels (Meta post_video_followers) and the TikTok business lane. - Null on Instagram Reels and non-Reels video, and on Facebook posts that are not Reels, where Meta does not expose this metric for the media. - 0 for other platforms. type: - integer - 'null' igReelsAvgWatchTime: description: >- Average watch time per play, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). On Facebook it includes replays within a play, so it can exceed the Reel length. 0 for other media and platforms, including regular Facebook videos. type: integer igReelsVideoViewTotalTime: description: >- Total watch time including replays, in milliseconds, for Instagram Reels, Facebook Reels and TikTok videos (business accounts). 0 for other media and platforms, including regular Facebook videos. type: integer impressionSources: additionalProperties: type: number description: >- Share of views by surface, as fractions 0 to 1. Only for TikTok accounts connected through the TikTok for Business app (T+24-48h, only for posts active in the last 7 days). - Keys: `forYou`, `follow`, `search`, `personalProfile`, `sound`, `directMessage`, `other`. A surface TikTok adds later appears under a camelCase key derived from its name. - Empty object when TikTok reports nothing, and for other platforms. - When a post is published to several accounts, each share is weighted by views. type: object impressions: type: integer lastUpdated: format: date-time type: string likes: type: integer profileViews: description: >- Instagram feed posts (images and carousels; 0 on Reels and Stories) and TikTok accounts connected through the TikTok for Business app: profile views from users who reached the profile through this post (TikTok T+24-48h). 0 for other platforms. type: integer reach: type: integer reelsSkipRate: description: >- Instagram Reels only: percentage (0-100) of initial views that skipped the reel within its first 3 seconds, as reported by Meta. - Meta labels the metric estimated and in development, so it can move between syncs. - 0 for non-Reels media and other platforms. - For a post published to several accounts, the aggregate is weighted by views. type: number replays: description: >- Facebook Reels only: plays that were replays (Meta fb_reels_replay_count). Summed across accounts. 0 for other media and platforms. type: integer reposts: description: >- Reposts of the media by other users, minus deleted reposts, on feed posts, reels and stories. Instagram accounts connected with Facebook Login only. - Instagram Login accounts: always 0 (Meta does not expose this metric for them). - Other platforms: 0, including Threads, where reposts are counted in shares instead. type: integer retentionCurve: additionalProperties: type: number description: >- Facebook Reels and TikTok business lane: share of viewers still watching at each second of playback, as fractions 0 to 1. Keys are whole seconds from the start of a play ("3" is the share still watching at 3 s). Empty object for other media and platforms. - Facebook Reels (Meta post_video_retention_graph): the base is a subset of plays that Meta selects and does not expose. On small Reels it can be far below views (6 of 51 measured), so a value is a share of that subset, not of all plays. - Facebook Reels length: loops count as continued playback, so a short Reel's curve runs past its length (an 8 s Reel has keys "0" to "12"). Meta returns at most 41 points, so a long Reel covers only its first 40 s. - TikTok accounts connected through the TikTok for Business app (TikTok video_view_retention): one point per whole second, at most 61 points, thinned evenly on videos longer than 60 s. On a cross-posted post this is the curve of the account with the most views among those reporting one, never a blend: curves from different platforms and accounts measure different audiences and different seconds. Each platformAnalytics entry keeps its own curve. type: object saves: description: >- Number of saves/bookmarks (Instagram, Pinterest, X) type: integer shares: type: integer videoDurationSeconds: description: >- Video length in seconds. Null when unknown: platforms that do not report a length, non-video media, or when Instagram does not expose the media URL (e.g. reels with copyrighted audio). - YouTube: filled for public videos once their analytics next refresh (from the Data API; live streams may report null). The Data API has no Shorts flag: a video over 180 seconds cannot be a Short, but a shorter one may be a regular upload. - Instagram Reels: also filled. Combine with igReelsAvgWatchTime (ms) to estimate retention. type: - integer - 'null' views: type: integer websiteClicks: description: >- TikTok accounts connected through the TikTok for Business app only: clicks on the profile website link attributed to this post (T+24-48h). Also counted inside `clicks`, which sums every profile-link type (website, phone, email, address, app download). 0 for other platforms. type: integer type: object - type: 'null' errorCode: description: >- Stable machine-readable reason for errorMessage. New values may be added. - post_not_found: the post was deleted or is no longer visible to the account. - not_post_owner: the post is owned by another Page or user (collab or visitor post); its analytics cannot be read with this Page's token. - permission_missing: the last analytics sync of the Facebook account failed because the Page no longer grants pages_read_engagement (pending entries only). - null: no stable code; read errorMessage. enum: - post_not_found - not_post_owner - permission_missing - null type: - string - 'null' errorMessage: description: >- Failure detail: - Failed entries: why the post failed to publish. - Unavailable entries: why analytics cannot be synced (e.g. Google Business Profile, a TikTok upload that never received a video id). - Pending entries: the most recent analytics sync error for the account (null while no sync has failed), cleared after the next successful sync. type: - string - 'null' isOwner: description: >- Facebook only: true when the connected Page authored the post, false when Facebook reports another author (a collab post), null when unknown or for other platforms. type: - boolean - 'null' platform: type: string platformPostId: description: >- The native post ID on the platform (e.g. Instagram media ID, tweet ID) type: - string - 'null' platformPostUrl: format: uri type: - string - 'null' status: enum: - published - failed type: string syncStatus: description: Sync state of analytics for this platform enum: - synced - pending - unavailable type: string type: object type: array platformPostUrl: format: uri type: - string - 'null' postId: type: string publishedAt: format: date-time type: - string - 'null' scheduledFor: format: date-time type: string status: description: >- Overall post status. "partial" when some platforms published and others failed. While any platform is still pending or processing, the post's own status is returned instead (usually scheduled or publishing), even if another platform already published. A post with no published or failed platform (for example every platform cancelled) returns its own status with syncStatus unavailable and no platformAnalytics. enum: - published - failed - partial - scheduled - publishing - draft - cancelled type: string syncStatus: description: Overall sync state across all platforms enum: - synced - pending - partial - unavailable type: string thumbnailUrl: description: >- Cover image URL. Facebook, Instagram and TikTok covers whose platform CDN link expired are re-read from the platform and served from AIsa storage, so that URL does not expire and can be cached. format: uri type: - string - 'null' type: object description: > Analytics are being synced from the platform, or (single post lookup only) the post has not finished publishing on every platform yet. The body matches AnalyticsSinglePostResponse with syncStatus "pending" and a message. - While a platform has not published, status is the post's own status (for example scheduled or publishing). - A post with one failed platform returns 202 rather than 424 until the others finish. - Pending platforms whose account failed its last analytics sync carry that error in platformAnalytics[].errorMessage, and the message says so. 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.