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 and fetching interview results — into a script that walks every completed interview and saves each answer video to disk.

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.

The script

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

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.

download_videos.js

#!/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; 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:

   cd Desktop
   
3. Check your Node.js version

   Native fetch requires Node 18+. Confirm with:

   node -v
   
4. Set your API key

   Export your Hireflix API key as an environment variable:

   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 for how to find it):

   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
└── ...

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.

download_videos.js

#!/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; 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:

   cd Desktop
   
3. Check your Node.js version

   Native fetch requires Node 18+. Confirm with:

   node -v
   
4. Set your API key

   Export your Hireflix API key as an environment variable:

   export HIREFLIX_API_KEY="<your-api-key>"
   
5. Run the script

   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/
│   └── ...
└── ...

Video urls 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.

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.

Learn next?

Let’s learn how to create and use webhooks.