Skip to content
The world does revolve around you.

Data exports#

The installer asks (Q11 and Q12) whether you have any platform data exports for Ostler to import. This page is the long-form version of those questions: what an export is, why Ostler wants one, and how to request yours from every platform Ostler can read.

TL;DR

Most big platforms will email you a download link 1 to 3 days after you ask. Save the ZIP to ~/Downloads (or the folder you pointed the installer at) and Ostler imports it automatically. If you have not requested anything yet, you can skip Q11/Q12 and import later with ostler-import <path-to-zip>.

What is a data export?#

A data export is the bundle of your own content that a platform is legally required to give back to you on request. Under UK GDPR, EU GDPR, and California's CCPA, every platform that holds your data has to make it available in a portable format. Most produce a ZIP containing JSON or HTML files: messages, posts, contacts, photos, listening history, watch history, likes, follows, calendar events, and so on.

These exports are how Ostler reaches back beyond the small window the live APIs expose. Twitter's API only returns your last few hundred tweets; the export contains every tweet you have ever posted. Facebook's API does not give you message history at all; the export does. WhatsApp has no API for your own data; the export is the only way in.

Why Ostler wants them#

Ostler's whole job is to give you a personal knowledge graph of your own life: people you know, conversations you have had, places you have been, things you have made. The live macOS sources (Apple Mail, iMessage, Calendar, Photos, Reminders, Notes, Safari) give Ostler the present and the recent past, often back many years if you have been a long-time Apple user.

Platform exports give Ostler the rest of your past:

  • The 10 years of Instagram posts before you moved your photo workflow to Apple Photos.
  • The Facebook Messenger threads from university that never made it to iMessage.
  • The Twitter / X timeline of who you talked to before Threads.
  • The Spotify listening history that says what you played at every gym session for the last decade.
  • The LinkedIn connection graph and message archive.
  • The Google Calendar entries from a work account you no longer use.

None of this leaves your Mac. Ostler reads the export, extracts the structured facts (people, dates, conversations, places, media), and writes them into your local knowledge graph. The original ZIPs stay where you put them.

The typical wait#

Most platforms take 1 to 3 days to prepare an export and email you a download link. A few (TikTok, Spotify, Apple) can take up to 7 days, and Discord stretches close to the GDPR maximum of 30 days. Plan ahead: request what you want, then run the Ostler installer when the downloads start arriving. You do not have to wait for all of them. Ostler imports them as they appear in your downloads folder.

Where to put the files when they arrive#

Put each ZIP (or extracted folder) into one of these locations:

  • ~/Downloads (the default)
  • The folder you chose during install if you pointed Ostler at a different drive
  • ~/.ostler/imports/ if you want to be explicit

A background job scans these locations every four hours. You can also force an immediate import with ostler-import <path> from the Terminal once the Hub is set up.

The platforms#

Twitter / X#

  • What is included: every tweet, retweet, like, direct message, follower list, following list, lists, blocks, mutes, ad interaction history, and account settings going back to account creation.
  • Request URL: x.com/settings/download_your_data
  • How: log in on the web, scroll to Your account > Download an archive of your data, confirm with your password, and Twitter / X will email you when it is ready.
  • Wait: typically 24 to 48 hours.
  • Format: ZIP containing JS files (which behave like JSON) plus an HTML viewer.

Facebook (Meta)#

  • What is included: posts, photos, videos, messages (Messenger), reactions, comments, friend list, groups, events, pages followed, ad interactions, login history, marketplace activity.
  • Request URL: accountscenter.facebook.com/info_and_permissions/dyi
  • How: Account Centre > Your information and permissions > Download your information. Pick Some of your information if you want to be selective. Choose JSON format and High media quality.
  • Wait: typically 1 to 3 days.
  • Format: ZIP of JSON files (with a media subfolder).

Instagram#

  • What is included: posts, stories, reels, direct messages, comments, likes, saved posts, followers, following, profile information, login activity.
  • Request URL: accountscenter.instagram.com/info_and_permissions/dyi
  • How: the same Meta Account Centre flow as Facebook. If you have linked Facebook and Instagram in Account Centre you can request both in one bundle. Choose JSON format.
  • Wait: typically 1 to 3 days.
  • Format: ZIP of JSON files plus media.

