audience-snapshot
Analyze what an audience looks like -- demographic breakdowns, top field values, coverage rates, and distributions. Use when the user wants to understand audience composition, view segment demographics, or analyze field coverage for a segment.
How do I install this agent skill?
npx skills add https://github.com/lytics/agent-skills --skill audience-snapshotIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The 'audience-snapshot' skill is an analytics tool designed to interact with the Lytics API. It follows security best practices by using environment variables for sensitive tokens and communicating exclusively with official vendor domains.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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_updatedis old, suggest refetching withcached=false
Dependencies
- Uses:
../references/auth.md,../references/api-client.md - Related:
segment-manager skillfor segment lookup,audience-builder skillfor creating segments
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/lytics/agent-skills/audience-snapshot">View audience-snapshot on skillZs</a>