> 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/setup-and-monitor/plan-and-integrate/set-up-advanced-features/standard-segment-builder.md).

# Standard segment builder

Configure a guided segment builder so business users can build audiences without knowing the schema.

## Your goal

Set up the standard segment builder for a datamart, so that people who do not know your schema can still build segments quickly - by picking from a curated list of criteria instead of writing a query.

## Expected outcome

At least one builder and one audience feature exist on the datamart, and **Audience > Builders > Standard** offers a usable set of criteria.

{% hint style="info" %}
This page covers the **setup** work, which is done once per datamart in settings. Using the builder to create a segment is covered in the `Audience & Activation` section.
{% endhint %}

## Where it fits among the three builders

The platform gives you three ways to segment your audience using queries.

| Tool                         | Where                              | Requires                                                                                                      | Best for                                                                                                                      |
| ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Standard segment builder** | **Audience > Builders > Standard** | Setup: at least one builder and one audience feature                                                          | Fast segment building, and visualising the segment in a dashboard before saving it. The preferred solution once it is set up. |
| **Advanced segment builder** | **Audience > Builders > Advanced** | No setup, but knowledge of the schema                                                                         | Dragging and dropping schema fields into a visual OTQL query builder. Not the best option for casual users.                   |
| **Query tool**               | **Data Studio > Query tool**       | Solid knowledge of your schema and [OTQL](/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md) | Writing OTQL queries directly.                                                                                                |

## What you configure

* A **standard segment builder** is a configured instance of the guided builder. Each builder has a list of default audience features that are automatically used in it. You can set up several builders to act as templates, once you identify segment queries your teams use often.
* An **audience feature** is one of the criteria a user can pick in the builder. The builder is only usable once at least one exists.

Both are managed in **Settings > Datamart > *****your datamart***** > Segment builders**, and can also be managed by API.

## Set it up

{% stepper %}
{% step %}

### Identify the criteria your teams actually use

Look at the segments your teams build today. The audience features you create should cover those criteria; anything else adds noise to the builder.
{% endstep %}

{% step %}

### Create the audience features

Audience features are the selectable criteria. Their detailed configuration is covered in the `Audience & Activation` section, under the standard segment builder reference.
{% endstep %}

{% step %}

### Create the builder

Go to **Settings > Datamart > *****your datamart***** > Segment builders**, or use the API:

```
POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders
```

```json
{
  "datamart_id": "string",
  "demographics_features_ids": ["string"],
  "name": "string"
}
```

`demographics_features_ids` holds the IDs of the audience features linked to the builder. **These audience features are always selected in the builder** - use them for the criteria that should frame every segment, not for optional ones.

Builders can be listed with `GET /v1/datamarts/{datamart_id}/audience_builders`, read individually with `GET /v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}`, and updated with `PUT` on the same path.
{% endstep %}

{% step %}

### Add a dashboard to the builder

The builder can show a dashboard so users see the shape of the population before saving the segment. Dashboards are uploaded per builder as a JSON definition; the components available are the same as elsewhere, so see [Create a custom dashboard](/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard.md) for what you can put in one.
{% endstep %}

{% step %}

### Import final values, if you use search by final value

To let users select audience features by their final values, import those values first, as a CSV file.

Requirements:

* Between 1 and 8 levels, followed by the final value:

  ```
  level1,level2, ... ,final_value
  ```

  ```
  level1,level2,level3,level4,final_value
  activities,channel_id,,,my channel id1
  segments,creation_ts,,,123
  ```

  `UserPoint` does not need to be specified as `level1` - it is implicit.
* A maximum of **100,000 lines**, each matching your schema.
* Final value fields of type `String` or `[String]`.

Upload with:

```
POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions
```

```bash
curl --location --request POST \
  'https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions' \
  -H 'Content-Type: text/csv' \
  -H 'Authorization: TOKEN' \
  --data-binary '@./final_value_file.csv'
```

{% endstep %}
{% endstepper %}

{% hint style="danger" %}
You cannot create more than **20** standard segment builder instances per datamart. See [Platform limits](/setup-and-monitor/plan-and-integrate/set-up-the-environment/platform-limits.md).
{% endhint %}

## Verify

* **Audience > Builders > Standard** opens and offers criteria.
* The features you marked as default appear pre-selected in every new segment.
* If you imported final values, they are selectable on the corresponding features.

## 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>Segment metrics</strong></td><td>The counts shown next to every segment.</td><td><a href="/setup-and-monitor/plan-and-integrate/set-up-the-environment/set-up-segment-metrics.md">Segment metrics</a></td></tr><tr><td><strong>Query your datamart</strong></td><td>OTQL, and the query tool the other builders rely on.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart.md">Query your datamart</a></td></tr><tr><td><strong>Create a custom dashboard</strong></td><td>Build the dashboard shown inside the builder.</td><td><a href="/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard.md">Create a custom dashboard</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/setup-and-monitor/plan-and-integrate/set-up-advanced-features/standard-segment-builder.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.