GA4 Cohort维度请求报错，缺失CohortSpec参数求解决方案

问题描述 #

报错信息：400 Cohort dimensions can only be used in requests with a CohortSpec but there is no sufficient information in GA4 or in API itself

相关代码片段：

request = RunReportRequest(
        property='properties/'+property_id, 
        dimensions=[Dimension(name="cohort"),Dimension(name='cohortNthDay')],metrics=[Metric(name='cohortActiveUsers')],      
       date_ranges=[DateRange(start_date="2022-11-20",end_date="2022-12-12")],)

df_r=pd.DataFrame(format_report(request))

已知需添加带自定义参数的CohortSpec项，但Google Analytics Data v1beta API及GA4 Data API文档缺少足够信息或示例，无法运行查询计算群组留存结果，求问如何发起群组请求。

解决方案 #

要使用群组维度和指标，必须在请求中明确配置CohortSpec，它包含群组定义、留存统计规则等核心参数。以下是可直接复用的代码示例：

from google.analytics.data_v1beta import RunReportRequest, Dimension, Metric, DateRange
from google.analytics.data_v1beta.types import CohortSpec, Cohort, CohortReportSettings

# 1. 定义群组：指定用户加入群组的时间范围（比如首次访问时间在该区间的用户）
cohort = Cohort(
    name="2022-11-20至2022-11-26群组",
    date_range=DateRange(start_date="2022-11-20", end_date="2022-11-26")
)

# 2. 配置留存统计规则
cohort_report_settings = CohortReportSettings(
    accumulate=False,  # False=按每日独立活跃用户统计；True=累加留存用户数（如第3天留存包含前2天的活跃用户）
    cohort_start_date_offset=0  # 0=从用户加入群组当天开始统计留存；1=从加入次日开始
)

# 3. 组装CohortSpec
cohort_spec = CohortSpec(
    cohorts=[cohort],
    cohort_report_settings=cohort_report_settings
)

# 4. 构建完整请求
request = RunReportRequest(
    property='properties/'+property_id,
    dimensions=[Dimension(name="cohort"), Dimension(name='cohortNthDay')],
    metrics=[Metric(name='cohortActiveUsers')],
    cohort_spec=cohort_spec,
    # 观测日期范围需覆盖群组加入日到目标留存统计的最后一天
    date_ranges=[DateRange(start_date="2022-11-20", end_date="2022-12-12")],
)

df_r = pd.DataFrame(format_report(request))

关键参数说明 #

• Cohort：定义群组的用户来源时间区间，即用户首次触发群组条件（如首次访问、首次转化）的时间段。
• CohortReportSettings：
  • accumulate：控制留存数据的统计逻辑，按需选择累加或独立统计。
  • cohort_start_date_offset：调整留存计算的起始点，适配不同的留存统计需求（比如次日留存设为1）。
• date_ranges：此处为留存数据的观测周期，必须覆盖群组加入日期到你需要统计的最后一个留存节点。

内容的提问来源于stack exchange，提问作者I.Furkan Bozkurt