View as Markdown
HeyGen icon

HeyGen ACTION

List Videos

Retrieves a page of videos, newest first, with their id, status, and download links once completed. Use this to find a video ID for other actions. Note: the HeyGen v3 list may not include videos created in the HeyGen web app (it can return an empty list even when such videos exist); if you already know a video's ID, use Retrieve Video Link instead, which works for any video ID. Pass Fields to keep the response small. If has_more is true, pass next_token as the Token to get the next page. Example: Title Onboarding with Limit 2 and Fields ["id", "title", "status"] returns {"data": [{"id": "v_123", "title": "Onboarding intro", "status": "completed"}, {"id": "v_122", "title": "Onboarding part 2", "status": "processing"}], "has_more": true, "next_token": "abc"}. See the documentation
  • Action
  • Read only
  • API key
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's HeyGen account once, then configure and run List Videos from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "heygen-list-videos",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    heygen: { authProvisionId: "apn_xxxxxxx" },
    folderId: "Folder ID",
    titleFilter: "Title",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

List Videos inputs
Property Type Description
folderId Folder ID string
Only return videos in this folder. HeyGen has no API to list folders, so use a folder ID copied from the HeyGen app or returned in a video's folder_id field from a previous List Videos call.
Optional
titleFilter Title string
Only return videos whose title contains this text. Example: Onboarding
Optional
videoFields Fields string[]
Only return these fields for each video, to keep the response small. Valid fields: id, status, title, created_at, completed_at, video_url, thumbnail_url, gif_url, captioned_video_url, subtitle_url, duration, folder_id, output_language, failure_code, failure_message, video_page_url. Example: ["id", "title", "status"]. Returns all fields if not set.
Optional
limit Limit integer
Number of results per page (1-100). Defaults to the API default if not set. Example: 20
Optional
token Token string
Cursor for the next page. Use the next_token value from the previous response of this same action, with the same filters and limit. Example: eyJzdGFydF9pZCI6ICI4NDU5MTlhZTEw...
Optional

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
heygen-list-videos
Version
0.0.1
App
HeyGen
Authentication
API key
Read-only
Yes
Destructive
No
Open world
Yes