audience-snapshot

Audience Snapshot

Purpose

Provides an analytics view of an audience segment -- what do the people in this segment look like? Shows field value distributions, coverage rates, numeric statistics, and highlights notable patterns. This is a read-only operation.

Environment

Requires authenticated API access. See ../references/auth.md for credential resolution.

Inputs

• Segment name or ID (required)
• Specific fields to analyze (optional -- defaults to all fields)
• Table (optional -- defaults to user)

API Endpoints

Segment Field Info by ID

Important: This endpoint requires the segment's id hash (e.g., a1b2c3d4e5f6), NOT the slug name. Using a slug will return HTTP 500. Always resolve the segment ID first via GET /v2/segment.

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

Segment Field Info for Multiple Segments

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

Query Parameters

Parameter	Default	Max	Description
fields	all	-	Comma-delimited list of specific fields to return
limit	20	1000	Number of term values per field
table	user	-	Entity table name
cached	true	-	Use cached results; set false for fresh data

Response Shape

Response uses the standard API envelope. The fieldinfo data is inside 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
}

Parse with jq '.data.segments[].fields[]' to iterate over fields.

Per-field response keys:

Key	Type	Description
field	string	Field name
terms_counts	object	Top values with counts (categorical fields)
more_terms	bool	Whether more values exist beyond the limit
ents_present	int	Profiles with this field populated
ents_absent	int	Profiles missing this field
approx_cardinality	int	Estimated distinct value count
stats	object or null	Numeric fields only: mean, sd, min, max, n
histograms	array or null	Numeric/date fields: bucketed distributions
last_updated	timestamp	When field info was last computed

Behavior

Step 1: Resolve Segment ID

The fieldinfo endpoint requires the segment's id hash -- slug names will return HTTP 500. Always resolve first:

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

Find the matching segment by name or slug_name, extract its id field (hex hash) and current size.

Step 2: Fetch Field Info

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

If the user specified particular fields, add &fields=field1,field2,field3. For deeper analysis on specific fields, increase the limit: &limit=100.

Step 3: Present Audience Snapshot

Organize the results into a readable summary:

## 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 |

Step 4: Highlight Notable Patterns

Call out interesting findings:

• Dominant values: "87% of this audience is from the US"
• High/low coverage: "Only 34% have a phone number"
• Numeric outliers: "Visit count ranges from 1 to 150, but 79% have fewer than 20"
• Comparisons: If analyzing multiple segments, highlight key differences

Step 5: Offer Follow-Up Actions

After presenting the snapshot, suggest next steps:

• "Would you like to drill into a specific field with more detail?"
• "Want to compare this audience against another segment?"
• "Should I narrow this audience further based on what we see?"

Comparing Segments

When comparing two or more segments, fetch fieldinfo for each and present side-by-side:

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

Present differences:

### 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% |

Error Handling

• Segment not found: List available segments, suggest checking the name
• No field info available: Segment may be too new or empty -- check segment size first
• Stale data: If last_updated is old, suggest refetching with cached=false

Dependencies

• Uses: ../references/auth.md, ../references/api-client.md
• Related: segment-manager skill for segment lookup, audience-builder skill for creating segments