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

Behavior

For Read Operations (list, get, size)

Execute immediately and display results.

For Write Operations (create, update, delete)

Use the confirmation-gate pattern:

1. Build complete payload
2. Show human-readable summary
3. Show raw API payload
4. Wait for user confirmation
5. Execute on approval

Validation Flow

Before creating/updating a segment:

1. Validate the FilterQL with POST /api/segment/validate
2. If invalid, parse error and attempt to fix (max 3 retries)
3. Once valid, estimate size with POST /api/segment/size
4. 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