> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/audience-and-activation/target-contextually/use-contextual-targeting-in-segments.md).

# Use contextual targeting in segments

Use the semantic information extracted from your content as a criterion in an audience segment.

## Your goal

Build an audience from the *content people consumed*, using the entities, IAB categories, or targeting lists the semantic engine attached to their events.

## Expected outcome

A saved audience segment whose criteria include contextual information, with the frequency and recency constraints you need.

## When this is useful

Contextual targeting normally addresses pages. This job addresses **people**, on the basis of the pages they read - "users who read at least three articles about a given topic in the last 30 days". It is the bridge between the contextual module and the rest of your audience work.

## Prerequisites

The prerequisites differ depending on which contextual criterion you want to use.

<table data-search="false"><thead><tr><th width="250">To use as criteria</th><th>What must be in place</th></tr></thead><tbody><tr><td><strong>Entities</strong> and <strong>IAB categories</strong></td><td>The <a href="/audience-and-activation/target-contextually/contextual-reference/contextual-activation.md#1-schema-update">schema</a> is updated, and the <strong>Tag event with semantic extract</strong> option is activated in the <a href="/audience-and-activation/target-contextually/contextual-reference/contextual-activation.md#2-the-contextual-targeting-extractor-event-rule">Contextual Targeting Extractor event rule</a>.</td></tr><tr><td>A particular <strong>targeting list</strong></td><td>The schema is updated, and the <strong>Use for Audience segments</strong> option is activated on that <a href="/audience-and-activation/target-contextually/contextual-reference/targeting-lists.md#making-a-list-usable-in-audience-segments">targeting list</a>.</td></tr></tbody></table>

{% hint style="info" %}
For [Edge segmentation](/audience-and-activation/build-your-audiences/segment-reference/segment-types/edge-segment.md) you do **not** need the event rule step - but you do need `@EdgeAvailability` on `semantic_tagging` and `targeting_list_ids`.
{% endhint %}

{% hint style="danger" %}
Two limits decided elsewhere apply here:

* **Raw keywords cannot be used as audience segment criteria** - only within targeting lists.
* **Only semantic targeting lists** are targetable through the `targeting_list_ids` property. A panel-based list is not.
  {% endhint %}

## Steps

The example below builds a server-side segment on targeting lists using the [Advanced Segment Builder](/audience-and-activation/build-your-audiences/segment-reference/segment-builders/advanced-segment-builder.md). Any builder can be used, though the Standard Segment Builder requires extra configuration - the criteria have to be wrapped in [audience features](/audience-and-activation/build-your-audiences/segment-reference/segment-builders/standard-segment-builder/audience-features.md) first.

{% stepper %}
{% step %}

### Open the builder

Go to **Builders > Advanced**.
{% endstep %}

{% step %}

### Add the targeting list criterion

From the schema on the right-hand side, open the **events** object and drag the **targeting\_list\_ids** attribute onto the **+** icon.
{% endstep %}

{% step %}

### Select the lists

Click the **targeting\_list\_ids** card and select **Edit**. Choose the **Equals** operator, then search for and select the targeting lists you want in **Field Values**, and click **Submit**.
{% endstep %}

{% step %}

### Add frequency, if you need it

Click the **events** card and select **Edit**. Check **I want to add a frequency** and enter the frequency you want.
{% endstep %}

{% step %}

### Add recency, if you need it

Still in the **events** card, click **Add a Field Condition** and fill in:

1. **Field name**: `ts`
2. **Operator**: **After**
3. **Field Values**: click **Relative** and enter the period you want to query over

{% hint style="warning" %}
Check that **AND** is selected between `targeting_list_ids` and the recency condition. If it shows OR, click it to switch to AND - otherwise you are selecting everyone who read anything recently, rather than everyone who read *this content* recently.
{% endhint %}
{% endstep %}

{% step %}

### Finish the segment

Add any other criteria your audience needs, then click **Save as segment** and give it a name.
{% endstep %}
{% endstepper %}

## Verification

The segment saves and its user count is plausible. It is a [Query segment](/audience-and-activation/build-your-audiences/segment-reference/segment-types/query-segment.md) like any other, so keep it persisted, as it is by default, if you intend to activate it.

## Troubleshooting

### My targeting list does not appear in the search input

Check that **Use for Audience segments** is activated on the targeting list. If it is, wait around **15 minutes** for the targeting lists to be refreshed.

### My events are not tagged with entities and IAB categories

Check that **Tag event with semantic extract** is activated in the Contextual Targeting Extractor event rule.

{% hint style="warning" %}
The option is **not retroactive**. Events ingested before it was switched on are not tagged, and will not be found by these criteria.
{% endhint %}

### When exactly are events tagged?

Every nature of event - `page_view`, `basket_view`, `article_view`, and so on - is tagged with the extracted **entities** and **IAB categories**, and with the corresponding **targeting list IDs**, **on entry into the platform**. Three consequences follow:

* Events ingested before the event rule was configured with **Tag event with semantic extract** carry no entities or IAB categories, and are not targetable through those criteria.
* Events ingested before a targeting list was configured with **Use for Audience segments** carry no targeting list ID for it, and are not targetable through that criterion.
* Updating a targeting list's definition has **no effect on events already ingested** - their targeting list IDs are not updated.

{% hint style="info" %}
Practical consequence: enable both options as early as possible, and expect a segment built on a brand-new criterion to grow from the day it was enabled rather than to arrive fully populated.
{% endhint %}

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Advanced Segment Builder</strong></td><td>The interface used above, in full.</td><td><a href="/audience-and-activation/build-your-audiences/segment-reference/segment-builders/advanced-segment-builder.md">Advanced Segment Builder</a></td></tr><tr><td><strong>Contextual activation</strong></td><td>The schema and event rule this job depends on.</td><td><a href="/audience-and-activation/target-contextually/contextual-reference/contextual-activation.md">Contextual activation</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/audience-and-activation/target-contextually/use-contextual-targeting-in-segments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.