跳转到主要内容
POST
取得使用者社群檔案的分析與人口統計,例如曝光、觀看與粉絲數。 目前支援 Bluesky、Facebook Pages、Google My Business、Instagram、LinkedIn、Pinterest、Reddit、Snapchat、Threads、TikTok、X/Twitter 與 YouTube。
Facebook:Meta 已於 2026 年 6 月 15 日淘汰部分觸及與影片指標。 Meta 移除了所有 Graph API 版本的 unique impression 與 3 秒影片觀看(unique)的 Insights 指標,因此 Facebook 的 analytics 物件不再回傳 pagePostsImpressions* 系列(pagePostsImpressionspagePostsImpressionsPaidpagePostsImpressionsUniquepagePostsImpressionsOrganicUniquepagePostsImpressionsViral*pagePostsImpressionsNonviral*pagePostsServedImpressionsOrganicUnique),亦不再回傳 pageVideoViewsUnique。請改用 pageMediaView 作為觸及指標(Total Unique Media Views 的後續替代方案已在規劃中)。pagePostEngagementspageVideoViewspageVideoViewsPaid 不受影響。參考:即將發生的 API 變更 — 2026 年 6 月 15 日
  • Facebook Page 分析(例如人口統計)僅適用於獲得 100 個以上讚的 Page。Facebook 通常每 24 小時更新一次其指標。
  • Instagram 可能需要最多 48 小時才會計算完分析資料。粉絲數少於 100 的帳號無法取得粉絲分析。人口統計指標僅回傳前 45 名,且僅使用我們具有人口統計資料的觀眾來計算人口統計指標;若 Instagram 使用者在過去 30 天內互動少於 100 次,則不會回傳人口統計資料。
  • 在取得 Instagram 社群分析時,特定指標的人口統計資訊可能不會出現在回應中。當每個分類的人數超過 100 人時,人口統計資訊才會出現。詳情請參閱 Instagram Analytics Demographics Warning
  • LinkedIn 同時支援 Company Page 分析與個人(member)檔案分析。對個人檔案而言,analytics 物件包含歷史累計的 followersCountfollowersDaily[] 中的每日粉絲成長,以及彙總的貼文指標(impressionCountuniqueImpressionsCountlikeCountcommentCountshareCount)。LinkedIn 的 count 總數為最終一致但非即時一致,在某些情況下可能需要 24-48 小時。個人檔案的彙總 shareCountlikeCountcommentCount 為最佳估算,可能與 LinkedIn 介面上顯示的數字略有差異。
  • TikTok 可能需要 24-48 小時才會更新其分析資料,例如影片觀看次數、人口統計、按讚、分享與留言。
  • 其他資訊請參閱貼文分析端點

標頭參數

主體參數

platforms
array
必填
要取得分析的社群媒體平台。接受下列字串值的陣列:
quarters
integer
指定要回傳多少「季」的歷史資料。一季的長度為:
  • Facebook:85 天
  • Instagram、TikTok 與 YouTube:90 天
  • Snapchat:90 天(因 Snapchat API 限制,最多為 1 季 / 90 天)
適用於 Facebook、Instagram、Snapchat、TikTok 與 YouTube 平台。有效值:1–4。 只有大於 0 的值才會啟用日期過濾。日期過濾(Instagram 與 TikTok):daily=truequarters > 0 時,日期過濾會啟用。 若 dailyquarters 都未提供,則回傳全歷史(all-time)資料,不套用日期過濾。注意:quarters: 0 現在會視為沒有日期範圍(全歷史資料)。先前 quarters: 0 會被視為 quarters: 1
daily
boolean
默认值:false
設為 true 時,會以每日時間序列的形式回傳分析資料,而非彙總總數。此選項僅適用於 Facebook、Instagram、Snapchat、TikTok 與 YouTube 平台。由於資料量較大,建議搭配壓縮使用。對於 Instagram 與 TikTok,設定 daily=true 也會使用預設的較短季窗口啟用日期過濾。Instagram reach:daily=true 時,Instagram 回應會回傳一個巢狀的 reach 物件(包含 periodvalues 時間序列),而非非 daily 模式下回傳的純量 reachCount 欄位。
period60Days
boolean
默认值:false
用於 TikTok 分析;設為 true 時,僅回傳留言、分享與觀看的 60 天彙總總數(commentCountTotalshareCountTotalviewCountTotal)。 相較於取得完整分析歷史,這能提供更快的回應時間。 注意:請勿與 daily=true 一起使用,兩者不相容。重要:自 2025 年 3 月 1 日起,TikTok 改為 60 天總數。自 2026 年 4 月起,TikTok 改用以季為基礎的日期過濾——請使用 quarters 參數控制日期窗口(例如 quarters: 1 = 90 天、quarters: 2 = 180 天)。詳情請見即將發生的變更
youtube
object
YouTube 分析的平台專用選項。lifetime(boolean,預設:false):設為 true 時,會在回應中包含 lifetimeLikes——即該頻道所有公開影片的按讚總和。這需要取得所有影片並加總其按讚數,因此影片數量較多的頻道可能需要較長時間。門檻: 影片超過 1,000 部的頻道會回傳 lifetimeLikes: null,並在最外層的 warnings 陣列中回傳一個警告,以避免過度使用 API。快取: 每個頻道分別快取,非成功結果的 TTL 較短,讓重試能迅速反映狀態變化:
  • 成功的 lifetimeLikes 值:24 小時
  • 1,000 部影片門檻導致的略過(警告 code: 445):1 小時——夠短,讓一個刪除影片以低於門檻的頻道不必等一整天才能取得真實值。
  • 暫時性 YouTube Data API 失敗(警告 code: 446):不快取——下一次請求會重試。
