> For the complete documentation index, see [llms.txt](https://docs.madconnect.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madconnect.ai/deployment-options/madconnect-apis/audience-segments.md).

# 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 |