# Segment builders

You have access to three tools to segment your audience using queries:

* Leverage [audience features](/advanced-usages/audiences/audience-features.md) to build your queries in the standard segment builder (**Audience** > **Builders** > **Standard**). Once set up, this is the preferred solution for fast queries building and visualising the segment in a dashboard before saving it.
* Drag and drop fields from your schema into a visual OTQL query builder with the advanced segment builder (**Audience** > **Builders** > **Advanced**). It doesn't require any setup but requires knowledge about the schema. May not be the best option for casual users.
* Build OTQL queries directly in **Data Studio** > **Query tool.** This requires a solid knowledge of your schema and [OTQL](/querying-your-data/otql-queries.md).

## Standard segment builder set up

You enable this feature when you set up at least:

* One segment builder
* One [audience feature](/advanced-usages/audiences/audience-features.md). 

You can set up multiple segment builder to create templates once you identify common segment queries that you often use.

Each segment builder has a list of default audience features that are automatically used in it.

You can create and edit segment builders through the UI by going to **Settings** > **Datamart** > **Your datamart** > **Segment builders.** You can also manage them by API.

## List standard segment builders

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders`

#### Path Parameters

| Name         | Type    | Description            |
| ------------ | ------- | ---------------------- |
| datamart\_id | integer | The ID of the datamart |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}
```

{% endtab %}
{% endtabs %}

## Get a standard segment builder

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}`

#### Path Parameters

| Name                   | Type    | Description                                        |
| ---------------------- | ------- | -------------------------------------------------- |
| datamart\_id           | integer | The ID of the datamart                             |
| audience\_builders\_id | integer | The ID of standard segment builder you want to get |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Create a standard segment builder

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders`

#### Path Parameters

| Name         | Type    | Description            |
| ------------ | ------- | ---------------------- |
| datamart\_id | integer | The ID of the datamart |

#### Request Body

| Name                        | Type   | Description                                                                                                                                                      |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| datamart\_id                | string | The ID of the datamart                                                                                                                                           |
| demographics\_features\_ids | array  | Array of string: the IDs of audience features you want to link to your standard segment builder. These audience features will always be selected in the builder. |
| name                        | string | Name of the standard segment builder                                                                                                                             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}
```

{% endtab %}
{% endtabs %}

## List standard segment builders

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders`

#### Path Parameters

| Name         | Type    | Description  |
| ------------ | ------- | ------------ |
| datamart\_id | integer | GLLBBPYmcMbn |

## Get a standard segment builder

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}`

#### Path Parameters

| Name                   | Type    | Description  |
| ---------------------- | ------- | ------------ |
| datamart\_id           | integer | EACXzNpxesGA |
| audience\_builders\_id | integer | y1iztafbxNOl |

## Create a standard segment builder

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders`

#### Path Parameters

| Name         | Type    | Description  |
| ------------ | ------- | ------------ |
| datamart\_id | integer | UpWZubSJk7SC |

#### Request Body

| Name                        | Type   | Description  |
| --------------------------- | ------ | ------------ |
| datamart\_id                | string | ZdvK39oPj25k |
| demographics\_features\_ids | array  | Zu89g8D3qu6m |
| name                        | string | bpFIx0HWRbci |

```javascript
// Create a standard segment builder payload
{
  "datamart_id": "string",
  "demographics_features_ids": [
    "string"
  ],
  "name": "string"
}
```

{% hint style="danger" %}
&#x20;You cannot create more than 20 standard segment builder instances per datamart. &#x20;
{% endhint %}

## Edit a standard segment builder

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}`

#### Path Parameters

| Name                   | Type    | Description                                    |
| ---------------------- | ------- | ---------------------------------------------- |
| audience\_builders\_id | integer | The ID of the standard segment builder to edit |
| datamart\_id           | integer | The ID of the datamart                         |

#### Request Body

| Name                        | Type   | Description                                                                                                                                                      |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| datamart\_id                | string | The ID of the datamart                                                                                                                                           |
| demographics\_features\_ids | string | Array of string: The IDs of audience features you want to link to your standard segment builder. These audience features will always be selected in the builder. |
| name                        | string | The name of the standard segment builder                                                                                                                         |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Edit a standard segment builder

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_builders/{audience_builders_id}`

#### Path Parameters

| Name                   | Type    | Description  |
| ---------------------- | ------- | ------------ |
| audience\_builders\_id | integer | aIhsvJpgK6ny |
| datamart\_id           | integer | TTSN6yxr96WI |

#### Request Body

| Name                        | Type   | Description  |
| --------------------------- | ------ | ------------ |
| datamart\_id                | string | N2N4Y3WHqATi |
| demographics\_features\_ids | string | 1EsZV25xtbUt |
| name                        | string | xsAiWSvKY437 |

```javascript
// Edit a standard segment builder payload
{
  "datamart_id": "string",
  "demographics_features_ids": [
    "string"
  ],
  "name": "string"
}
```

### Dashboards API

This API helps you upload dashboards.

## List dashboards for standard segment builder

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json`

#### Path Parameters

| Name                  | Type    | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| organisation\_id      | integer | The ID of the organisation                                                    |
| datamart\_id          | integer | The ID of the datamart                                                        |
| audience\_builder\_id | integer | The ID of the standard segment builder on which you want to upload dashboards |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Create & edit dashboards for standard segment builder

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json`

