Documentation / Developer / Lytics APIs

Segment

Segments are named, logical expressions of users. These segments may logically be built using other segments as well. The Segment API provides a list of segments built by both the admin, pre-defined segments automatically added to each account as well as custom ones created through the UI.

Segments represent a number of concepts:

  • Segment: A list of users, users are members (or not) of a segment.

  • Trigger: As a user enters, or leaves a segment, this is a trigger. Triggers do not have a Size, only a history of events.

  • Goal: A segment that also implies conversion. In Lytics App, there are Goals that show more prominently in a funnel type interface.

  • Dynamic Attribute: A user belonging to a segment describes an attribute about that user. For instance IsPurchaser is both an attribute that can help personaliation, as well as a segment. We call these special segments Aspects at Lytics.

  • Metric: A segment when used exclusively for the purposes of tracking conversions/metric.

The Segment resource has the following attributes:

FieldData TypeDescription
idstringUnique ID, Lytics assigned
createdDateCreated date
updatedDateLast Updated date
kindstringWhat type of segment from list above ["aspect","goal"] or leave empty for "segment".
slugstringCustomer-assigned unique ID. If not provided, the Name will be auto assigned.
namestringName of this segment
descriptionstringLong text description (optional)
is_publicboolIs this segment available as part of user profile API (entity API)
segment_qlstringSegment QL Logical Expression
tags[]stringList of tags, for organization purposes
fields[]stringList of fields for this segment and any of its children

To see a list of available fields available for segmentation rules, see the Catalog API.

Segment List

/api/segment{?table,valid}

Get a list of all segments for an account. You might be more interested in /api/segment/sizes API below which is a more abreviated set of info including number of users in that segment.

Parameters
tablestring (optional)
Ex: user
Table for segments to fetch, "user" by default, specify "content" for content collections (aka segments).
validstring (optional)
Ex: all
True, False or "all". Get all segments, only valid, or only invalid.
GET

Segment List

/api/segment{?table,valid}

Get list of Segments . Segments can refer to any Table.

The two main tables you will be working with are User and Content.

# Grab all segments from "user" table
curl "$LIOAPI/api/segment" -s -H "Authorization: $LIOKEY" | jq '.'

# Grab all "Content Collections" (ney, segments)
curl "$LIOAPI/api/segment?table=content" -s -H "Authorization: $LIOKEY" | jq '.'

Response 200

Headers

Content-Type: application/json

Body

{
    "data": [
        {
            "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
            "account_id": "fake46b7afad96f3a4e4b41cee40ecd6",
            "author_id": "user_12345",
            "kind":"segment",
            "segment_ql": "FILTER AND ( visitct > 5, lastvisit_ts >= \"2015-04-01 00:00:00Z\", last_visit <  \"2015-04-02T00:00:00Z\")",
            "created": "2014-08-04T21:18:20.124Z",
            "updated": "2014-08-04T21:18:20.124Z",
            "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
            "is_public": true,
            "name": "Recent Visits",
            "slug_name": "recent_visits",
            "tags": [
                "email_trigger"
            ]
        }
    ]
}

Segment

/api/segment/{id}

Get Single Segment By ID or slug

Parameters
idstring (required)
Ex: my_segment_slug
id, or slug of a segment, part of url path
GET

Segment Fetch

/api/segment/{id}

Fetch a segment by id or slug

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
        "account_id": "fake46b7afad96f3a4e4b41cee40ecd6",
        "author_id": "fake1234",
        "kind":"segment",
        "segment_ql": "FILTER AND ( visitct > 5, lastvisit_ts >= \"2015-04-01T00:00:00Z\", lastvisit_ts <  \"2015-04-02T00:00:00Z\")",
        "created": "2014-08-04T21:18:20.124Z",
        "updated": "2014-08-04T21:18:20.124Z",
        "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
        "name": "Recent Visits",
        "slug_name": "recent_visits",
        "tags": [
            "email_trigger"
        ]
    }
}
PUT

Segment Update

