---
title: "Retrieve TikTok Top Ads interactive time analysis"
method: GET
path: "/tiktok/top-ads/analysis"
tags: ["TikTok", "TikTok Top Ads"]
---

# Retrieve TikTok Top Ads interactive time analysis

`GET /tiktok/top-ads/analysis`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/tiktok/top-ads/analysis`
- Auth: API key in header `x-api-key`

Returns the detail-page interactive time analysis chart and percentile for a Top Ads material. Metric values are `retain_ctr` (CTR), `retain_cvr` (CVR), `click_cnt` (Clicks), `convert_cnt` (Conversion), and `play_retain_cnt` (Remain).

## Query parameters

- `material_id` string, required
- `metric` 'retain_ctr' | 'retain_cvr' | 'click_cnt' | 'convert_cnt' | 'play_retain_cnt'
- `period_type` 7 | 30 | 180

## Headers

- `x-api-key` string, required

## Response `200`

OK

- PopulartrendTopAdsAnalysisResponseDoc
  - `code` integer
  - `data` PopularTrendTopAdsAnalysisResp
    - `code` integer
    - `data` object: Time analysis of the ad for the chosen metric, with its percentile, chart points and highlighted seconds.
      - `analysis` PopularTrendTopAdsAnalysisPoint[]
        - `second` integer: Second of the ad video the point refers to.
        - `value` number: Value of the selected metric at that second.
      - `duration` number
      - `highlight` integer[]
      - `metric` string
      - `metric_label` string
      - `percentile` number
      - `percentile_data` object
      - `percentile_metric` string
      - `period_type` integer
    - `msg` string
    - `request_id` string: Request id returned by TikTok Creative Center.
  - `msg` string

## Other responses

- `400`: Invalid input
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)