> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audiences and Segments

> Define behavior-based and request-based targeting with clear priorities and a safe base fallback.

An **audience** names who an experience is for. A **segment** describes the first-party behavior that qualifies a visitor for that audience. For targeting that depends only on the current request, an audience can reference a request rule instead.

## Resource locations

```text theme={null}
.content/
├── audiences/{audience-id}/_index.json
├── segments/{segment-id}/_index.json
└── rules/{rule-id}/_index.json
```

Each resource ID must be one path-safe segment and match its directory name.

## Define a behavior-based segment

This segment qualifies a visitor who viewed `/pricing` at least three times in the last seven days but has not completed the demo-request goal:

```json theme={null}
{
  "$type": "segment",
  "props": {
    "id": "high-intent",
    "displayName": "High-intent visitors",
    "status": "enabled",
    "priority": 200,
    "criteria": {
      "all": [
        {
          "type": "event_count",
          "event": "rum.page_view",
          "path": "/pricing",
          "minCount": 3,
          "withinDays": 7
        }
      ],
      "none": [
        {
          "type": "event_exists",
          "event": "custom.demo-request"
        }
      ]
    }
  }
}
```

Criteria groups use these rules:

* every condition in `all` must match;
* at least one condition in `any` must match;
* no condition in `none` may match; and
* the segment must include at least one positive `all` or `any` condition.

### Condition types

| Type           | Use it when                                        | Required fields     |
| -------------- | -------------------------------------------------- | ------------------- |
| `event_count`  | An event must occur a minimum number of times      | `event`, `minCount` |
| `event_exists` | At least one matching event is enough              | `event`             |
| `event_latest` | The latest matching event must satisfy the filters | `event`             |

All three types can filter by `path`, `referrer`, scalar `properties`, an experiment and arm, or a positive `withinDays` window. A trailing `*` performs prefix matching for `path`, `referrer`, and string property values.

<Tip>
  Use canonical event names in criteria: built-in events use namespaces such as `rum.*`; custom events use `custom.*`.
</Tip>

## Connect the segment to an audience

```json theme={null}
{
  "$type": "audience",
  "props": {
    "id": "high-intent",
    "displayName": "High-intent visitors",
    "status": "enabled",
    "priority": 200,
    "membershipSource": "segment",
    "segmentRef": "$ref:segments/high-intent"
  }
}
```

Both resources must be enabled for the audience to participate in selection. A draft or disabled resource remains versioned but is not eligible for live delivery.

## Define a request-based audience

Request rules are useful when the current request provides everything needed for a decision, such as campaign parameters. They do not require a stored behavior history.

Create `.content/rules/enterprise-campaign/_index.json`:

```json theme={null}
{
  "$type": "audience_rule",
  "props": {
    "id": "enterprise-campaign",
    "status": "enabled",
    "description": "Enterprise campaign traffic",
    "expression": {
      "all": [
        {
          "field": "utm.campaign",
          "operator": "startsWith",
          "value": "enterprise-"
        }
      ]
    }
  }
}
```

Then reference it from an audience:

```json theme={null}
{
  "$type": "audience",
  "props": {
    "id": "enterprise-campaign",
    "displayName": "Enterprise campaign visitors",
    "status": "enabled",
    "priority": 100,
    "membershipSource": "rule",
    "ruleRef": "$ref:rules/enterprise-campaign"
  }
}
```

Request rules support `query.*`, `utm.*`, `header.*`, `cookie.*`, trusted `geo.*` facts, and `referrer`. Supported operators are `equals`, `contains`, `startsWith`, and `exists`.

<Warning>
  Header, geographic, and device facts depend on the configured hosting adapter. Confirm the available trusted facts for your deployment before using them in customer-facing targeting.
</Warning>

## Priority and fallback

When several audiences match the same request, the higher audience priority wins. Give overlapping audiences distinct priorities so the intended result is easy to review.

ACI uses the base experience when no audience matches or when a required fact, reference, or consented identity is unavailable. Build the base page as a complete, valid experience and test it alongside every audience variant.

## Validate a change

```bash theme={null}
npm run content:compile
npm run typecheck
npm test
```

Compilation validates criteria shapes, resource status, references, overlay targets, and each resolved variant before the change reaches a release.

***

*Next: [Experiences and Overlays →](/aci/personalization/experiences-and-overlays)*