audience-snapshot

受众概览

用途

提供受众细分的分析视图——该细分中的人群有什么特点？展示字段值分布、覆盖率、数值统计，并突出值得注意的模式。此操作为只读操作。

环境

需要经过身份验证的 API 访问权限。凭据解析请参阅 ../references/auth.md。

输入

• 细分名称或 ID（必填）
• 要分析的特定字段（可选——默认为所有字段）
• 表（可选——默认为 user）

API 端点

按 ID 获取细分字段信息

重要：此端点需要细分的 id 哈希值（例如，a1b2c3d4e5f6），而不是 slug 名称。使用 slug 会返回 HTTP 500。请始终先通过 GET /v2/segment 获取细分 ID。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

获取多个细分的字段信息

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/fieldinfo?ids=${ID1},${ID2}&limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

查询参数

参数	默认值	最大值	描述
fields	all	-	要返回的特定字段列表，以逗号分隔
limit	20	1000	每个字段的词项值数量
table	user	-	实体表名称
cached	true	-	使用缓存结果；设为 false 可获取最新数据

响应结构

响应使用标准 API 信封格式。fieldinfo 数据位于 data.segments 中：

{
  "data": {
    "segments": [
      {
        "id": "segment_id",
        "fields": [
          {
            "field": "country",
            "terms_counts": {"US": 5000, "CA": 2000, "UK": 1500},
            "more_terms": false,
            "ents_present": 8500,
            "ents_absent": 1500,
            "approx_cardinality": 45,
            "last_updated": "2026-03-18T12:00:00Z"
          },
          {
            "field": "visit_count",
            "terms_counts": null,
            "ents_present": 9800,
            "ents_absent": 200,
            "approx_cardinality": 350,
            "stats": {"mean": 12.5, "sd": 8.3, "min": 1.0, "max": 150.0, "n": 9800},
            "histograms": [{"data": {"0-10": 4500, "10-20": 3200, "20-50": 1800, "50+": 300}}],
            "last_updated": "2026-03-18T12:00:00Z"
          }
        ]
      }
    ]
  },
  "message": "success",
  "status": 200
}

使用 jq '.data.segments[].fields[]' 解析并遍历字段。

每个字段的响应键：

键	类型	描述
field	string	字段名称
terms_counts	object	计数最高的值（分类字段）
more_terms	bool	是否还有超出限制的值
ents_present	int	填充了此字段的档案数
ents_absent	int	缺少此字段的档案数
approx_cardinality	int	估算的不同值数量
stats	object or null	仅数值字段：平均值、标准差、最小值、最大值、n
histograms	array or null	数值/日期字段：分桶分布
last_updated	timestamp	字段信息上次计算的时间

行为

第 1 步：解析细分 ID

fieldinfo 端点需要细分的 id 哈希值——使用 slug 名称会返回 HTTP 500。请始终先解析：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

按名称或 slug_name 找到匹配的细分，提取其 id 字段（十六进制哈希值）和当前规模。

第 2 步：获取字段信息

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

如果用户指定了特定字段，请添加 &fields=field1,field2,field3。 如需深入分析特定字段，请增大 limit：&limit=100。

第 3 步：展示受众概览

将结果整理成易读的摘要：

## Audience Snapshot: High Value Customers
**Size**: 10,000 profiles

### Top Demographics
**country** (98% coverage, 45 distinct values)
  US: 5,000 (50%)
  CA: 2,000 (20%)
  UK: 1,500 (15%)
  DE: 800 (8%)
  Other: 700 (7%)

**city** (85% coverage, 1,200 distinct values)
  New York: 800 (8%)
  Toronto: 600 (6%)
  London: 500 (5%)
  ...

### Engagement Metrics
**visit_count** (98% coverage)
  Mean: 12.5 | Std Dev: 8.3
  Min: 1 | Max: 150
  Distribution: 0-10: 46%, 10-20: 33%, 20-50: 18%, 50+: 3%

### Field Coverage
| Field | Coverage | Distinct Values |
|-------|----------|----------------|
| email | 92% | 9,800 |
| country | 98% | 45 |
| city | 85% | 1,200 |
| visit_count | 98% | 350 |
| products_purchased | 67% | 890 |

第 4 步：突出值得注意的模式

指出有趣的发现：

• 占主导地位的值：“该受众中有 87% 来自美国”
• 高/低覆盖率：“只有 34% 的人填写了电话号码”
• 数值异常情况：“访问次数从 1 到 150 不等，但 79% 少于 20 次”
• 比较：如果分析多个细分，突出关键差异

第 5 步：提供后续操作

展示概览后，建议下一步操作：

• “您想进一步详细分析某个字段吗？”
• “要将该受众与另一个细分进行比较吗？”
• “要根据当前结果进一步缩小该受众范围吗？”

比较细分

比较两个或更多细分时，分别获取每个细分的 fieldinfo，并并排展示：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/fieldinfo?ids=${ID1},${ID2}&limit=20" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

展示差异：

### Comparison: High Value vs All Users
| Field | High Value | All Users |
|-------|-----------|-----------|
| Avg visit_count | 12.5 | 4.2 |
| US % | 50% | 35% |
| Email coverage | 92% | 68% |

错误处理

• 未找到细分：列出可用细分，并建议检查名称
• 没有可用的字段信息：细分可能太新或为空——请先检查细分规模
• 数据过时：如果 last_updated 时间较早，建议使用 cached=false 重新获取

依赖项

• 使用：../references/auth.md、../references/api-client.md
• 相关：用于查找细分的 segment-manager skill，用于创建细分的 audience-builder skill