/api/segment/{id}

Update A segment.

# You can upsert (insert if new, update if exists)
# by POSTing to api and the ALIAS will be used to lookup
# the existing one and update it.
curl -s -XPOST "https://api.lytics.io/api/segment" \
    -H "Content-type: text/plain" \
    -H "Authorization: $LIOKEY" \
    -d'

FILTER AND (
    visitct > 5,
    lastvisit_ts >= "now-30d",
    score_momentum >  10
)
ALIAS our_test_activelist

' | jq '.'


# Json Api Allows a few more fields such as description
curl -s -XPUT "https://api.lytics.io/api/segment/123456id" \
    -H "Authorization: $LIOKEY" \
    -H "Content-type: application/json" \
    -d'
{
    "name":"Most Active Users",
    "segment_ql": "FILTER AND (visitct > 5,lastvisit_ts >= \"now-30d\", score_momentum >  10)",
    "slug_name":"our_test_activelist",
    "is_public": true,
    "description":"a description of what this is for"
}
' | jq '.'

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
        "account_id": "fake46b7afad96f3a4e4b41cee40ecd6",
        "author_id": "fake1234",
        "kind":"segment",
        "segment_ql": "FILTER AND ( visitct > 5, lastvisit_ts >= \"2015-04-01T00:00:00Z\", lastvisit_ts <  \"2015-04-02T00:00:00Z\")",
        "created": "2014-08-04T21:18:20.124Z",
        "updated": "2014-08-04T21:18:20.124Z",
        "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
        "name": "Recent Visits",
        "slug_name": "recent_visits",
        "tags": [
            "email_trigger"
        ]
    }
}
DELETE

Segment Delete

/api/segment/{id}

Delete A segment.

Response 204

POST

Segment Create

/api/segment

Create A segment. See /api/segment/validate method for testing out Segmentation rules.

Pass a Segment QL logic expression to create a Segment.

# Plain Text api will extract the "our_test_activelist" as the "slug" and "name" of
# the segment
curl -s -XPOST "https://api.lytics.io/api/segment" \
    -H "Content-type: text/plain" \
    -H "Authorization: $LIOKEY" \
    -d'

FILTER AND (
    visitct > 5,
    lastvisit_ts >= "now-30d",
    score_momentum >  10
)
ALIAS our_test_activelist

' | jq '.'

# or try managing segments in files so you can check them in
# to Bitbucket or Github.   Also addresses field-
curl -s -XPOST 'https://api.lytics.io/api/segment' \
    -H 'Content-type: text/plain' \
    -H "Authorization: $LIOKEY" \
    -d @my_segment.json | jq '.'


# Json Api Allows a few more fields such as description
curl -s -XPOST "https://api.lytics.io/api/segment" \
    -H "Authorization: $LIOKEY" \
    -H "Content-type: application/json" \
    -d'
{
    "name":"Most Active Users",
    "segment_ql": "FILTER AND (visitct > 5,lastvisit_ts >= \"now-30d\", score_momentum >  10)",
    "slug_name":"our_test_activelist",
    "is_public": true,
    "description":"a description of what this is for",
    "tags":["email_personalization","product"]
}
' | jq '.'

# create a json file of a segment
curl -s -XPOST "$LIOAPI/api/segment" \
    -H "Authorization: $LIOKEY" \
    -H "Content-type: application/json" \
    -d @segment.json | jq '.'



# Content Collection (ney, "Segment")
curl -s -XPOST "https://api.lytics.io/api/segment" \
    -H "Content-type: text/plain" \
    -H "Authorization: $LIOKEY" \
    -d'

FILTER AND (
   EXISTS imageurls     -- Make sure they have images
   aspects = "article"  -- Ensure they are of type article
   PATH = "blog"        -- only show those from the /blog  part of site
   created > "now-30d"  -- only those authored in last 30 days
)
FROM content
WITH
   name = "Recent Blog Articles With Images"
ALIAS recent_blog_articles

' | jq '.'

SegmentQL

The query language for segments

Filter     = "FILTER" Phrase [FROM] [ALIAS]
Phrase     = AND | OR | Expression
AND        = "AND" (Phrase, Phrase, ...)
OR         = "OR" (Phrase, Phrase, ...)
Expression = NOT
           | Comparison
           | EXISTS
           | IN
           | CONTAINS
           | LIKE
           | IncludeSegment
NOT            = "NOT" Phrase
Comparison     = Identifier ComparisonOp Literal
ComparisonOp   = ">" | ">=" | "<" | "<=" | "==" | "!="
EXISTS         = "EXISTS" Identifier
IN             = Identifier "IN" (Literal, Literal, ...)
CONTAINS       = Identifier "CONTAINS" Literal
LIKE           = Identifier "LIKE" String # uses * for wildcards
IncludeSegment = "INCLUDE" Identifier

# Optional From, not needed for segmentation on users
FROM          = "FROM" Identifier

# Alias for giving a segment a "name" which is how
#  it will be included from other filters
ALIAS         = "ALIAS" Identifier

Literal = String | Int | Float | Bool | Timestamp

# note, identifiers may not contain spaces, or periods, etc
Identifier = [a-zA-Z][a-zA-Z0-9_]+

Examples

# Simple single expression filter
FILTER "abc" IN some_identifier

FILTER NOT foo

# Filters have an optional "Alias" used for
# referencing

FILTER AND ( channelsct > 1 AND score_quantity > 20 ) ALIAS multi_channel_active


# Filters can references to other Filters
FILTER AND (
   EXISTS email,
   NOT INCLUDE multi_channel_active
)


FILTER AND (
    visitct > 5,
    NOT INCLUDE someotherfilter,
)

# negation
FILTER NOT AND ( ... )

# Compound filter
FILTER AND (
    visitct > 5,
    lastvisit_ts >= "2015-04-01T00:00:00Z",
    lastvisit_ts <  "2015-04-02T00:00:00Z",
)

# Like
FILTER url LIKE "/blog/"

# date math
# Operator is either + or -. Units supported are y (year), M (month),
#   w (week), d (date), h (hour), m (minute), and s (second)

FILTER lastvisit_ts > "now-24h"

# IN
city IN ("Portland, OR", "Seattle, WA", "Newark, NJ")

# Complex
AND (
    OR (
        foo == true
        bar != 5
    )
    EXISTS signup_date
    OR (
        NOT bar IN (1, 2, 4, 5)
        INCLUDE SomeOtherFilter
    )
)

# Time Windows
# Can only be used on timebucket fields
# Answers the question "at least X in Y days", where X can be one of (1, 5, 10, 25, 50, 100)
# and Y can be one of (7, 30) days.
#
# timewindow(fieldname, X, Y)
FILTER timewindow(bucketfield, 5, 7)


# Between
FILTER AND (
    _modified BETWEEN "2015-07-01" AND "2016-08-01"
)

Response 201

Headers

Content-Type: application/json

Body

{
    "data": {
        "id": "7a7f76ff97ad0e3e96c162f74aee8f8f",
        "account_id": "fake46b7afad96f3a4e4b41cee40ecd6",
        "author_id": "fake1234",
        "kind":"segment",
        "segment_ql": "FILTER AND ( visitct > 5, lastvisit_ts >= \"2015-04-01T00:00:00Z\", lastvisit_ts <  \"2015-04-02T00:00:00Z\")",
        "created": "2014-08-04T21:18:20.124Z",
        "updated": "2014-08-04T21:18:20.124Z",
        "description": "Casual users have been active in the last 90 days and show no extreme behavioral patterns.",
        "name": "Recent Visits",
        "slug_name": "recent_visits",
        "tags": [
            "email_trigger"
        ]
    }
}

Segment Size

/api/segment/size

Get Segment Size for a Segment Statement.

POST

Segment Size

/api/segment/size

Get size of a single Segment using SegmentQL, not saved.

