← 返回目录
📁 API Reference › Custom Conversions

获取与事件源关联的自定义转化

您可以使用本接口检索与 Pixel 或应用关联的自定义转化。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/custom_conversion/list/

方法 GET

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](1738373164380162.html)接口获取。|

参数

|字段{30%}|类型{15%}|描述{55%}|
|--- |--- |--- |
|advertiser_id {必填}|string|广告主 ID。|
|event_source_type {必填}|string|事件源类型。<br><br>枚举值:<ul><li>`PIXEL`: Pixel。</li><li>`APP`: 应用。</li></ul>|
|event_source_id {必填}|string|事件源 ID。<br><br><ul><li>当 `event_source_type` 为 `PIXEL` 时，指定一个 Pixel ID。<ul><li>要获取广告账户中的 Pixel ID，可使用[/pixel/list/](1740858697598978.html)并检查返回的`pixel_id`。</li></ul></li><li>当 `event_source_type` 为 `APP` 时，指定自归因网络应用的应用平台 ID。<ul><li>要获取广告账户中自归因应用的应用平台 ID，可使用[/app/list/](1740859313270786.html)。确认应用的 `self_attribution_enabled` 返回值为 `true` 并检查返回的 `app_platform_id`。</li></ul></li></ul>|
|search_keyword|string|用于搜索自定义转化的关键字。<br>您可以通过自定义转化名称或自定义转化 ID 进行搜索。<br><br><ul><li>按自定义转化名称搜索时，支持模糊匹配。</li><li>按自定义转化 ID 搜索时，支持精确匹配。</li></ul>|
|sort_field|string|排序字段。<br><br>枚举值:<ul><li>`CREATE_TIME`: 自定义转化的创建时间。</li><li>`TOTAL_COUNT`: 自定义转化的总转化数。</li></ul>默认值: `CREATE_TIME`。|
|sort_type|string|排序类型。<br><br>枚举值:<ul><li>`DESC`: 降序。</li><li>`ASC`: 升序。</li></ul>默认值: `DESC`。|
|page|number|当前页数。<br><br>取值范围: ≥ 1。<br>默认值: 1。|
|page_size|number|页面大小。<br><br>取值范围: 1-1,000。<br>默认值: 10。|

