> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keyapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive time analysis

> Interactive time analysis(CTR,CVR,Clicks,Conversion,Remain)。Used in conjunction with `/v1/tk-ads/top_ads_detail`.

<div className="inline-flex items-center gap-2 px-4 py-2 bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg">
  <span className="text-sm font-medium text-yellow-900 dark:text-yellow-100"><span className="font-semibold">2 credits</span><span className="text-yellow-700 dark:text-yellow-300 ml-1">per request</span></span>
</div>

## Copy for AI

<div className="my-6 rounded-xl border border-gray-200 bg-gray-50 p-5 dark:border-gray-800 dark:bg-gray-900/40">
  <div className="min-w-0">
    <p className="text-base font-semibold text-gray-900 dark:text-gray-100">Why Code When AI Can Do It For You?</p>
    <p className="mt-1 text-sm text-gray-700 dark:text-gray-300">Stop writing code like it's 1970! Let AI do the heavy lifting - click the button to copy a perfectly formatted prompt for ChatGPT, Claude, or your favorite AI assistant.</p>
  </div>

  <div className="mt-4">
    <button
      type="button"
      className="inline-flex items-center gap-2 rounded-md border border-emerald-300 bg-emerald-50 px-3 py-2 text-sm font-medium text-emerald-800 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-100 dark:hover:bg-emerald-900/50"
      onClick={() => navigator.clipboard.writeText(`I need to call the following KeyAPI endpoint. Please generate a complete and directly runnable Python example based on the API information provided below.

## API Information

Endpoint: GET https://api.keyapi.ai/v1/tk-ads/interactive_time_analysis
Summary: Interactive time analysis

Required Headers:
- Authorization: Bearer <YOUR_API_KEY>

Parameters:
- material_id (Required): No description. Example: 7552078920880619527
- metric (Optional): Available values: 
retain_ctr = Click-through rate (CTR) measures the percentage of viewers who clicked the ad while watching at every second. It is calculated by dividing the number of clicks by the number of views.
retain_cvr = Conversion rate (CVR) measures the percentage of conversions created (such as follows, downloads, or purchases) at every second of the video. It is calculated by dividing the number of conversions by the number of interactions.
click_cnt = The number of clicks the ad received.
convert_cnt = Conversions The number of conversions generated.
play_retain_cnt = Retention The number of users still watching the ad.


## Code Requirements

- Use the Python \`requests\` library
- Provide a complete and directly runnable example
- Handle HTTP request errors, timeouts, and non-2xx responses
- Handle JSON parsing errors
- Prefer the Example values provided in the API information for sample parameters
- Keep the code simple and avoid unnecessary abstractions or complexity
`)}
    >
      <span>Copy for AI</span>
    </button>
  </div>
</div>


## OpenAPI

````yaml en/tiktok-ads-library.openapi.json GET /v1/tk-ads/interactive_time_analysis
openapi: 3.0.1
info:
  title: Tiktok-ads API english documentation
  description: >-
    The english reference documentation of the Tiktok-ads API includes the
    interface's purpose, parameter description, response status, and sample
    structure.
  version: 1.0.0
servers:
  - url: https://api.keyapi.ai
    description: Production-KeyAPI
security: []
tags: []
paths:
  /v1/tk-ads/interactive_time_analysis:
    get:
      tags: []
      summary: Interactive time analysis
      description: >-
        Interactive time analysis(CTR,CVR,Clicks,Conversion,Remain)。Used in
        conjunction with `/v1/tk-ads/top_ads_detail`.
      parameters:
        - name: material_id
          in: query
          description: ''
          required: true
          example: '7552078920880619527'
          schema:
            type: string
            example: '7552078920880619527'
        - name: metric
          in: query
          description: >2-
             Available values: 
            retain_ctr = Click-through rate (CTR) measures the percentage of
            viewers who clicked the ad while watching at every second. It is
            calculated by dividing the number of clicks by the number of views.

            retain_cvr = Conversion rate (CVR) measures the percentage of
            conversions created (such as follows, downloads, or purchases) at
            every second of the video. It is calculated by dividing the number
            of conversions by the number of interactions.

            click_cnt = The number of clicks the ad received.

            convert_cnt = Conversions The number of conversions generated.

            play_retain_cnt = Retention The number of users still watching the
            ad.
          required: false
          schema:
            type: string
            enum:
              - retain_ctr
              - retain_cvr
              - click_cnt
              - convert_cnt
              - play_retain_cnt
            default: retain_ctr
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      analysis:
                        type: array
                        items:
                          type: string
                      highlight:
                        type: array
                        items:
                          type: string
                        description: >-
                          ·Highlight frames· are time frames in the video that
                          performed well in specific metrics, indicating higher
                          value, and are recommended to be used as a preview at
                          the beginning of the video. For this video, the
                          highlight frames for CTR occur at 1, 9 and 13 seconds.
                    required:
                      - highlight
                      - analysis
                required:
                  - data
              example:
                code: 0
                message: success
                data:
                  analysis:
                    - second: 0
                      value: 0.05674191580231849
                    - second: 1
                      value: 1
                    - second: 2
                      value: 0.3881286498736163
                    - second: 3
                      value: 0.23097707661466052
                    - second: 4
                      value: 0.16935413579708883
                    - second: 5
                      value: 0.1273424562015166
                    - second: 6
                      value: 0.1087771289113571
                    - second: 7
                      value: 0.10790551730149045
                    - second: 8
                      value: 0.09221650832389088
                    - second: 9
                      value: 0.0956157936023708
                    - second: 10
                      value: 0.08785845027455766
                    - second: 11
                      value: 0.0784450448879979
                    - second: 12
                      value: 0.06545803190098493
                    - second: 13
                      value: 0.06833435021354484
                    - second: 14
                      value: 0.06554519306197158
                    - second: 15
                      value: 0.11278654231674365
                  duration: 16
                  highlight:
                    - 1
                    - 9
                    - 13
                requestId: 32bc651e-3d88-4663-8fed-75e9a97782d7
          headers: {}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      deprecated: false
      security:
        - JWT Bearer: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://api.keyapi.ai/v1/tk-ads/interactive_time_analysis?material_id=7552078920880619527&metric=retain_ctr' \
              --header 'Authorization: Bearer <YOUR_API_KEY>'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.get(
                'https://api.keyapi.ai/v1/tk-ads/interactive_time_analysis',
                params={"material_id":"7552078920880619527","metric":"retain_ctr"},
                headers={'Authorization': 'Bearer <YOUR_API_KEY>'}
            )
            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const params = new
            URLSearchParams({"material_id":"7552078920880619527","metric":"retain_ctr"});


            const response = await
            fetch(`https://api.keyapi.ai/v1/tk-ads/interactive_time_analysis?${params}`,
            {
              method: 'GET',
              headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
            });

            const data = await response.json();

            console.log(data);
components:
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            example:
              code: 400
              data: null
              message: 'Missing required parameter: handle'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            example:
              code: 401
              data: null
              message: apiKey is null
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            example:
              code: 402
              data: null
              message: apiKey quota is not enough
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            example:
              code: 429
              data: null
              message: qps limit exceeded
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            example:
              code: 500
              data: null
              message: Internal server error
  securitySchemes:
    JWT Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |-
        API key for authentication. Format: `sk_live_xxxxxxxxxxxxx`
        Get your API key from the [Dashboard](http://keyapi.ai/app/dashboard).

````