# Audience Segments

### Audience Segments

The audience segment APIs allow users to fetch all unique audience segments created, deleted or replaced under a particular Sub-Account, Connection or Batch.

#### Get by Sub-Account

This API can be used to fetch unique audience segments under a sub-account.

{% code lineNumbers="true" %}

```
GET /es/v2/segments/account/<sub_account_id>
```

{% endcode %}

**Query parameters**

{% code lineNumbers="true" %}

```
?type=created (default) | deleted | replaced
&pageSize=100
&page=1
```

{% endcode %}

**Response:**

{% code lineNumbers="true" %}

```
{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}

```

{% endcode %}

**Attributes:**

| **Attribute** | **Description**                                                                                            | **Possible Values**               |
| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
| segmentName   | Name of the Audience Segment                                                                               | <p><br></p>                       |
| segmentId     | Unique id of the Audience segment                                                                          | <p><br></p>                       |
| date          | Date of creation / delete / replace                                                                        | YYYY-MM-DD format                 |
| accountId     | ID of the sub-account in which this segment was created or deleted or replaced.                            | UUID (16-character identifier)    |
| connectionId  | ID of the connection in which this segment was created or deleted or replaced.                             | UUID (16-character identifier)    |
| batchId       | ID of the batch in which this segment was created or deleted or replaced.                                  | UUID (32-character identifier)    |
| pageSize      | <p>Maximum number of segments to return in a single API call. </p><p>Default: 100</p><p>Max Size: 1000</p> | Integer (e.g., 10, 100 etc..)     |
| page          | Current page number                                                                                        | Integer (e.g., 1,2, 3, etc.)      |
| totalPages    | Total number of pages                                                                                      | Integer (e.g., 1, 2, 3, etc.)     |
| totalRecords  | Total number of records (segments) across all pages                                                        | Integer (e.g., 0, 10, 1000 etc..) |

**Sample Curl::**

{% code lineNumbers="true" %}

```
curl --location '<host>/es/v2/segments/account/9c4e0bbf84211a81' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-2144-d54d4be743fe'
```

{% endcode %}

#### Get by Connection

This API can be used to fetch unique audience segments under a given connection.

{% code lineNumbers="true" %}

```
GET /es/v2/segments/connection/<connection_id>
```

{% endcode %}

**Query parameters**

{% code lineNumbers="true" %}

```
?type=created (default) | deleted | replaced
&pageSize=100
&page=1
```

{% endcode %}

**Response:**

{% code lineNumbers="true" %}

```
{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}
```

{% endcode %}

**Attributes:**

| **Attribute** | **Description**                                                                                            | **Possible Values**               |
| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
| segmentName   | Name of the Audience Segment                                                                               | <p><br></p>                       |
| segmentId     | Unique id of the Audience segment                                                                          | <p><br></p>                       |
| date          | Date of creation / delete / replace                                                                        | YYYY-MM-DD format                 |
| accountId     | ID of the sub-account in which this segment was created or deleted or replaced.                            | UUID (16-character identifier)    |
| connectionId  | ID of the connection in which this segment was created or deleted or replaced.                             | UUID (16-character identifier)    |
| batchId       | ID of the batch in which this segment was created or deleted or replaced.                                  | UUID (32-character identifier)    |
| pageSize      | <p>Maximum number of segments to return in a single API call. </p><p>Default: 100</p><p>Max Size: 1000</p> | Integer (e.g., 10, 100 etc..)     |
| page          | Current page number                                                                                        | Integer (e.g., 1,2, 3, etc.)      |
| totalPages    | Total number of pages                                                                                      | Integer (e.g., 1, 2, 3, etc.)     |
| totalRecords  | Total number of records (segments) across all pages                                                        | Integer (e.g., 0, 10, 1000 etc..) |

**Sample Curl::**

{% code lineNumbers="true" %}

```
curl --location '<host>/es/v2/segments/connection/fccc1c8423c11d' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-2144-d54d4be743fe'
```

{% endcode %}

#### Get by Batch

&#x20;This API can be used to fetch unique audience segments under a given batch (transfer)

{% code lineNumbers="true" %}

```
GET /es/v2/segments/batch/<batch_id>
```

{% endcode %}

**Query parameters**

{% code lineNumbers="true" %}

```
?type=created (default) | deleted | replaced
&pageSize=100
&page=1
```

{% endcode %}

**Response:**

{% code lineNumbers="true" %}

```
{
    "statusCode": 200,
    "statusMessage": "Request executed successfully",
    "response": {
        "data": [
          {
            "segmentId": "<string>",
            "segmentName": "<string>",
            "date":"<string>",
            "accountId": "<string>",
            "connectionId": <string>",
            "batchId" : "<string>" 
          },
          ...
        ],
        "totalRecords": 0,
        "totalPages": 0,
        "pageSize": 0,
        "page" : 0
    }
}

```

{% endcode %}

**Attributes:**