#### Path Parameters

| Name                  | Type    | Description                                                                   |
| --------------------- | ------- | ----------------------------------------------------------------------------- |
| organisation\_id      | integer | The ID of the organization                                                    |
| datamart\_id          | integer | The ID of the datamart                                                        |
| audience\_builder\_id | integer | The ID of the standard segment builder on which you want to upload dashboards |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## List dashboards for standard segment builder

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json`

#### Path Parameters

| Name                  | Type    | Description  |
| --------------------- | ------- | ------------ |
| organisation\_id      | integer | xpvJF5g4SpwP |
| datamart\_id          | integer | uqK1nIMmTAn6 |
| audience\_builder\_id | integer | cZe7evLowSbp |

## Create & edit dashboards for standard segment builder

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/data_file/data?uri=mics://data_file/tenants/{organisation_id}/dashboards/{datamart_id}/AUDIENCE_BUILDER-{audience_builder_id}.json`

#### Path Parameters

| Name                  | Type    | Description  |
| --------------------- | ------- | ------------ |
| organisation\_id      | integer | UFX1xf9M0BWy |
| datamart\_id          | integer | uhpUbCPUJ0Gm |
| audience\_builder\_id | integer | 5Rm1gDwXgxFe |

```javascript
// Create a dashboard payload example
[
  {
      "id": "1",
      "name": "Standard segment builder",
      "type": "AUDIENCE_BUILDER",
      "datamart_id": "xxxx",
      "components": [
        {
          "layout": {
            "h": 1,
            "static": false,
            "w": 6,
            "x": 0,
            "y": 0
          },
          "component": {
            "id": 2,
            "component_type": "COUNT",
            "title": "User Profiles",
            "query_id": "22252"
          }
        },
        {
          "layout": {
            "h": 1,
            "static": false,
            "w": 6,
            "x": 6,
            "y": 0
          },
          "component": {
            "id": 2,
            "component_type": "COUNT",
            "title": "User Cookies",
            "query_id": "22264"
          }
        },
        {
          "layout": {
            "h": 3,
            "static": false,
            "w": 12,
            "x": 0,
            "y": 1
          },
          "component": {
            "id": 5,
            "component_type": "MAP_BAR_CHART",
            "title": "Genre",
            "show_legend": true,
            "query_id": "47031",
            "sortKey": "A-Z",
            "percentage": true,
            "labels": {
              "enable": true,
              "filterValue": "",
              "format": "{point.y}%"
            },
            "tooltip": {
              "formatter": "{point.y}% ({point.count})"
            }
          }
        },
        {
          "layout": {
            "h": 3,
            "static": false,
            "w": 12,
            "x": 0,
            "y": 4
          },
          "component": {
            "id": 5,
            "component_type": "COUNT_BAR_CHART",
            "labels_enabled": true,
            "plot_labels": [
              "Email",
              "Print",
              "Sms",
              "Tel",
              "Web",
              "App"
            ],
            "title": "Contactabilité",
            "show_legend": false,
            "query_ids": [
              "47033",
              "47034",
              "47035",
              "47036",
              "47037",
              "47038"
            ]
          }
        }
      ]
    }
]
```

### Final values import

In ordre to be able to select audience features thanks to final values, you should first import your final values thanks to a csv file. For more information about the search by final feature, please read the *search by final value feature guider*.&#x20;

#### Requirements

Your csv file should have:

* The following format: 1 level min and 8 levels max, final\_value,

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

Example

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

{% hint style="info" %}
Don't need to specify UserPoint for the level1, it's implicit.
{% endhint %}

* A maximum of 100 000 lines, each line should match your schema,
* Final values' field of type `String` or `[String]`.

#### API

## Upload final values csv file

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions`

#### Path Parameters

| Name         | Type    | Description            |
| ------------ | ------- | ---------------------- |
| datamart\_id | integer | The ID of the datamart |

#### Request Body

| Name | Type   | Description                                                                     |
| ---- | ------ | ------------------------------------------------------------------------------- |
| file | string | The name of the file you want to import. Ex: "@final\_value\_file.cs&#x76;**"** |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "ok",
  "data": {
    "parameters": null,
    "result": null,
    "error": null,
    "id": "xxxxxx",
    "status": "PENDING",
    "creation_date": 1634134417792,
    "start_date": null,
    "duration": null,
    "organisation_id": "xxxx",
    "user_id": "xxxx",
    "cancel_status": null,
    "debug": null,
    "is_retryable": false,
    "num_tasks": null,
    "completed_tasks": null,
    "erroneous_tasks": null,
    "retry_count": 0,
    "permalink_uri": null,
    "job_type": "REFERENCE_TABLE",
    "import_mode": "MANUAL_FILE",
    "import_type": null
  }
}
```

{% endtab %}
{% endtabs %}

## Upload final values csv file

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/{datamart_id}/reference_table_job_executions`

#### Path Parameters

| Name         | Type    | Description  |
| ------------ | ------- | ------------ |
| datamart\_id | integer | Od2HfDMVLPel |

#### Request Body

| Name | Type   | Description  |
| ---- | ------ | ------------ |
| file | string | kUYOfU4QZxF3 |

Example

```javascript
curl -k --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'
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/advanced-usages/audiences/segment-builders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.