LinkedIn#

  • What is included: connections, messages (InMail and standard), posts, articles, comments, profile history, work and education history, endorsements, recommendations, ad data.
  • Request URL: linkedin.com/mypreferences/d/download-my-data
  • How: Settings & Privacy > Data privacy > Get a copy of your data. Tick Want something in particular? for faster connection / message exports (those are available in about 10 minutes); for the full archive tick Download larger data archive.
  • Wait: 10 minutes for the fast archive, 24 hours for the full archive.
  • Format: ZIP of CSV files.

WhatsApp#

  • What is included: account information, settings, contact list, profile photo. Does not include message history in the official export, but does include the metadata Ostler uses to map a WhatsApp number to a person.
  • Request URL: faq.whatsapp.com/1180414079177245 (instructions)
  • How: on your phone, Settings > Account > Request account info > Request report. Confirm. The report lands in the same Settings screen 1 to 3 days later. Tap to download, then AirDrop or transfer to your Mac.
  • Wait: typically 1 to 3 days.
  • Format: ZIP containing a single HTML file plus a JSON file with structured account data.
  • Message history: export individual chats from each chat's menu (More > Export chat) if you want the conversation text. Ostler reads both formats.

Google Takeout (Gmail, Calendar, Drive, YouTube)#

  • What is included: anything you store with Google. The interesting parts for Ostler are Calendar (.ics), Contacts (vCard), Drive (files), YouTube (watch and search history), and Maps (timeline).
  • Request URL: takeout.google.com
  • How: sign in, deselect everything, then tick the products you want. Click Next step, choose Send download link via email, One-time export, file type .zip, and 2 GB chunks (so the archive arrives as several smaller files rather than one giant one).
  • Wait: typically a few hours to a few days depending on size.
  • Format: ZIP per chunk. Inside: JSON for most products, .ics for Calendar, vCard for Contacts, native file formats for Drive.

Gmail: use Apple Mail instead

For email specifically, do not use Takeout. The Takeout Mail export is an mbox file that is awkward to import incrementally and has no notion of "new mail since last import". Instead, add your Gmail account to Apple Mail (System Settings > Internet Accounts > Google > tick Mail) and Ostler reads from the local Apple Mail store. That gives you live, incremental, continuously-updated mail without holding a Google OAuth token. See Apple Mail FDA vs Google OAuth for the rationale.

Calendar, Drive, YouTube, and Maps are still worth pulling via Takeout.

TikTok#

  • What is included: profile, video posts, comments, likes, follower list, following list, watch history, search history, login history, direct messages.
  • Request URL: tiktok.com/setting/download-your-data
  • How: Settings > Account > Download your data > Request data. Choose JSON as the format (TikTok defaults to TXT, which Ostler can also read but JSON is cleaner).
  • Wait: up to 4 days.
  • Format: ZIP of JSON files (or TXT files if you do not change the default).

Spotify#

  • What is included: account profile, playlists you created, library (saved tracks, albums, podcasts), follow list, payment history. Full streaming history (every song you have ever played, with timestamps) is a separate request on the same page.
  • Request URL: spotify.com/account/privacy
  • How: scroll to Download your data. The default Account data export is the fast one. For the long streaming history tick Extended streaming history, which is the gold mine for any "what was I listening to in 2018" question.
  • Wait: Account data takes around 5 days. Extended streaming history takes up to 30 days. Request both at the same time.
  • Format: ZIP of JSON files.

YouTube#

YouTube is part of Google Takeout. See the Google Takeout entry above. Tick YouTube and YouTube Music in the product picker. You get:

  • Watch history (the big one)
  • Search history
  • Subscriptions
  • Comments, posts, live chat
  • Playlists
  • Uploaded videos (large; deselect if you do not want them)

Apple#

  • What is included: App Store and iTunes purchase history, App Store activity, iCloud Contacts, Calendar, Reminders, Notes, Safari bookmarks, Maps activity, Music library and listening history, Photos metadata, AppleCare history, Apple ID account data.
  • Request URL: privacy.apple.com
  • How: sign in with your Apple ID, tick Request a copy of your data, choose the categories. For Ostler the most useful are iCloud Contacts, iCloud Calendar, Apple Music listening history, and Safari bookmarks and reading list. (You can skip iCloud Photos, iMessage, and Notes here, because Ostler reads those live from the Mac.)
  • Wait: up to 7 days.
  • Format: ZIP containing CSV files for most categories.

