← 返回目录
📁 API Reference › Audience

获取受众详情

您可以使用本接口获取指定受众群体的详细信息，包括受众群体当前状态以及历史操作记录详情。该接口将返回属于您的受众和与您分享的受众。您可以使用is_creator查看您是否为该受众的拥有者。

注意
单次请求最多获取 100 个受众群体的详细信息。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/dmp/custom_audience/get/|/v1.3/dmp/custom_audience/get/| |请求参数类型|advertiser_id: number<br>custom_audience_ids: number[]|advertiser_id: string<br>custom_audience_ids: string[]| |新增请求参数|/|history_size: number| |新增返回参数|/|shared: boolean<br>is_creator: boolean<br>create_time: string<br>owner_id: string<br>lookalike_spec: object[]<br> source_audience_id: string<br>include_source: boolean<br>mobile_os: string<br>placements: string<br>location_ids: string[]<br>audience_size: string |返回参数数据类型|audience_id: number|audience_id: string |返回参数类型|audience_id: number|audience_id`: string|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/get/

**方法** GET

**Header**

``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|

参数

|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|custom_audience_ids {必填}|string[]|受众群体ID列表，长度范围：`[1,100]`。|
|history_size|number|用户请求的历史数据的大小。|

示例

(code curl http)
curl --get -H "Access-Token:xxx" \\
--data-urlencode "advertiser_id=ADVERTISER_ID" \\
--data-urlencode "custom_audience_ids=[\"CUSTOM_AUDIENCE_IDS\"]" \\
https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/get/
(/code)

返回

|字段{40%}|类型{15%}|描述{45%}|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data|object|返回数据。|
#|list |object[]|受众群体详情列表。|
##|audience_details |object|受众群体数据。|
###|audience_id |string|受众群体ID。|
###|msg |string|受众状态信息。|
###|audience_sub_type|string| 受众子类型，表明可以使用的广告类型。枚举值：`NORMAL`: 常规受众，可用于非覆盖和频次广告。`REACH_FREQUENCY`: 覆盖和频次广告受众，只可用于覆盖和频次广告。|
###|error_msg |string|创建、修改受众群体时的失败信息。|
###|is_valid |boolean|受众群体是否可用。计算中或已过期的受众群体不可用。|
###|is_expiring|boolean|受众群体是否即将过期。受众群体会在过期时间的60天内进入即将过期状态。
###|expired_time|string|受众群体过期时间。时间格式为“YYYY-MM-DD HH:MM:SS"。|
###|name |string|受众群体名称。|
###|rule|string|如果受众群体属于广告互动、应用活动或网站访客受众，此字段代表受众创建规则。|
###|is_auto_refresh |boolean|如果受众群体属于广告互动、应用活动或网站访客受众，此字段代表是否启用了受众群体每日自动更新功能。|
###|shared |boolean|是否是共享的受众群体ID。枚举值：`True`，`False`。
###|is_creator |boolean|广告主是否是受众的拥有者。枚举值：`true`，`false`。 您可以使用`shared` 和 `is_creator` 查看广告主的所属情况和分享状态。规则如下：<br>1. `shared` = `true` 且 `is_creator` = `true`：广告主是该受众的拥有者，且该受众由广告主分享给其他账户。<br>2. `shared` = `true` 且 `is_creator` = `false`：广告主不是该受众的拥有者，该受众由其他账户分享给广告主。<br>3. `shared` = `false` 且 `is_creator` = `true`：广告主是该受众的拥有者，且该受众未与其他人共享。 
###|owner_id|string|受众拥有者的广告主ID。<ul><li> 若`is_creator`=`true`，`owner_id`为您在请求中指定的`advertiser_id`。</li><li> 若`is_creator`=`false`，`owner_id`为创建该受众的广告主ID。</li></ul>|
###|create_time|string|受众创建时间，格式为 "YYYY-MM-DD HH:MM:SS"。
###|type |string|受众群体类型。 枚举值：<br><ul><li>`Customer File Audience` ([客户文件受众](https://ads.tiktok.com/help/article?aid=6721963343558475781))。</li><li>`Engagement Audience` ([广告互动受众](https://ads.tiktok.com/help/article?aid=6721963298155134982))。</li><li>`App Activity Audience` ([应用活动受众](https://ads.tiktok.com/help/article?aid=6721962999092871173))。</li><li>`Website Audience` ([网站访客受众)](https://ads.tiktok.com/help/article?aid=6721962903081058309))。 </li><li>`Lookalike Audience` ([相似受众](https://ads.tiktok.com/help/article?aid=6746381707865227270))。</li><li>`Lead Generation `([线索收集受众](https://ads.tiktok.com/help/article/lead-generation-audience?lang=zh))</li><li>`Rule Business Account` ([企业号受众](https://ads.tiktok.com/help/article?aid=10011405&redirected=1))</li><li>`Rule ad shop` （[商店活动受众](https://ads.tiktok.com/help/article/shop-retargeting?lang=zh)）</li><li>`Partner` （合作伙伴受众）</li><li>`Challenge` (非标互动受众) </li><li>`Preferred Population` (优选人群受众)</li></ul><p><span style="color:darkred"><b>注意</b></span>：当前，无法通过API创建合作伙伴受众，非标互动受众和优选人群受众。 |
###|cover_num |number|覆盖人数。即TikTok上匹配的用户人数。|
###|calculate_type |string |加密类型。枚举值详见[枚举值-加密类型](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|lookalike_spec |object|相似受众群体的参数。|
####|source_audience_id|string|种子受众ID。|
####|include_source|boolean|是否包含种子受众群体。|
####|mobile_os|string|操作系统。枚举值：`ALL`：支持iOS和安卓， `ANDROID`：仅支持安卓，`IOS`：仅支持iOS。具体请查看[枚举值-相似人群手机系统](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
####|placements|string|投放平台。枚举值：`TikTok`, `TopBuzz & BuzzVideo`，`Pangle`。详见[枚举值-相似受众版位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
####|location_ids|string[]|投放地区。具体请查看[枚举值-相似受众地点](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
####|audience_size|string|相似受众的大小。枚举值：`NARROW`, `BALANCED`，`BROAD`。具体请查看[枚举值-相似受众大小](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
##|audience_history |object[]|受众群体变更历史列表。|
###|action |string|变更行为。欲了解枚举值含义，请查看下文<strong>"`action` 值与通过/dmp/custom_audience/update/的操作的映射关系" </strong>小节。|
###|action_detail |string|操作详情。|
###|editor |string|操作者。如果是通过TikTok API for Business上传的，那么值是"open_api"。|
###|msg |string |部分成功时的失败信息。比如：文件中部分数据解析失败。 |
###|opt_time |string|操作时间。格式如：2019-04-14 06:52:56。|
|request_id |string|请求的日志id，唯一标识一个请求。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
"message": "OK",
    "code": 0,
    "data": {
        "list": [
            {
                "audience_details": {
                    "audience_id": 124793922,
                    "name": "custom-audience-2838",
                    "type": "Customer File Audience",
                    "rule": "{\"inclusions\": null, \"exclusions\": null}",
                    "error_msg": null,
                    "calculate_type": "FIRST_NORMAL",
                    "is_valid": false,
                    "is_auto_refresh": false,
                    "msg": null,
                    "is_expiring": false,
                    "cover_num": 7,
                    "expired_time": "2037-12-31 16:00:00",
                    "owner_id": "{{owner_id}}",
                     "lookalike_spec": null
                },
                "audience_history": [
                    {
                        "msg": null,
                        "opt_time": "2021-07-15 16:34:43",
                        "editor": "open_api",
                        "action": "Create Audience",
                        "action_detail": "7"
                    }
                ]
            }
        ]
    },
    "request_id": "202107160034480102450491835D2068E9"
}
(/code);

action 值与通过/dmp/custom_audience/update/的操作的映射关系

| <code>action</code>值{25%} | 描述{35%} | 对应通过/dmp/custom_audience/update/进行的操作{40%} |
|---|---|---|
| `modify` | 修改了自定义受众的名称。 | 传入了`custom_audience_name ` |
| `upload - replace` | 上传文件替换了原始客户文件受众数据 | 传入了`file_paths` ，且未传入`action`或将 `action`设置为`REPLACE` |
| `upload - add` | 上传文件扩充了原始客户文件受众数据 | 传入了`file_paths `，且将 `action`设置为`APPEND` |
| `upload remove` | 上传文件删除了原始客户文件受众数据 | 传入了`file_paths` ，且将 `action`设置为`REMOVE` |
| `convert_to_rf` | 允许在覆盖和频次推广系列中使用此自定义受众 | 传入了`audience_sub_type`，且将其设置为`REACH_FREQUENCY` |
← 刷新相似受众分享受众 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →