# List Videos — HeyGen

> 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…

- Key: `heygen-list-videos`
- Type: Action (Read-only)
- Version: 0.0.1
- App: HeyGen (`heygen`) — https://pipedream.com/apps/heygen.md
- This page (HTML): https://pipedream.com/apps/heygen/actions/list-videos
- Hints: read-only · open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/heygen/actions/list-videos/list-videos.mjs

## Description

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](https://developers.heygen.com/reference/list-videos)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `folderId` | `string` | No | 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. |
| `titleFilter` | `string` | No | Only return videos whose title contains this text. Example: Onboarding |
| `videoFields` | `string[]` | No | 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. |
| `limit` | `integer` | No | Number of results per page (1-100). Defaults to the API default if not set. Example: 20 |
| `token` | `string` | No | 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... |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
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 accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "heygen",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "heygen-list-videos",
  arguments: {
    folderId: "Folder ID",
    titleFilter: "Title",
  },
})
```

**TypeScript**

```ts
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)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "heygen-list-videos",
    "configured_props": {
      "heygen": { "authProvisionId": "apn_xxxxxxx" },
      "folderId": "Folder ID",
      "titleFilter": "Title"
    }
  }'
```

---

- App: https://pipedream.com/apps/heygen.md · All apps: https://pipedream.com/apps