| **Attribute** | **Description**                                                                                            | **Possible Values**               |
| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------- |
| segmentName   | Name of the Audience Segment                                                                               | <p><br></p>                       |
| segmentId     | Unique id of the Audience segment                                                                          | <p><br></p>                       |
| date          | Date of creation / delete / replace                                                                        | YYYY-MM-DD format                 |
| accountId     | ID of the sub-account in which this segment was created or deleted or replaced.                            | UUID (16-character identifier)    |
| connectionId  | ID of the connection in which this segment was created or deleted or replaced.                             | UUID (16-character identifier)    |
| batchId       | ID of the batch in which this segment was created or deleted or replaced.                                  | UUID (32-character identifier)    |
| pageSize      | <p>Maximum number of segments to return in a single API call. </p><p>Default: 100</p><p>Max Size: 1000</p> | Integer (e.g., 10, 100 etc..)     |
| page          | Current page number                                                                                        | Integer (e.g., 1,2, 3, etc.)      |
| totalPages    | Total number of pages                                                                                      | Integer (e.g., 1, 2, 3, etc.)     |
| totalRecords  | Total number of records (segments) across all pages                                                        | Integer (e.g., 0, 10, 1000 etc..) |

**Sample Curl::**

{% code lineNumbers="true" %}

```
curl --location '<host>/es/v2/segments/batch/22bb77079c084d0c984635611f999994' \
--header 'Authorization: Bearer d28bd3c8-f634-476d-8344-214d4be743fe'
```

{% endcode %}

#### Get directly from Platform

&#x20;This API can be used to fetch an audience list directly from the configured connector platform.&#x20;

The API enables retrieval of segments based on:

* MadConnect Sub Account ID (mandatory)
* Ad Account ID (mandatory)
* Segment Name (optional)
* Segment ID (optional)
* Connector ID (mandatory)

Additionally, the API will only return segments matching the connector’s integration type (e.g., Customer File / Custom Audience).

&#x20;Note:

* API will only fetch data if Connector is configured
* MadConnect does NOT store connector secrets
* Secrets are stored in the customer-managed Snowflake account or on a deployed cloud account. Secrets are retrieved dynamically at runtime<br>

{% code lineNumbers="true" %}

```
GET /es/v2/segments/direct
```

{% endcode %}

**Query parameters**

{% code lineNumbers="true" %}

```
?subAcountId=<string> // sub account ID
?&adAccountId=<string> // Advertiser account ID
&connectorId=<string> // Connector ID
&segmentName=<string> // Name of the segment to filter - platform dependent
&segmentId=<string> // Id of the segment to filer - platform dependent
&pageToken=<string> // page token or index
&pageSize=50 // size of the page, default: 50; max:200
```

{% endcode %}

**Response:**

{% code lineNumbers="true" %}

```
{
 "statusCode": 200,
 "statusMessage": "Request executed successfully",
 "response": {
   "segments": [
     {
       "segmentId": "<string>",
       "segmentName": "string>",
       "adAccountId": "<string>",
       "connectorId": "<string>",
       "platform": "<string>",
       "creationDate": "<string>",
       "updateDate": "<string>",
       "numUsers": 0,
       "status": "<string>",
       "statusMessage": "<string>",
       "type": "<string>"
     }
   ],
   "pageSize": 0,
   "nextPageToken" : "<string>",
   "hasMore" : <boolean>
 }
}
```

{% endcode %}

**Attributes:**

| **Attribute** | **Type** | **Description**                                                                                  |
| ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| segmentId     | string   | Unique segment identifier                                                                        |
| segmentName   | string   | Segment name                                                                                     |
| adAccountId   | string   | Ad account ID                                                                                    |
| connectorId   | string   | Connector identifier                                                                             |
| platform      | string   | Derived from connector metadata                                                                  |
| creationDate  | datetime | Created timestamp e.g. 2026-03-18T15:15:24Z                                                      |
| updateDate    | datetime | Last updated timestamp e.g. 2026-03-18T15:15:24Z (returned if available in destination platform) |
| numUsers      | integer  | Audience size (returned if available in destination platform)                                    |
| status        | string   | Segment status                                                                                   |
| statusMessage | string   | Segment status message (platform-specific)                                                       |

**Sample Curl:**

**Fetch All Segments**

{% code lineNumbers="true" %}

```
GET /es/v2/segments/direct?accountId=acc_123&adAccountId=456&connectorId=ab123123789
```

{% endcode %}

**Filter by Segment Name**

{% code lineNumbers="true" %}

```
GET /es/v2/segments/direct?accountId=acc_123&adAccountId=meta_456&connectorId=conn_789&segmentName=customer
```

{% endcode %}

**Fetch by Segment ID**

{% code lineNumbers="true" %}

```
GET /es/v2/segments/direct?accountId=acc_123&adAccountId=meta_456&connectorId=conn_789&segmentId=seg_123&pageSize=100
```

{% endcode %}

<mark style="color:$warning;">**Meta Ads - Not Supported Fields**</mark>

| **Field** | **Description**                       |
| --------- | ------------------------------------- |
| segmentId | Filter on segment id is not supported |


---

# 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://docs.madconnect.ai/deployment-options/madconnect-apis/audience-segments.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.