示例

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/custom_conversion/list/?advertiser_id={{advertiser_id}}&event_source_type=PIXEL&event_source_id={{event_source_id}}&page=1&page_size=1000' \
--header 'Access-token: {{Access-token}}'
(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见[附录-返回码](1737172488964097.html)。 |
|message|string|返回信息。更多信息参见[附录-返回码](1737172488964097.html)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。  |
|data|object|返回数据。|
#|list|object[]|与事件源关联的自定义转化列表。|
##|custom_conversion_id|string|自定义转化的 ID。|
##|name|string|自定义转化的名称。|
##|description|string|自定义转化的描述。|
##|event_source_type|string|事件源类型。<br><br>枚举值:<ul><li>`PIXEL`: Pixel。</li><li>`APP`: 应用。</li></ul>|
##|event_source_id|string|事件源 ID。<br><br><ul><li>当 `event_source_type` 为 `PIXEL` 时，指定一个 Pixel ID。<ul><li>要获取广告账户中的 Pixel ID，可使用[/pixel/list/](1740858697598978.html)并检查返回的`pixel_id`。</li></ul></li><li>当 `event_source_type` 为 `APP` 时，指定自归因网络应用的应用平台 ID。<ul><li>要获取广告账户中自归因应用的应用平台 ID，可使用[/app/list/](1740859313270786.html)。确认应用的 `self_attribution_enabled` 返回值为 `true` 并检查返回的 `app_platform_id`。</li></ul></li></ul>|
##|activity_info|object|自定义转化的活动的详情。|
###|activity_status|string|自定义转化的活跃状态。<br><br>枚举值:<ul><li>`NO_RECENT_ACTIVITY`: 近期无活动。已收到回传活动，但并非是在过去 7 天内收到。</li><li>`ACTIVE`: 活跃。在过去 7 天内收到回传活动。</li><li>`WAITING_FOR_ACTIVITY`: 不活跃。过去 90 天内未收到回传活动。</li></ul>|
###|total_count|number|自定义转化的总转化数。|
###|last_record_time|string|上次收到自定义转化活动的时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC+0)。<br><br>示例: `2025-01-01 00:00:01`。|
##|optimization_event|string|与自定义转化关联的转化事件（标准事件）。<br><br>枚举值参阅 [`optimization_event` 的可选值](https://business-api.tiktok.com/portal/docs?id=1842225226006530#item-link-optimization_event%20的可选值)。|
##|rules|object[]|自定义转化的转化规则详情。<br><br>只有满足这些条件的操作才会计为自定义转化。|
###|parameter|string|参数。<br><br>枚举值:<ul><li>`BRAND`: `brand`。</li><li>`CONTENT_CATEGORY`: `content_category`。</li><li>`CONTENT_ID`: `content_id`。</li><li>`CONTENT_NAME`: `content_name`。</li><li>`CONTENT_TYPE`: `content_type`。</li><li>`CURRENCY`: `currency`。</li><li>`DESCRIPTION`: `description`。</li><li>`EVENT_ID`: `event_id`。</li><li>`NUM_ITEMS`: `num_items`。</li><li>`PRICE`: `price`。</li><li>`SEARCH_STRING`: `search_string`。</li><li>`STATUS`: `status`。</li><li>`URL`: `url`。</li><li>`VALUE`: `value`。</li></ul>|
###|operator|string|运算符。<br><br><ul><li>当 `parameter` 为 `BRAND`、`CONTENT_CATEGORY`、`CONTENT_ID`、`CONTENT_NAME`、`CONTENT_TYPE`、`DESCRIPTION`、`EVENT_ID`、`SEARCH_STRING`、`STATUS` 或 `URL` 时，枚举值为:<ul><li>`CONTAIN`: 包含。</li><li>`NOT_CONTAIN`: 不包含。</li><li>`START_WITH`: 开头是。</li><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li></ul></li><li>当 `parameter` 为 `NUM_ITEMS`、`PRICE` 或 `VALUE` 时，枚举值为:<ul><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li><li>`LT`: 小于。</li><li>`GT`: 大于。</li><li>`LTE`: 小于或等于。</li><li>`GTE`: 大于或等于。</li></ul></li><li>当 `parameter` 为 `CURRENCY` 时，枚举值为:<ul><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li></ul></li></ul>|
###|values|string[]|参数的值。<br><br><ul><li>当 `parameter` 为 `BRAND`、`CONTENT_CATEGORY`、`CONTENT_ID`、`CONTENT_NAME`、`CONTENT_TYPE`、`DESCRIPTION`、`EVENT_ID`、`SEARCH_STRING`、`STATUS`、`URL` 时，该字段将是一个字符串数组，每个字符串的最大长度为 100 个字符，最多 100 个条目。</li><li>当 `parameter` 为 `NUM_ITEMS` 时，该字段将是一个介于 0 和 1,000,000,000 之间的整数。</li><li>当 `parameter` 为 `PRICE`、`VALUE` 时，该字段将是一个保留两位小数的浮点数，取值范围为 0.00到 1,000,000,000.00。</li><li>当 `parameter` 为 `CURRENCY` 时，该字段将是一个字符串数组。要了解枚举值，请参阅[币种的可选值](https://business-api.tiktok.com/portal/docs?id=1842225226006530#item-link-币种的可选值)。|
###|create_time|string|自定义转化的创建时间，格式为`YYYY-MM-DD HH:MM:SS`(UTC+0)。<br><br>示例: `2025-01-01 00:00:01`。|
###|update_time|string|自定义转化上次更新的时间，格式为`YYYY-MM-DD HH:MM:SS`(UTC+0)。<br><br>示例: `2025-01-01 00:00:01`。|
#|page_info|object|分页信息。|
##|page|number|当前页码。|
##|page_size|number|页面大小。|
##|total_number|number|总结果数。|
##|total_page|number|总页数。|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "activity_info": {
                    "activity_status": "WAITING_FOR_ACTIVITY",
                    "total_count": 0
                },
                "create_time": "{{create_time}}",
                "custom_conversion_id": "{{custom_conversion_id}}",
                "description": "{{description}}",
                "event_source_id": "{{event_source_id}}",
                "event_source_type": "PIXEL",
                "name": "{{name}}",
                "optimization_event": "SHOPPING",
                "rules": [
                    {
                        "operator": "NOT_CONTAIN",
                        "parameter": "EVENT_ID",
                        "values": [
                            "{{event_id}}",
                            "{{event_id}}"
                        ]
                    },
                    {
                        "operator": "START_WITH",
                        "parameter": "DESCRIPTION",
                        "values": [
                            "{{description_value}}"
                        ]
                    }
                ],
                "update_time": "{{update_time}}"
            },
            {
                "activity_info": {
                    "activity_status": "NO_RECENT_ACTIVITY",
                    "last_record_time": "{{last_record_time}}",
                    "total_count": 1
                },
                "create_time": "{{create_time}}",
                "custom_conversion_id": "{{custom_conversion_id}}",
                "description": "",
                "event_source_id": "{{event_source_id}}",
                "event_source_type": "PIXEL",
                "name": "{{name}}",
                "optimization_event": "ON_WEB_CART",
                "rules": [
                    {
                        "operator": "CONTAIN",
                        "parameter": "CONTENT_ID",
                        "values": [
                            "{{content_id}}"
                        ]
                    }
                ],
                "update_time": "{{update_time}}"
            },
            ...
            {
                "activity_info": {
                    "activity_status": "ACTIVE",
                    "last_record_time": "{{last_record_time}}",
                    "total_count": 20
                },
                "create_time": "{{create_time}}",
                "custom_conversion_id": "{{custom_conversion_id}}",
                "description": "",
                "event_source_id": "{{event_source_id}}",
                "event_source_type": "PIXEL",
                "name": "{{name}}",
                "optimization_event": "SHOPPING",
                "rules": [
                    {
                        "operator": "CONTAIN",
                        "parameter": "STATUS",
                        "values": [
                            "{{status_value}}"
                        ]
                    }
                ],
                "update_time": "{{update_time}}"
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 1000,
            "total_number": 98,
            "total_page": 1
        }
    }
}
(/code)
← 自定义转化删除自定义转化 →

内容来源：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 每日平台更新简报 →