# Event segmentation

Event Segmentation lets you target audiences based on lifecycle actions or Custom Events that have occurred.

To Segment based on event activity, include an [Activity Object](/developer/rest-api/ua/schemas/event-segmentation/#activityobject) in your audience, and an optional [Where Object](/developer/rest-api/ua/schemas/event-segmentation/#whereobject) to filter on specific event properties.


## Activity audience object {#activityobject}

The `activity` object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values.

In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago.


[Jump to examples ↓](#activityobject-examples)

- **`activity`** `string` **REQUIRED**

  The target event activity, e.g., `app_open`.

Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Manage events](/docs/guides/audience/events/manage/).


  Possible values: `app_open`, `message_received`, `message_center_read`, `message_center_delivered`, `message_center_deleted`, `in_app_message_display`, `in_app_message_resolution`, `in_app_message_expiration`, `screen_view`, `web_session`, `web_click`, `short_link_click`, `first_seen`, `sms_aborted`, `sms_delivered`, `sms_dispatched`, `sms_expired`, `sms_failed`, `sms_rejected`, `sms_undeliverable`, `sms_unknown`, `email_bounce`, `email_click`, `email_delay`, `email_delivered`, `email_injection`, `email_open`, `email_unsubscribe`, `scene_displayed`, `scene_completed`, `scene_incomplete`, `survey_displayed`, `survey_submitted`, `survey_not_submitted`

- **`after`** `object`

  A date value for an absolute comparison or an integer value for a relative comparison.


  **One of:**

  - `string`

    A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), for example: `"after": "2020-08-01T12:00:00"`.

  - `integer`

- **`before`** `object`

  A date value for an absolute comparison or an integer value for a relative comparison.


  **One of:**

  - `string`

    A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), for example: `"before": "2020-08-01T12:00:00"`.

  - `integer`

- **`metric`** `string`

  The metric you are targeting for the event.

When using the metric `count` or `total_value`, `operator` and `value` are required.

When using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead:

* `before`/`precision`
* `after`/`precision`
* `on`/`on_precision`

| Metric | Description |
|---|---|
| `count` | Evaluate based on the number of event occurrences. |
| `total_value`   | Evaluate based on the cumulative event `value` associated with the target user. |
| `last` | Evaluate based on the last occurrence of an event for a given user/time window. |
| `first` | Evaluate based on the first occurrence of an event for a given user/time window. |


  Possible values: `count`, `total_value`, `last`, `first`

- **`on`** `string`

  Use `on` in conjunction with the `first` or `last` metric to indicate either a specific date or period with precision. Use either:

* A date in ISO 8601 format, e.g., `2020-08-10T17:28:34+0000` or
* An integer that, when combined with the `on_precision` property, specifies the time period. For example, use `"on": 12` with `"on_precision: "month"` to target events that occurred in December.


  **One of:**

  - `string`

    A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format).

  - `integer`

- **`on_precision`** `string`

  When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`.

  Possible values: `day`, `month`, `month_day`, `year_month`, `year_month_day`

- **`operator`** `string` **REQUIRED**

  The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`.


  Possible values: `greater`, `less`, `equals`, `greater_eq`, `less_eq`

- **`precision`** `string`

  If using a relative number (integer) for the `before`/`after`/`on` property,
the `precision` value will be interpreted as the number of time units ago, e.g.,
*7 days ago*. Defaults to `days`.


  Possible values: `days`, `weeks`, `months`, `years`

  Default: `days`

- **`value`** `number` **REQUIRED**

  The value that the `operator` uses to evaluate the target audience.


- **`where`** `object`

  The [Where Object](/docs/developer/rest-api/ua/schemas/event-segmentation/#whereobject).


**Used in:**

- [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment)
- [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment)
- [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments)
- [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment)
- [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule)
- [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules)
- [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate)
- [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification)
- [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush)
- [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments)
- [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment)
- [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush)
- [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions)
- [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule)
- [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment)
- [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush)
- [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate)
- [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment)

**Examples**

*Activity audience object*

```json
{
   "audience": {
      "activity": "app_open",
      "operator": "greater",
      "value": 2,
      "after": 3,
      "precision": "days",
      "where": {
         "property": "/_triggering_push/campaigns/categories",
         "operator": "equals",
         "value": "neowise"
      }
   }
}

```

---

## Where object {#whereobject}

`where` is an object that filters on the existence of prior user activity, specified by event properties that you provide.


[Jump to examples ↓](#whereobject-examples)

- **`compare_as`** `string`

  Selects the property type for comparison.

  Possible values: `text`, `number`, `date`, `boolean`

- **`operator`** `string` **REQUIRED**

  The operator in question

  Possible values: `greater`, `less`, `equals`, `greater_eq`, `less_eq`, `contains`, `present`, `range`, `before`, `after`

- **`precision`** `string`

  Used only for date values.

  Possible values: `minutes`, `days`, `months`, `years`

- **`property`** `string` **REQUIRED**

  The Custom Event property on which to filter for inclusion in the audience.  See [Event Segmentation Properties](/docs/guides/audience/events/events/#events-reference) for properties reference.


- **`relative_to`** `string`

  Used only for date values.

  Possible values: `future`, `past`

- **`value`** `object` **REQUIRED**

  The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison.


  **One of:**

  - `string`

    A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), e.g., `2020-08-10T17:28:34+0000`.

  - `number`
  - `boolean`


**Examples**

*Example payload to an audience of users who have opened your app as a result of receiving a specific push ID.
*

```json
{
   "audience": {
      "activity": "app_open",
      "metric": "count",
      "operator": "greater",
      "value": 0,
      "where": {
         "property": "/_triggering_push/push_id",
         "operator": "equals",
         "compare_as": "text",
         "value": "636abb88-5642-4035-998d-a04c93c499ad"
      }
   },
   "device_types": [
      "ios", "android"
   ],
   "notification": {
      "alert": "Did you get that thing I sent you?"
   }
}

```

---