Frequently Asked Questions

Scraped messages are stored exclusively in data/vault.db, a SQLite database on your local filesystem. The database uses WAL mode for concurrent access. No data is ever uploaded to external servers, analytics endpoints, or cloud storage. Thread Vault CLI has no telemetry or network calls outside of www.instagram.com.

This is intentional — Thread Vault enforces Session Data Isolation. All scraped message rows, cursor state, and session cache files are purged when you exit the Scrape Dashboard or log out. This zero-persistence policy ensures no DM data lingers on your disk beyond the active session. If you need to keep records, export from SQLite before exiting.

While the dashboard is still open, use the SQLite CLI in a separate terminal: See the Export Guide for more options.

Never. Thread Vault does not ask for, process, or store your Instagram password. Authentication works via sessionid and csrftoken cookies only — the same mechanism used by your browser when you stay logged in to Instagram. Your password is entered directly into the Instagram login page in the Chromium browser, not processed by Thread Vault.

• cache/session.json — session ID, CSRF token, user PK, username
• cache/inbox_cache.json — thread directory listing
• data/vault.db — SQLite database with scraped messages

All three are deleted on logout. The threads table in vault.db persists between sessions (for the thread directory cache) but contains no message content.

Run the Playwright Chromium installer: This is a one-time setup. Alternatively, switch to Session ID Authentication (Method B) which requires no browser installation.

Your Instagram session has expired or been revoked. Instagram sessions can expire due to: password change, suspicious activity detection, too many concurrent sessions, or extended inactivity. Use Browser Login to establish a fresh cookie context. Session ID pasting also works if you retrieve a fresh value from your browser's DevTools.

Yes — Browser Login (Method A) fully supports 2FA. The Playwright Chromium window presents the real Instagram login page. Enter your credentials, complete the 2FA step (SMS, authenticator app, or backup code), and Thread Vault will capture the resulting session cookie automatically. The 5-minute timeout is sufficient for all 2FA flows.

On every startup, Thread Vault probes /api/v1/direct_v2/inbox/?limit=1 with the cached session. If the response contains a valid inbox key and the status is not "fail", the session is considered valid and the username is extracted from the viewer field. This probe is more reliable than hitting the profile endpoint because it confirms the session can actually fetch DM data.

This is normal and expected behavior. Instagram limits how frequently DMs can be fetched or unsent. The countdown progress bar shows remaining wait time. You can press Stop to cancel the wait and exit the pipeline cleanly. Wait times range from ~30 seconds to ~10 minutes depending on the backoff stage.

Thread Vault uses a five-stage backoff schedule with ±20% jitter:

• Stage 0: 30s (~24–36s with jitter)
• Stage 1: 60s (~48–72s)
• Stage 2: 120s (~96–144s)
• Stage 3: 300s (~4–6 minutes)
• Stage 4: 600s (~8–12 minutes) — maximum, stays here

The cooldown index increments each time a 429 is encountered and resets between sessions.

Automatic (P): Both scraper and unsend worker run concurrently. The scraper pushes messages into the queue as it fetches pages; the unsend worker begins processing immediately without waiting for scraping to finish. Manual Scrape (S): Only fetches and stores messages — does not unsend. Useful for previewing content. Manual Unsend (U): Unsends only checked/selected rows — requires prior scraping.

Yes. The scraper saves pagination cursors to scrape_progress in SQLite after each page. Re-running the scraper on the same thread automatically resumes from the last saved cursor. To force a full re-scrape from the first page, press X in the dashboard to reset the cursor state.

Yes. The scraper worker checks is_sent_by_viewer on each message item (equivalent to item.sent_by_current_user). Only messages sent by the authenticated account are written to SQLite and pushed to the queue. Received messages are skipped.

Mode A recursively strips text, caption, and caption_text keys from all message payloads before writing to SQLite. This is intentional — Mode A focuses on media metadata only, not the textual content associated with media messages.

This means another process has an exclusive lock on data/vault.db. Check if another instance of Thread Vault CLI is running. Thread Vault uses WAL mode and a 5-second busy timeout to minimize this, but concurrent writers to a single SQLite file will still serialize. Kill any other instances and retry.

Ensure your terminal supports full Unicode and ANSI escape codes. On Windows, use Windows Terminal. On macOS, use iTerm2 or Terminal.app with a Nerd Font. On Linux, any modern terminal emulator (Alacritty, Kitty, GNOME Terminal) should work. Set your terminal font to support box-drawing characters.

Press R in the Thread Explorer to reload from the Instagram API. If the list is still empty, your session may not have DM access. Verify you're logged into the correct account. Also check that your session is valid by looking at the session status widget — it should show your @username.

Run uv sync to ensure all dependencies are installed in the managed virtual environment. Never run python -m app directly without uv run — it won't use the correct venv. Always prefix with uv run: uv run python -m app.