跳转到主要内容
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 版本中移除了唯一展示与 3 秒(唯一)视频观看的 Insights 指标,因此 Facebook 的 analytics 对象不再返回 pagePostsImpressions* 系列(pagePostsImpressionspagePostsImpressionsPaidpagePostsImpressionsUniquepagePostsImpressionsOrganicUniquepagePostsImpressionsViral*pagePostsImpressionsNonviral*pagePostsServedImpressionsOrganicUnique)以及 pageVideoViewsUnique。请使用 pageMediaView 作为覆盖指标(“总唯一媒体观看数”的后继指标已在规划中)。pagePostEngagementspageVideoViewspageVideoViewsPaid 不受影响。参考:即将进行的 API 变更 — 2026 年 6 月 15 日
  • Facebook 主页分析(例如人口统计)仅在拥有 100 个或以上点赞的主页中可用。Facebook 通常每 24 小时更新一次指标。
  • Instagram 可能需要长达 48 小时来计算分析数据。粉丝数少于 100 时无法获得粉丝分析。人口统计指标仅返回前 45 名表现者,只有我们拥有其人口统计数据的观看者才会参与人口统计指标计算,如果 Instagram 用户在最近 30 天的互动次数少于 100,则不会返回人口统计数据。
  • 在获取 Instagram 社交分析时,特定指标的响应中可能不会出现人口统计信息。当每个分组中有超过 100 人时才会出现人口统计信息。更多信息请参见 Instagram 分析人口统计警告
  • LinkedIn 同时支持公司主页分析和个人(成员)资料分析。对于个人资料,analytics 对象包含终身 followersCount、每日粉丝增长 followersDaily[],以及聚合帖子指标(impressionCountuniqueImpressionsCountlikeCountcommentCountshareCount)。LinkedIn 的 count 总数是最终一致的,但并非即时一致,某些情况下可能需要 24-48 小时。个人资料的聚合 shareCountlikeCountcommentCount 为尽力而为的结果,可能与 LinkedIn UI 中显示的数字略有差异。
  • 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 都未提供,将返回不做日期过滤的全部历史数据。注意:quarters: 0 现在被视为无日期范围(全部历史数据)。此前,quarters: 0 被视为 quarters: 1
daily
boolean
默认值:false
设置为 true 时,将以每日时间序列值的形式返回分析数据,而不是聚合总计。此选项仅适用于 Facebook、Instagram、Snapchat、TikTok 和 YouTube 平台。由于数据量较大,建议使用压缩对于 Instagram 和 TikTok,设置 daily=true 也会以默认的更短季度窗口激活日期过滤。Instagram 覆盖: 使用 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(布尔值,默认: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你可以通过品牌获取用户端点找到任意 X/Twitter 用户的数字 userId。注意:发起此请求时请仅在请求头中包含 API KEY。请勿包含 Profile Key。
userName
string
仅限 X/Twitter。此参数允许你通过特定 X/Twitter 用户的用户名获取其帖子,而不是从你关联的账户获取。例如,用于获取用户名为 @Google 的所有帖子。注意:发起此请求时请仅在请求头中包含 API KEY。请勿包含 Profile Key。
当累计指标(例如粉丝、点赞)暂时无法从社交网络获取时,API 会自动使用存储的数据回填。每个平台的 analytics 对象中可能出现两个可选字段:
  • backfilledFrom(字符串,ISO 8601)— 当有一个或多个累计指标被存储数据替换时出现。该时间戳表示存储数据最后更新的时间。
  • recoveredFrom(字符串,ISO 8601)— 当由于 API 完全失败而使整个分析响应从存储数据中恢复时出现。该时间戳表示存储数据最后更新的时间。
存储数据超过 4 天将被视为过期,不再用于回填或恢复。LinkedIn reactions 帖子级累计 reactions 指标(一个按类型划分的反应计数对象)适用于这种”仅空值时回填”的行为。当 LinkedIn 对反应拉取进行速率限制时,该值会从上一次成功快照沿用——同时 backfilledFrom 会被设置为该快照的时间戳——而不是回退为空。
LinkedIn 个人(成员)分析——需重新关联。 在成员分析上线之前关联的个人 LinkedIn 资料没有所需的分析权限范围。针对这些资料的社交分析请求会返回错误码 475(“重新关联你的 LinkedIn 资料以启用分析”)。账户所有者必须在”社交账户”页面重新关联其 LinkedIn 资料,以授予新的权限。重新关联后请等待几分钟,让 475 错误码清除(Ayrshare 与 LinkedIn 都会短暂缓存权限状态,通常约 5-10 分钟)。发布不受影响。
warnings(对象数组,可选顶层字段)— 仅在 Ayrshare 需要告知调用方非致命状况时出现(例如某个可选计算被跳过)。当没有需要警告的内容时,此字段不会出现在响应中。每个条目都是一个结构化对象,而不是自由格式的字符串:
字段类型描述
action字符串产生该警告的操作上下文(例如 "analytics")。
status字符串对于 warnings 数组中的条目始终为 "warning"
code数值稳定的 Ayrshare 警告编码。可安全地在客户端代码中匹配。
message字符串人类可读的描述。
details字符串与该警告实例相关的可选附加上下文。
已知警告代码:
  • 445 — 因 YouTube 频道超过 1,000 个视频阈值而跳过 lifetimeLikes
  • 446 — 因 YouTube Data API 对上传播放列表或每一批 videos.list 返回错误而无法获取 lifetimeLikes