TikTok Ad Interactive Analysis (Retention/CTR Curve by Material ID)

{
  "type": "object",
  "required": [
    "material_id"
  ],
  "properties": {
    "cookie": {
      "type": "string",
      "description": "Optional session cookie, only needed to analyze a private/account-scoped ad you control. Leave empty for a public ad."
    },
    "material_id": {
      "type": "string",
      "description": "The TikTok ad's material ID, the same numeric ID shown for the ad in TikTok Ads Manager / Creative Center."
    },
    "metric_type": {
      "type": "string",
      "default": "remain",
      "description": "Which engagement metric to analyze: remain (viewer retention, the default), ctr (click-through rate), cvr (conversion rate), clicks, or conversion."
    },
    "period_type": {
      "type": "integer",
      "default": 180,
      "description": "Lookback window for the analysis, in days."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "keyframe": {
      "type": "object",
      "properties": {
        "msg": {
          "type": "string",
          "description": "'OK' on both real calls observed."
        },
        "code": {
          "type": "number",
          "description": "0 on both real calls observed (success)."
        },
        "data": {
          "type": "object",
          "properties": {
            "analysis": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "number",
                    "description": "The metric's value at that second (e.g. a retention fraction for remain, a click-through rate for ctr). Observed as 0 on both real calls."
                  },
                  "second": {
                    "type": "number",
                    "description": "Second offset from the video start."
                  }
                },
                "additionalProperties": true
              },
              "description": "One entry per second of the video, in order. Every value was 0 across both real calibration calls (an older/lower-traffic ad) -- a genuine flat curve for that ad, not an error; a higher-traffic ad is expected to show nonzero values here."
            },
            "duration": {
              "type": "number",
              "description": "Total video duration in seconds covered by `analysis` (60 on both real calls)."
            },
            "highlight": {
              "type": "array",
              "items": {},
              "description": "Notable highlighted seconds/segments in the curve. Empty on both real calls observed; the shape of a populated entry was not confirmed."
            }
          },
          "additionalProperties": true
        }
      },
      "description": "The per-second engagement time series for the chosen metric_type.",
      "additionalProperties": true
    },
    "percentile": {
      "type": "object",
      "properties": {
        "msg": {
          "type": "string",
          "description": "'OK' on both real calls observed."
        },
        "code": {
          "type": "number",
          "description": "0 on both real calls observed (success)."
        },
        "data": {
          "type": "object",
          "properties": {
            "ctr_percentile": {
              "type": "number",
              "description": "Percentile rank (0-1) for the ctr metric. Present when metric_type=ctr; observed 0.99."
            },
            "show_cnt_percentile": {
              "type": "number",
              "description": "Percentile rank (0-1) for the remain/retention metric. Present when metric_type=remain; observed 0.99."
            }
          },
          "description": "The percentile key name matches the metric requested -- observed as `show_cnt_percentile` for metric_type=remain and `ctr_percentile` for metric_type=ctr. The other metric_type values (cvr, clicks, conversion) were not captured and presumably use a differently-named key here.",
          "additionalProperties": true
        }
      },
      "description": "A percentile-rank benchmark for the chosen metric_type against other ads.",
      "additionalProperties": true
    }
  },
  "description": "The interactive-analysis document, as returned at routing.responseResultPath ($.output).",
  "additionalProperties": true
}