# Get video

Get public video details, approximate counts and the replay heatmap when the source supplies it. Shorts duration may be null. Transcripts are held.

- Platform: [YouTube](https://docs.upscrape.com/docs/platforms/youtube)
- Capability ID: `youtube.video.get`
- Cost: 1 credit per request
- Maximum runtime: 60 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "capability": "youtube.video.get"
}'
```

## Input


| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes | YouTube video URL or video ID |

### Example input

```json
{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

## Response

Successful output is returned in `results[0].data`.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "available_countries": [
    "AD",
    "AE",
    "AF"
  ],
  "category": "Music",
  "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channel_name": "Rick Astley",
  "channel_subscriber_count": "4.54M subscribers",
  "channel_thumbnail": [
    {
      "height": 48,
      "url": "https://yt3.ggpht.com/[redacted:token]=s48-c-k-c0x00ffffff-no-rj",
      "width": 48
    },
    {
      "height": 88,
      "url": "https://yt3.ggpht.com/[redacted:token]=s88-c-k-c0x00ffffff-no-rj",
      "width": 88
    },
    {
      "height": 176,
      "url": "https://yt3.ggpht.com/[redacted:token]=s176-c-k-c0x00ffffff-no-rj",
      "width": 176
    }
  ],
  "channel_url": "/@RickAstleyYT",
  "date_text": "Oct 24, 2009",
  "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It …",
  "duration_seconds": 213,
  "embed_url": "https://www.youtube.com/embed/dQw4w9WgXcQ",
  "full_description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It …",
  "is_family_safe": true,
  "is_live": false,
  "is_live_content": false,
  "is_private": false,
  "is_unlisted": false,
  "keywords": [
    "rick astley",
    "Never Gonna Give You Up",
    "nggyu"
  ],
  "like_count": 19404903,
  "like_count_a11y": "like this video along with 19,404,903 other people",
  "like_count_text": "19M",
  "metadata_complete": true,
  "most_replayed": {
    "segments": [
      {
        "duration_seconds": 2.14,
        "intensity": 1,
        "start_seconds": 0
      },
      {
        "duration_seconds": 2.14,
        "intensity": 0.4230315549340408,
        "start_seconds": 2.14
      }
    ],
    "video_id": "dQw4w9WgXcQ"
  },
  "publish_date": "2009-10-24T23:57:33-07:00",
  "related_videos": [
    {
      "channel": "Beluga",
      "duration": "3:16",
      "published": "4y ago",
      "title": "Smartest way to RickRoll anyone...",
      "video_id": "UZ7a7ufLllo",
      "views": ""
    },
    {
      "channel": "Madonna",
      "duration": "4:02",
      "published": "16y ago",
      "title": "Madonna - La Isla Bonita (Official Video)",
      "video_id": "zpzdgmqIHOQ",
      "views": ""
    },
    {
      "channel": "Britney Spears",
      "duration": "3:57",
      "published": "16y ago",
      "title": "Britney Spears - ...Baby One More Time (Official Video)",
      "video_id": "C-u5WLJ9Yk4",
      "views": ""
    }
  ],
  "thumbnails": [
    {
      "height": 94,
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLDd2KtelLHaNSXrI9_5K-NvTscKNw",
      "width": 168
    },
    {
      "height": 110,
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg?sqp=-[redacted:token]&rs=AOn4CLBUpEOOWUXWkNyijQuZ4UPzp2BE-w",
      "width": 196
    },
    {
      "height": 138,
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg?sqp=-[redacted:token]==&rs=AOn4CLBCyhr8AqpJ1SxKVU6SyK5ODJ_IpA",
      "width": 246
    }
  ],
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "upload_date": "2009-10-24T23:57:33-07:00",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_id": "dQw4w9WgXcQ",
  "view_count": 1818815735,
  "view_count_text": "1,818,815,735 views"
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `available_countries` | `array` | 3 items |
| `available_countries` | `array` | 3 items |
| `category` | `string` | Music |
| `channel_id` | `string` | UCuAXFkgsw1L7xaCfnd5JJOw |
| `channel_name` | `string` | Rick Astley |
| `channel_subscriber_count` | `string` | 4.54M subscribers |
| `channel_thumbnail` | `array` | 3 items |
| `channel_thumbnail` | `array` | 3 items |
| `channel_url` | `string` | /@RickAstleyYT |
| `date_text` | `string` | Oct 24, 2009 |
| `description` | `string` | The official video for “Never Gonna Give You Up” by Rick Astley.   Neve… |
| `duration_seconds` | `integer` | 213 |
| `embed_url` | `string` | https://www.youtube.com/embed/dQw4w9WgXcQ |
| `full_description` | `string` | The official video for “Never Gonna Give You Up” by Rick Astley.   Neve… |
| `is_family_safe` | `boolean` | true |
| `is_live` | `boolean` | false |
| `is_live_content` | `boolean` | false |
| `is_private` | `boolean` | false |
| `is_unlisted` | `boolean` | false |
| `keywords` | `array` | 3 items |
| `keywords` | `array` | 3 items |
| `like_count` | `integer` | 19404903 |
| `like_count_a11y` | `string` | like this video along with 19,404,903 other people |
| `like_count_text` | `string` | 19M |
| `metadata_complete` | `boolean` | true |
| `most_replayed` | `object` | 2 fields |
| `most_replayed.segments` | `array` | 2 items |
| `most_replayed.video_id` | `string` | dQw4w9WgXcQ |
| `publish_date` | `string` | 2009-10-24T23:57:33-07:00 |
| `related_videos` | `array` | 3 items |
| `related_videos` | `array` | 3 items |
| `thumbnails` | `array` | 3 items |
| `thumbnails` | `array` | 3 items |
| `title` | `string` | Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster) |
| `upload_date` | `string` | 2009-10-24T23:57:33-07:00 |
| `url` | `string` | https://www.youtube.com/watch?v=dQw4w9WgXcQ |
| `video_id` | `string` | dQw4w9WgXcQ |
| `view_count` | `integer` | 1818815735 |
| `view_count_text` | `string` | 1,818,815,735 views |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)