How to export HeyGen video metadata to CSV
A trustworthy manifest answers what exists, where it came from, which assets are available, and whether the corresponding local file was actually downloaded.
List videos through HeyGen’s paginated API or a trusted exporter, write one row per video, and keep the stable video ID as the primary key. Include title, timestamps, duration, language, folder, video-page URL, asset availability, local filenames, and transfer status.
A video folder cannot answer library questions
Local MP4 filenames rarely preserve every useful fact. A CSV can show which language a file uses, when it completed, whether a captioned version exists, which HeyGen folder it belongs to, and which records failed. It is also the bridge between a cloud workspace, local archive, client delivery, and later migration.
Use stable source fields plus local workflow fields
| Field | Purpose |
|---|---|
| video_id | Stable reconciliation key |
| title | Human-readable identification |
| created_at / completed_at | Timeline and incremental exports |
| duration_seconds | QA and storage estimates |
| output_language | Locale filtering |
| folder_id | Workspace grouping |
| video_page_url | Return to the project |
| master / caption / subtitle available | Asset coverage |
| failure_code / message | Exception diagnosis |
| local_filename / download_status | Backup reconciliation |
Keep the original timestamps machine-readable. Add a separate display column if stakeholders need local date formatting.
Do not export only the first API page
HeyGen’s current List Videos endpoint accepts a limit up to 100 and returns has_more plus an opaque next_token. A complete exporter repeats requests with the returned token until has_more is false.
- Start without a token.
- Append the page’s rows without replacing earlier pages.
- Pass the exact returned token to the next request.
- Stop only when the response says there are no more pages.
- Deduplicate by video ID if a retry repeats a page.
- Record export time and any request failures.
Filtering by folder or title can be useful for a scoped audit, but label that CSV as filtered so nobody mistakes it for the whole account.
Remote asset URLs are useful but not a backup
The API can expose standard, captioned, subtitle, thumbnail, and GIF URLs. Keep availability flags and URLs in an operational export if useful, but do not promise that a remote URL is permanent. For a durable archive, download the bytes and map each local filename back to the video ID.
Validate the inventory
- Confirm every row has a unique non-empty video ID.
- Compare row count with the expected scoped library count.
- Check duplicate titles; they should remain distinguishable by ID.
- Flag completed records without a master video URL.
- Flag captioned local files whose caption availability is false or blank.
- Open a sample of video-page URLs and local filenames.
- Save the raw CSV as UTF-8 and protect it from accidental edits.
Turn the CSV into useful views
- Missing assets: completed videos without local masters or expected captions.
- Language inventory: count by locale for localization coverage.
- Client delivery: approved records filtered by campaign and version.
- Storage estimate: duration or observed size summarized by period.
- Failure queue: unresolved failure codes and owner.
- Incremental backup: records completed since the previous snapshot.
For the file transfer that goes with the inventory, use the library backup workflow. Agencies should also apply the client isolation and handoff structure.