# Supadata

> Turn videos and web pages into text. Get the transcript of a video on YouTube, TikTok, Instagram, X or Facebook, the details and numbers behind a post, whatever an AI can see in a video, and any web page as clean readable text.

App · Video & Audio · 10 actions. Web page: https://docs.lodol.com/docs/integrations/supadata

## Actions

### Get a transcript that was still being made

Read back a transcript Supadata was still working on. 'Get a video transcript' waits for it and almost always returns it outright; a video hours long with no captions can still be going when the step ends, and then it returns a job reference for this step to finish with.

**Inputs**

- Job reference (`job_id`, text, required): The reference the step that started this work returned. Supadata keeps a finished result for one hour.

**Outputs**

- `available_languages` (list): Every language this video has a transcript in.
- `character_count` (number): How long the transcript is, in characters.
- `is_finished` (true/false): True when the transcript is the finished one.
- `job_id` (text): Set only when Supadata is still working: pass it to 'Get a transcript that was still being made'.
- `language` (text): The language the transcript came back in.
- `segments` (list): The transcript as timed segments, when timestamps were asked for. Each one has the words, where it starts and how long it lasts, in milliseconds.
- `status` (text): queued, active or completed.
- `text` (text): The whole transcript as plain text.

**Example output**

```json
{
  "available_languages": [
    "en",
    "es",
    "zh-TW"
  ],
  "character_count": 52,
  "is_finished": true,
  "job_id": "",
  "language": "en",
  "segments": [],
  "status": "completed",
  "text": "Never gonna give you up, never gonna let you down..."
}
```

### Get a video transcript

Get the words spoken in a video on YouTube, TikTok, Instagram, X or Facebook, or in a video or audio file you host. Supadata uses the captions when the video has them and listens to it when it does not.

**Inputs**

- Video link (`url`, text, required): The link to the video on YouTube, TikTok, Instagram, X, Facebook, or a link to a video or audio file. A YouTube video id works too, so the ids from a listing step can be used as they are.
- Where to get it from (`mode`, text): Listening to a video costs more than reading captions that are already there, so this is the setting that decides what a run costs. One of: `auto` (Captions if there are any, otherwise listen to the video (recommended)), `native` (Only captions that already exist (1 credit, and it fails when there are none)), `generate` (Always listen to the video (2 credits for every minute of it)). Default: `auto`.
- Preferred language (`lang`, text): Which language to return when the video has captions in several. Supadata falls back to the first one it has. Ignored when it listens to the video, which always comes back in the language spoken. One of: `af` (Afrikaans), `ak` (Akan), `sq` (Albanian), `am` (Amharic), `ar` (Arabic), `hy` (Armenian), `as` (Assamese), `ay` (Aymara), `az` (Azerbaijani), `bn` (Bangla), and 123 more.
- Include timestamps (`include_timestamps`, true/false): Also return the transcript as timed segments, for subtitles or for linking to a moment in the video. The plain text comes back either way. Default: `false`.

**Outputs**

- `available_languages` (list): Every language this video has a transcript in.
- `character_count` (number): How long the transcript is, in characters.
- `is_finished` (true/false): True when the transcript is the finished one.
- `job_id` (text): Set only when Supadata is still working: pass it to 'Get a transcript that was still being made'.
- `language` (text): The language the transcript came back in.
- `segments` (list): The transcript as timed segments, when timestamps were asked for. Each one has the words, where it starts and how long it lasts, in milliseconds.
- `status` (text): queued, active or completed.
- `text` (text): The whole transcript as plain text.

**Example output**

```json
{
  "available_languages": [
    "en",
    "es",
    "zh-TW"
  ],
  "character_count": 52,
  "is_finished": true,
  "job_id": "",
  "language": "en",
  "segments": [],
  "status": "completed",
  "text": "Never gonna give you up, never gonna let you down..."
}
```

### Get a YouTube channel or playlist

Get what a channel or a playlist is: its name, description, how many videos it holds and how many people follow or watch it. Paste either one and Supadata works out which it is.

**Inputs**

- Channel or playlist (`channel_or_playlist`, text, required): A link to a YouTube channel or playlist. A channel handle such as @RickAstley, a channel id or a playlist id all work too.

**Outputs**

- `banner` (text): The channel's banner image.
- `channel` (object): The channel a playlist belongs to.
- `description` (text): What it says about itself.
- `handle` (text): The channel's @handle, when it has one.
- `id` (text): Its YouTube id.
- `last_updated` (text): When the playlist last changed.
- `subscriber_count` (number): How many people follow the channel.
- `thumbnail` (text): The channel's picture.
- `title` (text): The channel's or playlist's name.
- `type` (text): Which it turned out to be: channel or playlist.
- `url` (text): The link to it.
- `video_count` (number): How many videos it holds.
- `view_count` (number): How many views it has in total.

