---
title: "获取广告百分位数据/Get ad percentile data"
method: POST
path: "/api/v1/tiktok/ads/get_ad_percentile"
tags: ["TikTok-Ads-API"]
---

# 获取广告百分位数据/Get ad percentile data

`POST /api/v1/tiktok/ads/get_ad_percentile`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/tiktok/ads/get_ad_percentile`
- Auth: HTTP bearer

# [中文]
### 用途:
- 获取广告在同行业中的百分位排名数据
- 了解广告在各项指标上相对于同行的表现水平
- 帮助评估广告效果并制定优化策略

### 参数:
- material_id: 广告素材ID，必填参数
- metric: 分析指标，可选值：
  - ctr_percentile: 点击率百分位（默认）
  - time_attr_conversion_rate_percentile: 时间归因转化率百分位
  - click_cnt_percentile: 点击次数百分位
  - time_attr_convert_cnt_percentile: 时间归因转化次数百分位
  - show_cnt_percentile: 展示次数百分位
- period_type: 时间范围(天)，默认180天
- cookie: 自定义Cookie字符串，可选参数，可以使用自己的Cookie来获取更多数据

### 返回内容说明:
- `percentile_data`: 百分位数据
  - `ctr_percentile`: 点击率百分位（0-100）
  - `cvr_percentile`: 转化率百分位
  - `engagement_percentile`: 互动率百分位
  - `view_percentile`: 观看量百分位
  - `industry_average`: 行业平均值对比

### 示例响应:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_percentile",
  "params": {
    "material_id": "7213258221116751874"
  },
  "data": {
    "percentile_data": {
      "ctr_percentile": 85,
      "cvr_percentile": 72,
      "engagement_percentile": 90,
      "view_percentile": 88,
      "industry_average": {
        "ctr": 2.5,
        "cvr": 1.2,
        "engagement": 5.8
      }
    }
  }
}
```

# [English]
### Purpose:
- Get ad percentile ranking data within the industry
- Understand ad performance levels relative to peers across various metrics
- Help evaluate ad effectiveness and develop optimization strategies

### Parameters:
- material_id: Ad material ID, required parameter
- metric: Analysis metric, options:
  - ctr_percentile: CTR percentile (default)
  - time_attr_conversion_rate_percentile: Time-attributed conversion rate percentile
  - click_cnt_percentile: Click count percentile
  - time_attr_convert_cnt_percentile: Time-attributed conversion count percentile
  - show_cnt_percentile: Impression count percentile
- period_type: Time period in days, default 180
- cookie: Custom Cookie string, optional parameter, can be used to fetch more data

### Return Description:
- `percentile_data`: Percentile data
  - `ctr_percentile`: Click-through rate percentile (0-100)
  - `cvr_percentile`: Conversion rate percentile
  - `engagement_percentile`: Engagement rate percentile
  - `view_percentile`: View count percentile
  - `industry_average`: Industry average comparison

### Example Response:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_percentile",
  "params": {
    "material_id": "7213258221116751874"
  },
  "data": {
    "percentile_data": {
      "ctr_percentile": 85,
      "cvr_percentile": 72,
      "engagement_percentile": 90,
      "view_percentile": 88,
      "industry_average": {
        "ctr": 2.5,
        "cvr": 1.2,
        "engagement": 5.8
      }
    }
  }
}
```

## Request body

- BodyGetAdPercentileApiV1TiktokAdsGetAdPercentilePost
  - `material_id` string, required: 广告素材ID/Ad material ID
  - `metric` string: 分析指标/Analysis metric (ctr_percentile, time_attr_conversion_rate_percentile, click_cnt_percentile, time_attr_convert_cnt_percentile, show_cnt_percentile)
  - `period_type` integer: 时间范围(天)/Time period (days)
  - `cookie` string: 自定义Cookie字符串（可选）

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-01** `50f9ec6e1cd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/tiktok/ads/get_ad_percentile/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)