Telegram#

  • What is included: account information, contacts, chat history (groups, channels, private chats), media attachments, sticker sets, settings.
  • Request URL: telegram.org/blog/export-and-more (explainer; the actual export is initiated from Telegram Desktop)
  • How: the export is only available in Telegram Desktop for macOS or Windows. Open Telegram Desktop > Settings > Advanced > Export Telegram data. Tick what you want (Personal chats and Private groups for Ostler), choose Machine-readable JSON format, and start. The export saves locally to a folder you pick.
  • Wait: runs locally; finishes in minutes to hours depending on size.
  • Format: folder (or ZIP it yourself) containing JSON files plus media.

Discord#

  • What is included: account information, servers (guilds) you are in, your messages in every channel and DM, your activity timestamps, payment history.
  • Request URL: Discord settings > Privacy & Safety > Request all of my data (sign in at discord.com on the web).
  • How: User Settings > Privacy & Safety, scroll to the bottom, click Request all of my data, confirm with the email Discord sends you.
  • Wait: typically 30 days (Discord stretches close to the GDPR maximum, plan ahead).
  • Format: ZIP of JSON files.

Reddit#

  • What is included: profile, posts, comments, votes, saved items, sent and received messages, subscribed subreddits, friends, blocked users.
  • Request URL: reddit.com/settings/data-request
  • How: sign in on the web, go to the data-request page, choose GDPR (this gives you the most data even if you are not in the EU, and Reddit honours the request worldwide), tick Generate a new request.
  • Wait: typically up to 30 days, usually much faster (a few days).
  • Format: ZIP of CSV files.

After you have the files#

Once one or more exports are sitting in ~/Downloads, the Hub picks them up on its four-hourly import scan. To force an import immediately:

ostler-import ~/Downloads/instagram-yourusername-2026-05.zip

You can also point Ostler at a folder full of exports:

ostler-import ~/Downloads

The importer is idempotent. Running it twice on the same archive is safe; nothing is duplicated.

To see what got imported, open the Hub's diagnostic dashboard at localhost:8089/doctor and look at the Imports tab.

Troubleshooting#

The file is too big to email#

Most platforms give you a download link rather than emailing the file directly, so the file size is not usually an issue at request time. If you are receiving small chunks (Google Takeout splits exports into 2 GB pieces by default) just put all the chunks in ~/Downloads and Ostler reassembles them.

If the export is genuinely a single multi-gigabyte file, leave it where it is on disk and pass the path directly to ostler-import. The importer reads from disk; it does not need to copy the file anywhere.

The ZIP is password-protected#

A few platforms (TikTok in some regions, Discord for certain account types) password-protect the ZIP and email you the password separately. When Ostler hits a protected archive it stops and prompts you for the password in the Doctor dashboard. You can also unzip it yourself first (using the password from the email) and point Ostler at the resulting folder.

Ostler does not recognise the file format#

Run:

ostler-import --probe <path>

That tells you which platform the importer thinks the file came from and which adapter would run. If the answer is "unknown", the platform may have changed its export shape (this happens once or twice a year per platform). Email [email protected] with the file name and a screenshot of the request page; we add new shapes in patch releases.

The import is taking ages#

Large Spotify extended streaming histories or Facebook archives can take 10 to 20 minutes to process on the first run because Ostler is building embeddings and writing graph entries. Subsequent imports of the same platform are incremental and much faster. The Doctor dashboard shows progress.

I requested it weeks ago and the email never came#

Check your spam folder first. If it really has been swallowed, request again; most platforms will let you. Discord and Spotify are the slowest; Twitter / X and LinkedIn are the fastest.

If your platform is not listed#

Email [email protected] with the name of the platform, the URL of its data-export page, and (if you have one) the export file itself or a screenshot of its structure. We add new adapters in patch releases. Common requests so far: Strava, Garmin Connect, Goodreads, Letterboxd, Notion, Slack, Signal, Bluesky, Mastodon.

If the platform does not offer an export at all, ask them. Under UK GDPR Article 20 (right to data portability) and equivalent CCPA provisions, they are obliged to provide one in a structured, commonly-used, machine-readable format on request. A friendly email to their privacy team almost always gets a response within 30 days.