注意: 已刪除或設為私人的影片不會計入總數,因此對於已移除影片的頻道,總數可能與「真實的」歷史累計按讚數不同。請求範例:
userId
string
僅限 X/Twitter。此參數讓你能以特定 X/Twitter 使用者的數值 ID 取得其貼文,而非從你所連結的帳號取得。例如,若要取得帳號 @Google 的所有貼文,可使用其數值 userId 20536157你可以透過 Brands Get User 端點查詢任何 X/Twitter 使用者的數值 userId。注意:此請求的標頭中僅需使用 API KEY,請勿包含 Profile Key。
userName
string
僅限 X/Twitter。此參數讓你能以特定 X/Twitter 使用者的帳號(handle)取得其貼文,而非從你所連結的帳號取得。例如,取得帳號 @Google 的所有貼文。注意:此請求的標頭中僅需使用 API KEY,請勿包含 Profile Key。
當累積指標(例如粉絲數、按讚)暫時無法從社群網路取得時,API 會自動以已儲存的資料回填。每個平台的 analytics 物件可能會出現兩個選填欄位:
  • backfilledFrom(string,ISO 8601)— 當有一個以上的累積指標是以儲存資料替代時出現。時間戳表示儲存資料的最後更新時間。
  • recoveredFrom(string,ISO 8601)— 當整個分析回應因為 API 完全失敗而從儲存資料還原時出現。時間戳表示儲存資料的最後更新時間。
超過 4 天的儲存資料會視為過期,不會用於回填或還原。LinkedIn reactions 貼文層級的累積 reactions 指標(各類型表情回應數的物件)適用此僅限空值回填機制。當 LinkedIn 對 reactions 擷取進行速率限制時,該值會沿用上一次成功快照的值——backfilledFrom 會設為該快照的時間戳——而不會退回為空。
LinkedIn 個人(member)分析 — 需重新連結。 在 member 分析上線前就已連結的 LinkedIn 個人檔案並未取得所需的分析權限範圍。針對這些檔案的社群分析請求會回傳錯誤代碼 475(「re-link your LinkedIn profile to enable analytics」)。帳號擁有者必須在 Social Accounts 頁面重新連結其 LinkedIn 個人檔案,以授予新的權限範圍。重新連結後,請預留數分鐘讓錯誤代碼 475 消失(Ayrshare 與 LinkedIn 都會短暫快取權限狀態,通常約 5-10 分鐘)。發文功能不受影響。
warnings(物件陣列,選填的最外層欄位)— 僅在 Ayrshare 需要通知呼叫端某個非致命狀況時(例如某個 opt-in 計算被略過)才會出現。若沒有任何需要警告的內容,則不會出現在回應中。每個項目都是結構化物件,而非自由格式的字串:
欄位型別說明
actionstring產生此警告的操作情境(例如 "analytics")。
statusstringwarnings 陣列中的項目一律為 "warning"
codenumber穩定的 Ayrshare 警告代碼,可安全地在用戶端程式中比對。
messagestring人類可讀的說明。
detailsstring針對此警告實例的額外選填上下文。
已知的警告代碼:
  • 445 — 因 YouTube 頻道超過 1,000 部影片門檻,lifetimeLikes 被略過。
  • 446 — 因 YouTube Data API 對上傳播放清單或每個 videos.list 批次都回傳錯誤,lifetimeLikes 無法取得。