> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hireflix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How-to: Bulk Downloading Interview Videos

## When to use this

Use this when you need to **archive or export interview videos in bulk** — for example, backing up interviews before a retention window closes, moving recordings into your own storage, or running an analysis over a full set of answers. It combines queries already covered in this section — [listing interviews for a position](https://docs.hireflix.com/tech/features/interviews/list-interviews-for-position.md) and [fetching interview results](https://docs.hireflix.com/tech/features/interviews/fetching-interview-results.md) — into a script that walks every completed interview and saves each answer video to disk.

> [!TIP]
>
> **Only need a handful of videos?** You can download them one by one from the dashboard instead of running a script: open the **position**, click into any **completed interview**, and use the **Download video** button in the bottom-left corner. This works fine for a few interviews, but it's a manual, one-video-at-a-time process — for anything bigger, one of the scripts below is much faster.

> [!TIP]
>
> **Also need the candidate data?** Names, emails, stages, scores, reviewer comments, and answer transcripts can be exported to a spreadsheet straight from the dashboard, no script needed. See [Bulk Exporting Candidates to CSV](https://docs.hireflix.com/user/reviewing-sharing/bulk-export-candidates-csv.md).

## The script

Pick the tab that matches what you need to export — both require **Node.js 18+** (for native `fetch`).

> [tab] Single Position
>
> Downloads every completed interview video for **one position**, given its position ID. The script:
>
> 1. Fetches every interview for the position, paginating automatically 100 at a time until it's collected them all, and skips any still `pending` (candidate hasn't completed it yet).
> 2. For each completed interview, fetches the `stepExecutions` and pulls the signed video `url` from each `latestAnswer`, skipping steps with a deleted or missing answer.
> 3. Streams each video to disk under `hireflix_videos/`, named `FirstName_LastName__01_QuestionTitle.mp4` — the two-digit prefix keeps answers in question order per candidate.
>
> Save this as `download_videos.js`.
>
> ```javascript download_videos.js theme={null}
> #!/usr/bin/env node
> /**
>  * Bulk-download all interview videos for a given Hireflix position.
>  *
>  * Requirements: Node.js 18+ (for native fetch)
>  * Usage:
>  *   export HIREFLIX_API_KEY="<your-api-key>"
>  *   node download_videos.js <position-id>
>  */
>
> import fs from "fs";
> import path from "path";
> import { pipeline } from "stream/promises";
>
> const API_URL = "https://api.hireflix.com/me";
> const API_KEY = process.env.HIREFLIX_API_KEY;
> const POSITION_ID = process.argv[2];
> const OUTPUT_DIR = "hireflix_videos";
>
> if (!API_KEY) {
>   console.error("Missing HIREFLIX_API_KEY environment variable.");
>   process.exit(1);
> }
>
> if (!POSITION_ID) {
>   console.error("Usage: node download_videos.js <position-id>");
>   process.exit(1);
> }
>
> const HEADERS = {
>   "Content-Type": "application/json",
>   "X-Api-Key": API_KEY,
> };
>
> async function gql(query, variables = {}) {
>   const res = await fetch(API_URL, {
>     method: "POST",
>     headers: HEADERS,
>     body: JSON.stringify({ query, variables }),
>   });
>
>   if (!res.ok) {
>     throw new Error(`HTTP ${res.status}: ${await res.text()}`);
>   }
>
>   const data = await res.json();
>   if (data.errors) {
>     throw new Error(JSON.stringify(data.errors, null, 2));
>   }
>   return data.data;
> }
>
> async function getInterviews(positionId) {
>   const query = `
>     query($id: String!, $lastCursor: String!) {
>       position(id: $id) {
>         name
>         interviewList(input: { filter: {}, pagination: { limit: 100, lastCursor: $lastCursor }, sort: [] }) {
>           lastCursor
>           results {
>             id
>             stage
>             candidate { firstName lastName email }
>           }
>         }
>       }
>     }
>   `;
>
>   let positionName = null;
>   const interviews = [];
>   let cursor = ""; // "" fetches the first page
>
>   while (true) {
>     const data = await gql(query, { id: positionId, lastCursor: cursor });
>     positionName = data.position.name;
>     const page = data.position.interviewList;
>     interviews.push(...page.results);
>
>     if (page.results.length === 0 || !page.lastCursor) break;
>     cursor = page.lastCursor;
>   }
>
>   return { positionName, interviews };
> }
>
> async function getInterviewVideos(interviewId) {
>   const query = `
>     query($id: String!) {
>       interview(id: $id) {
>         stepExecutions {
>           ... on AdminInterviewStepQAExecution {
>             template { title }
>             latestAnswer {
>               ... on InterviewStepQAVideoAnswer {
>                 video { ... on VideoMedia { url mimeType } }
>               }
>               ... on InterviewStepQADeletedAnswer { __typename }
>             }
>           }
>         }
>       }
>     }
>   `;
>   const data = await gql(query, { id: interviewId });
>   return data.interview.stepExecutions;
> }
>
> function safeFilename(text) {
>   return (text || "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
> }
>
> async function downloadVideo(url, destPath) {
>   const res = await fetch(url);
>   if (!res.ok) {
>     throw new Error(`Failed to download ${url}: HTTP ${res.status}`);
>   }
>   await pipeline(res.body, fs.createWriteStream(destPath));
> }
>
> async function main() {
>   fs.mkdirSync(OUTPUT_DIR, { recursive: true });
>
>   const { positionName, interviews } = await getInterviews(POSITION_ID);
>   console.log(`Position: ${positionName} — ${interviews.length} interview(s) found`);
>
>   for (const interview of interviews) {
>     if (interview.stage === "pending") continue; // candidate hasn't completed the interview yet
>
>     const candName = safeFilename(
>       `${interview.candidate.firstName}_${interview.candidate.lastName}`
>     );
>     const steps = await getInterviewVideos(interview.id);
>
>     for (let i = 0; i < steps.length; i++) {
>       const step = steps[i];
>       const answer = step.latestAnswer;
>       if (!answer || !answer.video) continue; // deleted or missing answer
>
>       const title = safeFilename(step.template?.title || `question_${i + 1}`);
>       const url = answer.video.url;
>       const ext = (answer.video.mimeType || "").includes("mp4") ? ".mp4" : ".webm";
>       const filename = `${candName}__${String(i + 1).padStart(2, "0")}_${title}${ext}`;
>       const dest = path.join(OUTPUT_DIR, filename);
>
>       console.log(`Downloading ${filename} ...`);
>       await downloadVideo(url, dest);
>     }
>   }
>
>   console.log("Done.");
> }
>
> main().catch((err) => {
>   console.error(err);
>   process.exit(1);
> });
> ```
>
> **1. Create the script file**
>
> Never run a script before? Open a **plain-text editor** — not Word or Google Docs, since those add hidden formatting that breaks the file. A free option that works on Mac and Windows is [VS Code](https://code.visualstudio.com/); Notepad (Windows) or TextEdit (Mac, switch to *Format → Make Plain Text* first) also work.
>
> Copy the full script above, paste it into a new file, and save it as `download_videos.js` in a folder you'll remember, e.g. your Desktop. Make sure your editor doesn't silently add `.txt` to the filename — on Windows, pick **All Files** in the save dialog's file-type dropdown; on Mac, TextEdit adds `.txt` unless you type the full name including `.js` yourself.
>
> **2. Open a terminal**
>
> The terminal (or command line) is where you'll type the commands in the remaining steps.
>
> * **Mac:** press `Cmd + Space`, type `Terminal`, press Enter.
> * **Windows:** press the Start key, type `Command Prompt` (or `PowerShell`), press Enter.
>
> Then move into the folder where you saved the script — for example, if you saved it on your Desktop:
>
> ```bash theme={null}
> cd Desktop
> ```
>
> **3. Check your Node.js version**
>
> Native `fetch` requires Node 18+. Confirm with:
>
> ```bash theme={null}
> node -v
> ```
>
> **4. Set your API key**
>
> Export your [Hireflix API key](https://docs.hireflix.com/tech/quickstart.md) as an environment variable:
>
> ```bash theme={null}
> export HIREFLIX_API_KEY="<your-api-key>"
> ```
>
> **5. Run the script**
>
> Pass the ID of the position you want to export as an argument (see [fetching positions](https://docs.hireflix.com/tech/features/positions/fetching-positions.md) for how to find it):
>
> ```bash theme={null}
> node download_videos.js <position-id>
> ```
>
> The script logs each file as it downloads and prints `Done.` when finished.
>
> #### Output
>
> Videos are saved to a `hireflix_videos/` folder created next to the script, one file per answered question:
>
> ```
> hireflix_videos/
> ├── Jane_Doe__01_Motivation.mp4
> ├── Jane_Doe__02_Experience.mp4
> ├── John_Smith__01_Motivation.mp4
> └── ...
> ```

> [tab] Whole Account
>
> Downloads every completed interview video across **every position in your account**. The script:
>
> 1. Fetches every position in your account.
> 2. For each position, fetches every interview in it, paginating automatically 100 at a time until it's collected them all, and skips any still `pending` (candidate hasn't completed it yet).
> 3. For each completed interview, fetches the `stepExecutions` and pulls the signed video `url` from each `latestAnswer`, skipping steps with a deleted or missing answer.
> 4. Streams each video to disk under `hireflix_videos/<Position Name>/`, named `FirstName_LastName__01_QuestionTitle.mp4` — one subfolder per position, so candidates with the same name in different positions don't collide.
>
> Save this as `download_videos.js`.
>
> ```javascript download_videos.js theme={null}
> #!/usr/bin/env node
> /**
>  * Bulk-download every interview video across your Hireflix account.
>  *
>  * Requirements: Node.js 18+ (for native fetch)
>  * Usage:
>  *   export HIREFLIX_API_KEY="<your-api-key>"
>  *   node download_videos.js
>  */
>
> import fs from "fs";
> import path from "path";
> import { pipeline } from "stream/promises";
>
> const API_URL = "https://api.hireflix.com/me";
> const API_KEY = process.env.HIREFLIX_API_KEY;
> const OUTPUT_DIR = "hireflix_videos";
>
> if (!API_KEY) {
>   console.error("Missing HIREFLIX_API_KEY environment variable.");
>   process.exit(1);
> }
>
> const HEADERS = {
>   "Content-Type": "application/json",
>   "X-Api-Key": API_KEY,
> };
>
> async function gql(query, variables = {}) {
>   const res = await fetch(API_URL, {
>     method: "POST",
>     headers: HEADERS,
>     body: JSON.stringify({ query, variables }),
>   });
>
>   if (!res.ok) {
>     throw new Error(`HTTP ${res.status}: ${await res.text()}`);
>   }
>
>   const data = await res.json();
>   if (data.errors) {
>     throw new Error(JSON.stringify(data.errors, null, 2));
>   }
>   return data.data;
> }
>
> async function getPositions() {
>   const query = `
>     query {
>       positions {
>         id
>         name
>       }
>     }
>   `;
>   const data = await gql(query);
>   return data.positions;
> }
>
> async function getInterviews(positionId) {
>   const query = `
>     query($id: String!, $lastCursor: String!) {
>       position(id: $id) {
>         interviewList(input: { filter: {}, pagination: { limit: 100, lastCursor: $lastCursor }, sort: [] }) {
>           lastCursor
>           results {
>             id
>             stage
>             candidate { firstName lastName email }
>           }
>         }
>       }
>     }
>   `;
>
>   const interviews = [];
>   let cursor = ""; // "" fetches the first page
>
>   while (true) {
>     const data = await gql(query, { id: positionId, lastCursor: cursor });
>     const page = data.position.interviewList;
>     interviews.push(...page.results);
>
>     if (page.results.length === 0 || !page.lastCursor) break;
>     cursor = page.lastCursor;
>   }
>
>   return interviews;
> }
>
> async function getInterviewVideos(interviewId) {
>   const query = `
>     query($id: String!) {
>       interview(id: $id) {
>         stepExecutions {
>           ... on AdminInterviewStepQAExecution {
>             template { title }
>             latestAnswer {
>               ... on InterviewStepQAVideoAnswer {
>                 video { ... on VideoMedia { url mimeType } }
>               }
>               ... on InterviewStepQADeletedAnswer { __typename }
>             }
>           }
>         }
>       }
>     }
>   `;
>   const data = await gql(query, { id: interviewId });
>   return data.interview.stepExecutions;
> }
>
> function safeFilename(text) {
>   return (text || "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
> }
>
> async function downloadVideo(url, destPath) {
>   const res = await fetch(url);
>   if (!res.ok) {
>     throw new Error(`Failed to download ${url}: HTTP ${res.status}`);
>   }
>   await pipeline(res.body, fs.createWriteStream(destPath));
> }
>
> async function main() {
>   fs.mkdirSync(OUTPUT_DIR, { recursive: true });
>
>   const positions = await getPositions();
>   console.log(`Found ${positions.length} position(s) in your account.`);
>
>   for (const position of positions) {
>     const interviews = await getInterviews(position.id);
>     console.log(`\nPosition: ${position.name} — ${interviews.length} interview(s) found`);
>
>     const positionDir = path.join(OUTPUT_DIR, safeFilename(position.name || position.id));
>     fs.mkdirSync(positionDir, { recursive: true });
>
>     for (const interview of interviews) {
>       if (interview.stage === "pending") continue; // candidate hasn't completed the interview yet
>
>       const candName = safeFilename(
>         `${interview.candidate.firstName}_${interview.candidate.lastName}`
>       );
>       const steps = await getInterviewVideos(interview.id);
>
>       for (let i = 0; i < steps.length; i++) {
>         const step = steps[i];
>         const answer = step.latestAnswer;
>         if (!answer || !answer.video) continue; // deleted or missing answer
>
>         const title = safeFilename(step.template?.title || `question_${i + 1}`);
>         const url = answer.video.url;
>         const ext = (answer.video.mimeType || "").includes("mp4") ? ".mp4" : ".webm";
>         const filename = `${candName}__${String(i + 1).padStart(2, "0")}_${title}${ext}`;
>         const dest = path.join(positionDir, filename);
>
>         console.log(`Downloading ${filename} ...`);
>         await downloadVideo(url, dest);
>       }
>     }
>   }
>
>   console.log("\nDone.");
> }
>
> main().catch((err) => {
>   console.error(err);
>   process.exit(1);
> });
> ```
>
> **1. Create the script file**
>
> Never run a script before? Open a **plain-text editor** — not Word or Google Docs, since those add hidden formatting that breaks the file. A free option that works on Mac and Windows is [VS Code](https://code.visualstudio.com/); Notepad (Windows) or TextEdit (Mac, switch to *Format → Make Plain Text* first) also work.
>
> Copy the full script above, paste it into a new file, and save it as `download_videos.js` in a folder you'll remember, e.g. your Desktop. Make sure your editor doesn't silently add `.txt` to the filename — on Windows, pick **All Files** in the save dialog's file-type dropdown; on Mac, TextEdit adds `.txt` unless you type the full name including `.js` yourself.
>
> **2. Open a terminal**
>
> The terminal (or command line) is where you'll type the commands in the remaining steps.
>
> * **Mac:** press `Cmd + Space`, type `Terminal`, press Enter.
> * **Windows:** press the Start key, type `Command Prompt` (or `PowerShell`), press Enter.
>
> Then move into the folder where you saved the script — for example, if you saved it on your Desktop:
>
> ```bash theme={null}
> cd Desktop
> ```
>
> **3. Check your Node.js version**
>
> Native `fetch` requires Node 18+. Confirm with:
>
> ```bash theme={null}
> node -v
> ```
>
> **4. Set your API key**
>
> Export your [Hireflix API key](https://docs.hireflix.com/tech/quickstart.md) as an environment variable:
>
> ```bash theme={null}
> export HIREFLIX_API_KEY="<your-api-key>"
> ```
>
> **5. Run the script**
>
> ```bash theme={null}
> node download_videos.js
> ```
>
> No arguments needed — it walks every position in your account automatically. The script logs each file as it downloads and prints `Done.` when finished.
>
> #### Output
>
> Videos are saved to a `hireflix_videos/` folder created next to the script, with one subfolder per position:
>
> ```
> hireflix_videos/
> ├── Social_Media_Manager/
> │   ├── Jane_Doe__01_Motivation.mp4
> │   ├── Jane_Doe__02_Experience.mp4
> │   └── John_Smith__01_Motivation.mp4
> ├── Backend_Engineer/
> │   └── ...
> └── ...
> ```

> [!WARNING]
>
> Video `url`s are **signed and expire after 14 days**. Both scripts always fetch a fresh URL right before downloading, so that's not an issue when you run them — but don't cache or reuse URLs from a previous run.

> [!NOTE]
>
> For every position it processes, the script paginates through **all** of its interviews (100 per request, looping on `lastCursor` until a page comes back empty) — it isn't capped at the first 100 candidates. The first request for each position must send `lastCursor: ""` (not `null`) — an explicit `null` causes the API to scope the result set incorrectly.
>
> Running the whole-account version can mean a lot of requests and large downloads, so it's also worth checking your data retention / GDPR policy before archiving candidate video off-platform.

> [card] [Learn next?](https://docs.hireflix.com/tech/webhooks/getting-started.md)
>
> Let's learn how to create and use webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.