**Example output**

```json
{
  "banner": "https://yt3.ggpht.com/example-banner",
  "channel": {},
  "description": "The official Rick Astley YouTube channel.",
  "handle": "@RickAstleyYT",
  "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "last_updated": "",
  "subscriber_count": 4100000,
  "thumbnail": "https://yt3.ggpht.com/example",
  "title": "Rick Astley",
  "type": "channel",
  "url": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "video_count": 129,
  "view_count": 2100000000
}
```

### Get the details pulled out of a video

Read back what the AI found in a video. While it is still watching this says so; once it has finished it returns the details themselves. Check 'is_finished' to know which you have.

**Inputs**

- Job reference (`job_id`, text, required): The reference the step that started this work returned. Supadata keeps a finished result for one hour.

**Outputs**

- `details` (object): What it found, as fields you can use.
- `is_finished` (true/false): True once the AI has finished watching.
- `job_id` (text): The reference read.
- `status` (text): queued, active or completed.

**Example output**

```json
{
  "details": {
    "summary": "An introduction to artificial intelligence.",
    "topics": [
      "AI basics",
      "Neural networks"
    ]
  },
  "is_finished": true,
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed"
}
```

### Get video or post details

Get the title, description, author, tags and view, like and comment counts behind a video or post on YouTube, TikTok, Instagram, X or Facebook, all in the same shape whichever one it came from.

**Inputs**

- Video link (`url`, text, required): The link to the video on YouTube, TikTok, Instagram, X, Facebook, or a link to a video or audio file. A YouTube video id works too, so the ids from a listing step can be used as they are.

**Outputs**

- `author` (object): Who posted it, and whether they are verified.
- `created_at` (text): When it was posted.
- `description` (text): Its description or caption.
- `extra` (object): Anything the platform adds of its own.
- `id` (text): The id the platform knows it by.
- `media` (object): How long it runs and its thumbnail.
- `media_type` (text): video, image, carousel or post.
- `platform` (text): youtube, tiktok, instagram, twitter or facebook.
- `stats` (object): Views, likes, comments and shares.
- `tags` (list): The tags it was posted with.
- `title` (text): Its title.
- `url` (text): The link to it.

**Example output**

```json
{
  "author": {
    "displayName": "Rick Astley",
    "verified": true
  },
  "created_at": "2009-10-25T00:00:00Z",
  "description": "The official video...",
  "extra": {
    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw"
  },
  "id": "dQw4w9WgXcQ",
  "media": {
    "duration": 213,
    "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "type": "video"
  },
  "media_type": "video",
  "platform": "youtube",
  "stats": {
    "comments": 2200000,
    "likes": 17000000,
    "shares": null,
    "views": 1600000000
  },
  "tags": [
    "Rick Astley",
    "Official Video"
  ],
  "title": "Rick Astley - Never Gonna Give You Up",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
```

### List a channel's or playlist's videos

List the videos on a channel or in a playlist, newest first, as ids the transcript and details steps take as they are.

**Inputs**

- Channel or playlist (`channel_or_playlist`, text, required): A link to a YouTube channel or playlist. A channel handle such as @RickAstley, a channel id or a playlist id all work too.
- Which videos (`video_kind`, text): Leave out the ones you do not want. One of: `all` (Everything), `video` (Ordinary videos only), `short` (Shorts only), `live` (Live streams only). Default: `all`.
- How many videos (`limit`, number): The most to list. Leave it alone for the newest 30 of a channel, or the first 100 of a playlist. From 1 to 5000.

**Outputs**

- `all_ids` (list): Every id above in one list, ready for a loop that gets each one's transcript or details.
- `live_ids` (list): The live streams.
- `short_ids` (list): The Shorts.
- `type` (text): What it listed: channel or playlist.
- `video_count` (number): How many videos there are in all.
- `video_ids` (list): The ordinary videos.

**Example output**

```json
{
  "all_ids": [
    "dQw4w9WgXcQ",
    "xvFZjo5PgG0"
  ],
  "live_ids": [],
  "short_ids": [],
  "type": "channel",
  "video_count": 2,
  "video_ids": [
    "dQw4w9WgXcQ",
    "xvFZjo5PgG0"
  ]
}
```

### List a website's pages

Get every page address on a website without reading any of them. One credit, however big the site is. Loop over the addresses with 'Read a web page' to read the ones you want.

**Inputs**

- Website address (`url`, text, required): The site to scan. Give the top address to see the whole site, or a section such as https://example.com/blog to stay inside it.