This api is very rate throttled, 1/10 seconds.

# Post a SegmentQL query to size api to fetch size
curl -s -XPOST "https://api.lytics.io/api/segment/size" \
    -H "Content-type: text/plain" \
    -H "Authorization: $LIOKEY" \
    -d'

FILTER AND (
    visitct > 5,
    lastvisit_ts >= "now-30d",
    score_momentum >  10
)

' | jq '.'

Request

Headers

Content-Type: text/plain

Body

FILTER AND (
    visitct > 10,
    EXISTS email,
    score_momentum > 25
)

Response 200

Headers

Content-Type: application/json

Body

{
    "data": {
        "id":"fakeid1234",
        "name":"active",
        "slug_name":"active",
        "size":10402
    }
}

Segment Validate

/api/segment/validate

Validate single Segment Query Statement

# Plain Text api for testing segments
curl -s -XPOST 'https://api.lytics.io/api/segment/validate' \
    -H 'Content-type: text/plain' \
    -H "Authorization: $LIOKEY" \
    -d'

FILTER AND (
    visitct > 5,
    lastvisit_ts >= "now-30d",
    score_momentum >  10
)

' | jq '.'
POST

Segment Validate

/api/segment/validate

Validate single Segment Query Statement

Request

Headers

Content-Type: text/plain

Body

FILTER AND (
    visitct > 10,
    EXISTS email,
    score_momentum > 25
)

Response 200

Headers

Content-Type: application/json

Body

{
    "status": 200,
    "message":"success",
    "data": null
}

Segment Sizes

/api/segment/sizes{?ids}

Get Segment Sizes. Pass a list of ids, or none for ALL for this account.

Parameters
ids[]string (required)
Ex: 123,456
list of ids to get, format = ids[]=123&ids[]=234 OR ids=123,345 etc, see standard []string param doc
GET

Segment Sizes

/api/segment/sizes{?ids}

Get bunch of segment sizes.

Response 200

Headers

Content-Type: application/json

Body

{
    "data" : [
        {
            "id":"456dert",
            "name":"Active",
            "slug_name":"active",
            "size":10402
        },
        {
            "id":"1234abcd",
            "type":"custom",
            "slug_name":"active",
            "size":45236
        }
    ]
}

Segment Scan

/api/segment/{segId}/scan{?id,limit,splits,start,meta,sortfield,sortorder,recent,segments,fields}

Get a list of all users (or other entity types) for a segment. See Content for examples using the Content table.

Parameters
segIdstring (optional)
Ex: 1234
segment Id in path
idstring (optional)
Ex: 1234
segment Id in querystring instead of path then use `api/segment/scan`
limitinteger (optional)
Ex: 10
num of rows to return per call, default = 20, max = 100
splits[]integer (optional)
Ex: 1,2,3
1,2,3 comma seperated list of ints 0-99 for a-b split testing (a=1,5,8 )
startinteger (optional)
Ex: next_xyz
optional ID of a previous segment scan to resume, must be recent this is retrieved from the `next` parameter in JSON response, note that this token times out 10 minutes after the previous succesful request
metaboolean (optional)
Ex: true
optional boolean, whether to include schema in response
sortfieldstring (optional)
Ex: last_visit_ts
field to sort on
sortorderstring (optional)
Ex: 20
[desc,asc]
recentboolean (optional)
Ex: true
short cut for last visit timestamp desc [t,true,]
segmentsstring (optional)
Ex: {rules...}
JSON of ad-hoc segment, or pass this in http Body
fields[]string (optional)
Ex: email,user_id,name
list of fields to include in response
GET

Segment Scan

/api/segment/{segId}/scan{?id,limit,splits,start,meta,sortfield,sortorder,recent,segments,fields}

Get a paged list of Users for a Segment.

Response 200

Headers

Content-Type: application/json

Body

{
    "next": "biglongstring",
    "data": [
        {
            "email": "[email protected]",
            "user_id": 12,
            "visitct": 100
        },
        ...
    ]
}