skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
lytics/agent-skills50 installs

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-snapshot
view source ↗

Is 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

ParameterDefaultMaxDescription
fieldsall-Comma-delimited list of specific fields to return
limit201000Number of term values per field
tableuser-Entity table name
cachedtrue-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:

KeyTypeDescription
fieldstringField name
terms_countsobjectTop values with counts (categorical fields)
more_termsboolWhether more values exist beyond the limit
ents_presentintProfiles with this field populated
ents_absentintProfiles missing this field
approx_cardinalityintEstimated distinct value count
statsobject or nullNumeric fields only: mean, sd, min, max, n
histogramsarray or nullNumeric/date fields: bucketed distributions
last_updatedtimestampWhen 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

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>