**Outputs**

- `url_count` (number): How many there are.
- `urls` (list): Every page address found on the site.

**Example output**

```json
{
  "url_count": 2,
  "urls": [
    "https://supadata.ai",
    "https://supadata.ai/pricing"
  ]
}
```

### Read a web page

Get a web page as clean, readable text, with the navigation, adverts and markup stripped out, plus every link on it. Pages that build themselves in the browser are read too.

**Inputs**

- Page address (`url`, text, required): The address of the page to read.
- Leave links out of the text (`remove_links`, true/false): Strip the links out of the text itself, which reads better when the page is going to an AI step. The list of links comes back either way. Default: `false`.
- Preferred language (`lang`, text): Which language to ask the site for, when it publishes in several. One of: `af` (Afrikaans), `ak` (Akan), `sq` (Albanian), `am` (Amharic), `ar` (Arabic), `hy` (Armenian), `as` (Assamese), `ay` (Aymara), `az` (Azerbaijani), `bn` (Bangla), and 123 more. Default: `en`.

**Outputs**

- `character_count` (number): How long that text is.
- `content` (text): The page as readable text.
- `description` (text): The page's own summary of itself.
- `links` (list): Every link found on the page.
- `title` (text): The page's title.
- `url` (text): The page that was read.

**Example output**

```json
{
  "character_count": 12300,
  "content": "# Supadata\n\nSupadata turns videos and websites into text.",
  "description": "Web and video content, ready for AI.",
  "links": [
    "https://supadata.ai/pricing",
    "https://docs.supadata.ai"
  ],
  "title": "Supadata",
  "url": "https://supadata.ai"
}
```

### Search YouTube

Search YouTube for videos, channels and playlists, with the filters its own search box offers. No YouTube account or quota needed.

**Inputs**

- What to search for (`query`, text, required): What you would type into YouTube's search box.
- What to find (`result_type`, text): Which kind of result to return. One of: `all` (Everything), `video` (Videos), `channel` (Channels), `playlist` (Playlists), `movie` (Films). Default: `all`.
- Published (`upload_date`, text): How recently it was published. Applies to videos and films. One of: `all` (Any time), `hour` (In the last hour), `today`, `week` (This week), `month` (This month), `year` (This year). Default: `all`.
- Length (`duration`, text): How long the video runs for. Applies to videos and films. One of: `all` (Any length), `short` (Under 4 minutes), `medium` (4 to 20 minutes), `long` (Over 20 minutes). Default: `all`.
- Order by (`sort_by`, text): The order the results come back in. One of: `relevance` (Most relevant), `date` (Newest), `views` (Most viewed), `rating` (Highest rated). Default: `relevance`.
- Only videos that are (`features`, list): Keep only videos with all of these. Applies to videos and films. One or more of: `subtitles` (Subtitled), `hd`, `4k`, `hdr`, `creative-commons` (Creative Commons), `live` (Live now), `360` (360 degree), `vr180`, `3d`, `location` (Tagged with a place).
- How many results (`limit`, number): Supadata pages through YouTube until it has this many. Every twenty results costs one credit. From 1 to 500. Default: `20`.

**Outputs**

- `query` (text): The search that was run.
- `result_count` (number): How many results came back.
- `results` (list): Each result, with what it is, its id, title, channel and, for a video, its length and views.

**Example output**

```json
{
  "query": "never gonna give you up",
  "result_count": 1,
  "results": [
    {
      "channel": {
        "id": "UCuAXFkgsw1L7xaCfnd5JJOw",
        "name": "Rick Astley"
      },
      "duration": 213,
      "id": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "type": "video",
      "viewCount": 1600000000
    }
  ]
}
```

### Start pulling details out of a video

Have an AI watch a video and pull out whatever you describe: the products shown, the recipe, the chapters, the claims made. It watches and listens, so it sees what no transcript would say. This takes a few minutes, so follow it with a Wait step and 'Get the details pulled out of a video'.

**Inputs**

- Video link (`url`, text, required): The link to the video on YouTube, TikTok, Instagram, X, Facebook, or a link to a video or audio file. A YouTube video id works too, so the ids from a listing step can be used as they are.
- What to pull out (`prompt`, text, required): Describe what you want in plain language, naming each thing you expect back, such as 'The dish being cooked, every ingredient with its quantity, and the steps in order'. Naming them keeps every run in the same shape.

**Outputs**

- `is_finished` (true/false): Always false here. It has only just begun.
- `job_id` (text): The reference to read the details back with.
- `status` (text): Where the work is up to: queued.

**Example output**

```json
{
  "is_finished": false,
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "queued"
}
```