FactIQ
Browse documentation

Turn a YouTube video into a data deep dive with Codex and FactIQ

You watched a video full of numbers. This recipe shows you how to dig past the talking points — trace every number to official data, find what the video left out, and publish the result as a sourced page.

On this page

Start here

Pull the video’s captions to use as a research outline, have Codex dig into every number with FactIQ’s data, and publish a deep dive that shows what the data actually says — including, just as carefully, where the data runs out.

What you’ll build

A published deep dive where every number has a source and every gap in the data is labeled. Here’s what you’ll end up with.

What you need

The Codex CLI, a FactIQ account, and roughly an afternoon.

The one rule

Write down where the data ran out just as carefully as what it showed. That’s what makes a deep dive trustworthy.

1. Install the FactIQ plugin

This gives Codex the tools to search and query FactIQ’s data. You install once, sign in once, then start a fresh thread so the tools are loaded.
codex plugin marketplace add defog-ai/factiq-plugin
codex plugin add factiq@factiq
codex mcp login factiq

The last command opens a browser window — sign in there. The connection is read-only: Codex can look things up and run queries, but it cannot change any data.

2. Get the video’s captions

The captions are your research outline — every number, forecast, and named source you’ll dig into. Reading them is much faster than scrubbing through the video. You can use the transcript privately, but you can’t republish it.
  1. 01

    Install the caption tool

    uv tool install git+https://github.com/rishsriv/stitch-youtube-vtt.git@4b723d84b16cb176fccf0f0f34dd8b09f79c7323 installs a small tool that downloads a video’s captions and cleans them into readable text. The long string pins it to a reviewed version.
  2. 02

    Save the transcript somewhere private

    Run the command below and write the output outside your repository — for example to /tmp. The tool prefers the creator’s own captions, falls back to automatic ones, removes duplicated lines, and records the title and URL.
  3. 03

    List the claims worth digging into

    Read the transcript and pull out every concrete number, forecast, and named source, each with its timestamp. Automatic captions mishear numbers, so replay the video at any spot where a figure looks odd.
stitch-youtube-vtt 'https://www.youtube.com/watch?v=VIDEO_ID' /tmp/video-research.txt

3. Find out what data exists

Before digging in, find out how far the data can take you. When the right data doesn’t exist, that’s a finding to write down — not a reason to grab a similar-looking series instead.
  1. 01

    Open the catalog

    Call get_data_catalog once to see every data source. Skip anything listed under schemas_without_data.
  2. 02

    Find the right datasets

    Search with search_datasets using concrete keywords, then call describe_dataset to see what each one measures, how, and with what example series.
  3. 03

    Find the exact series

    Use short phrases with search_series — it matches titles literally, so “electricity net consumption” beats a full sentence. When you need to inspect titles or dimensions, run an exploratory run_sql query against the series table.
  4. 04

    Write down the limits

    For each claim, note whether the data matches its country, sector, time period, frequency, and measure. Annual national electricity data cannot verify a claim about the evening peak in one region — and saying so is the honest answer.

Once you know what exists, hand Codex your claim list with a prompt like this.

Research prompt
Do a data deep dive on the number-based claims in this outline using FactIQ's data. For each claim, establish what official data actually shows, and go one level deeper where the data allows — trends, comparisons, and context the video did not mention. Before you run any queries, call get_data_catalog once. Then use search_datasets, describe_dataset, and short search_series terms to find out what data actually exists. Do not guess series IDs. Use read-only query tools only. Keep three things separate throughout: what the video says, what FactIQ's data says, and your own interpretation. For every claim, write down: the claim itself, how the data relates to it (supported, partly supported, or not verified), the source organization and dataset, the time period, the units, the series or dataset IDs, the date you retrieved the data, any calculation you did, and anything the data could not cover. If the exact series a claim needs does not exist, record that as the result — never swap in a similar-looking series as a stand-in.

4. Dig into each claim

Now run the actual queries — establish what the data shows for each claim, then look one level deeper for the trends and comparisons the video skipped. Most mistakes at this stage are not wrong numbers — they’re right numbers measuring the wrong thing.

How the data is laid out

Every source uses the same three tables: series is the catalog, data_points holds the values as (series_id, time, value), and dimensions holds the breakdowns. Use get_series when you know the one or two IDs you need; use run_sql for joins, ratios, or anything involving three or more series.

Before you trust a number

  • Check that the series measures what the claim is about: same country, same national-or-regional scope, same frequency, same units.
  • When comparing two numbers, make sure both measure the same thing. Electricity generated and electricity consumed are different numbers, and comparing one country’s generation with another’s consumption proves nothing.
  • Do the arithmetic in SQL or a small calculation you can show. Keep full precision and round only when presenting.
  • Queries return at most 50 rows. If you hit that cap, aggregate or narrow the query — don’t page through raw rows and add them up by hand, because that’s where transcription errors creep in.
  • If a number surprises you, check it against a second source when one exists. If the two disagree, explain why — different periods, different definitions — rather than quietly picking the one that fits.

5. Keep an evidence ledger

Before writing any prose, put every claim and every number you dug up in one ledger. Anything not in the ledger doesn’t go on the page — that’s how unsourced numbers stay out.

One row per claim, with these fields:

FieldWhat to write down
The claimWhat the video said, in your own words, with a timestamped link
What the data showsSupported, partly supported, contradicted, or not verified
Where the data came fromOrganization, dataset, and the exact series or dataset IDs
The numberValue, time period, frequency, units, and geography
The mathThe formula, its inputs, any unit conversions, and the unrounded result
When you checkedThe UTC date you retrieved the data, and how recent the data itself is
What was missingWhat the data couldn’t cover, and why a nearby series wasn’t a fair substitute
Your takeAny conclusion you drew yourself, clearly labeled as your interpretation

6. Write it up

Turn the ledger into a page a reader can trust. Start with what the data shows, keep the reasoning next to each claim, and leave the tool names for a methodology note.
Writing prompt
Turn the finished evidence ledger into a public documentation page. Keep the video's exact title and URL, and link to timestamps for the major sections. Paraphrase the video — do not publish the transcript. Start the page with what the data shows. Label where every statement comes from: the video, FactIQ's data, or your own reading of the two. Every number on the page goes in a table with its source, period, units, retrieval date, and series or dataset ID. Include the claims the data could not reach — they go in the same table, not a footnote. Add page metadata, docs navigation, sitemap coverage, tables that scroll on small screens, dark-mode styles, working anchor links, and a regression test.
  • Keep the video’s exact title and URL, and link to useful timestamps.
  • Paraphrase — don’t publish the transcript.
  • Make it visible where each statement comes from: the video, the data, or you.
  • Give every number a source, period, units, retrieval date, and series ID.
  • Put the claims the data couldn’t reach in the main table, not a footnote. Readers trust a deep dive more when it admits where the data ran out.
  • Reuse the site’s existing docs layout, navigation, dark-mode styles, metadata helper, and sitemap.

7. Test the page

The page isn’t done when it compiles — it’s done when you’ve opened it and clicked through it.
pnpm test src/screens/__tests__/DocsPage.test.tsx
pnpm exec tsc --noEmit
pnpm dev
  • Open the page in a browser at desktop and phone widths.
  • At phone width, open the mobile documentation menu and click every table-of-contents link.
  • Follow the previous/next links and the docs hub links, and confirm none of them lead to a missing page.
  • Check that wide tables scroll sideways instead of breaking the layout.
  • Switch to dark mode and confirm everything is still readable.
  • Check /sitemap.xml locally and confirm both this page and the example page are listed.