segment-manager
Segment CRUD, validation, and sizing operations. Use when the user wants to list, view, create, update, delete, validate, or size segments.
How do I install this agent skill?
npx skills add https://github.com/lytics/agent-skills --skill segment-managerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a secure interface for managing Lytics segments. It follows security best practices by using environment variables for authentication and implementing a mandatory confirmation gate for destructive write operations.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Segment Manager
Purpose
Full segment lifecycle management -- list, get, create, update, delete, validate FilterQL, and estimate segment size.
Environment
Requires authenticated API access. See ../references/auth.md for credential resolution.
API Endpoints
List Segments
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&kind=segment&sizes=true" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Query params: table, kind, valid, sizes
Get Segment
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?sizes=true&inline=true" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Query params: sizes (include size data), inline (inline included segments)
Get Segment Ancestors
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}/ancestors" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Create Segment
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment" \
-H "Authorization: ${LYTICS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "Segment Name",
"slug_name": "segment_slug",
"description": "What this segment represents",
"segment_ql": "FILTER condition FROM user ALIAS segment_slug",
"kind": "segment",
"table": "user",
"is_public": true,
"tags": [],
"save_hist": true
}'
Update Segment
curl -s -X PUT "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
-H "Authorization: ${LYTICS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{ ... updated fields ... }'
Delete Segment
curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Validate FilterQL
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
-H "Authorization: ${LYTICS_API_TOKEN}" \
-H "Content-Type: text/plain" \
-d 'FILTER AND (country = "US", visitct > 5) FROM user ALIAS test'
Returns 200 on valid, error message on invalid.
Estimate Segment Size (ad-hoc FilterQL)
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
-H "Authorization: ${LYTICS_API_TOKEN}" \
-H "Content-Type: text/plain" \
-d 'FILTER condition FROM user'
Body is raw FilterQL text, not JSON.
Get Existing Segment Size
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/size" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Segment Field Info -- Audience Snapshot
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
-H "Authorization: ${LYTICS_API_TOKEN}"
Returns per-field analytics within a segment: value distributions, coverage rates, numeric stats, and histograms.
Query params: fields (comma-delimited), limit (default 20, max 1000), table, cached.
For detailed analysis, use the audience-snapshot skill.
Reevaluate Segment
curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/reevaluate" \
-H "Authorization: ${LYTICS_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"id": "segment_id"}'
Segment Payload
Required fields for creation:
{
"name": "Display Name",
"slug_name": "url_friendly_slug",
"description": "Human-readable description",
"segment_ql": "FILTER ... FROM user ALIAS slug",
"kind": "segment",
"table": "user",
"is_public": true,
"save_hist": true
}
Optional fields:
{
"tags": ["tag1", "tag2"],
"groups": ["group_id"],
"expires_at": "2025-12-31T00:00:00Z",
"emit_trigger": false,
"schedule_exit": false
}
Segment Kinds
| Kind | Description | Use Case |
|---|---|---|
segment | Standard audience segment | General audience targeting |
aspect | Building block segment | Reusable filter components |
goal | Business objective | Conversion tracking |
list | Temporal export list | One-time or recurring exports |
conversion | Campaign tracking | Attribution measurement |
metric | Metric segment | Analytics/reporting |
managed | System-managed | Internal platform use |
candidate | Decisioning exclusion | Exclude from decisioning |
Behavior
For Read Operations (list, get, size)
Execute immediately and display results.
For Write Operations (create, update, delete)
Use the confirmation-gate pattern:
- Build complete payload
- Show human-readable summary
- Show raw API payload
- Wait for user confirmation
- Execute on approval
Validation Flow
Before creating/updating a segment:
- Validate the FilterQL with
POST /api/segment/validate - If invalid, parse error and attempt to fix (max 3 retries)
- Once valid, estimate size with
POST /api/segment/size - Present validation + size results before proceeding
Error Handling
- Invalid FilterQL: Parse the validation error, identify the issue, suggest fix
- Slug conflict (409): Suggest alternative slug name
- Empty segment (size 0): Warn user, suggest broadening criteria
- Very large segment: Note the size and ask user to confirm intent
Dependencies
- Uses:
../references/auth.md,../references/api-client.md,../references/confirmation-gate.md - References:
../references/filterql-grammar.md
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/segment-manager">View segment-manager on skillZs</a>