# Get most replayed moments



<MethodPage method="GET" path="/v1/videos/{id}/heatmap" credits={1}>
  Returns YouTube's "most replayed" graph for a video, condensed: the most replayed moment, up to five peaks and the whole graph averaged into 20 parts. It shows where viewers rewatch or skip to, the only public hint of how a video holds attention. **1 credit** per successful response.

  Intensity is relative to the video's own most replayed moment (1.0), so compare shapes between videos, not values. The first seconds are high on most videos because every view starts there.

  <Callout type="info" title="Credits">
    Successful responses deduct 1 credit. YouTube shows the graph only on videos with enough views; a video without one returns `404 heatmap_unavailable` and costs nothing.
  </Callout>

  <Security permission="videos:read" />

  <SchemaGroup title="Path Parameters">
    <SchemaField name="id" type="string" location="path" required>
      11-character YouTube video ID or video URL.
    </SchemaField>
  </SchemaGroup>

  <div id="returns" className="mt-8">
    Response (HTTP 200) [#response-http-200]

    ```jsonc
    {
      "video_id": string,
      "length_seconds": number,
      "most_replayed": {             // YouTube's "Most replayed" label, when shown
        "start_seconds": number,
        "end_seconds": number,
        "intensity": number,
        "label": string
      },
      "peaks": [                     // Up to 5 strongest peaks, in time order
        { "start_seconds": number, "end_seconds": number, "intensity": number }
      ],
      "curve": [                     // 20 parts covering the whole video
        { "start_seconds": number, "end_seconds": number, "intensity": number } // 0 to 1
      ]
    }
    ```
  </div>

  <MethodSamples>
    <LanguageSample language="cURL">
      ```bash
      curl -X GET "https://api.ytapi.dev/v1/videos/dQw4w9WgXcQ/heatmap" \
        -H "Authorization: Bearer $YT_API_KEY"
      ```
    </LanguageSample>

    <LanguageSample language="TypeScript">
      ```ts
      const id = "dQw4w9WgXcQ";
      const response = await fetch(`https://api.ytapi.dev/v1/videos/${id}/heatmap`, {
        headers: {
          Authorization: `Bearer ${process.env.YT_API_KEY}`,
        },
      });

      if (response.status === 404) {
        console.log("No most replayed graph for this video");
      } else {
        const heatmap = await response.json();
        for (const p of heatmap.peaks) {
          console.log(`https://www.youtube.com/watch?v=${id}&t=${Math.floor(p.start_seconds)}`);
        }
      }
      ```
    </LanguageSample>

    <LanguageSample language="Python">
      ```python
      import os
      import requests

      video_id = "dQw4w9WgXcQ"
      response = requests.get(
          f"https://api.ytapi.dev/v1/videos/{video_id}/heatmap",
          headers={"Authorization": f"Bearer {os.environ['YT_API_KEY']}"},
      )
      if response.status_code == 404:
          print("No most replayed graph for this video")
      else:
          for p in response.json()["peaks"]:
              print(f"https://www.youtube.com/watch?v={video_id}&t={int(p['start_seconds'])}")
      ```
    </LanguageSample>

    <LanguageSample language="Go">
      ```go
      package main

      import (
      	"fmt"
      	"net/http"
      	"os"
      )

      func main() {
      	req, _ := http.NewRequest("GET", "https://api.ytapi.dev/v1/videos/dQw4w9WgXcQ/heatmap", nil)
      	req.Header.Set("Authorization", "Bearer "+os.Getenv("YT_API_KEY"))

      	resp, err := http.DefaultClient.Do(req)
      	if err != nil {
      		panic(err)
      	}
      	defer resp.Body.Close()
      	fmt.Println(resp.Status)
      }
      ```
    </LanguageSample>
  </MethodSamples>
</MethodPage>