Clearing Browsing Data with the browsingData API

A privacy tool needs a “clear this site” button; a developer utility needs to wipe a web app’s caches and service workers between test runs; a kiosk extension clears everything when a session ends. All of them reach for chrome.browsingData, and all of them meet the same surprises: the call succeeds but some data remains, an origin filter is silently ignored for history, and clearing cookies logs the user out of sites they did not expect. The API is powerful and coarse-grained, and using it well means knowing exactly what each option touches. This guide sits under browser data APIs for bookmarks, history and downloads.

What the API can and cannot target

chrome.browsingData.remove(options, dataToRemove) deletes the selected types of data — cache, cookies, history, downloads list, form data, passwords, local storage, IndexedDB, cache storage, service workers, file systems and more — that were created after options.since. Optionally, options.origins limits the deletion to listed origins, or options.excludeOrigins protects them. The catch is that origin filtering applies only to data types that are naturally keyed by origin: cookies, local storage, IndexedDB, cache storage, service workers, file systems and the HTTP cache. History, downloads, form data and passwords are not filterable by origin and are rejected if you combine them with origins. And originTypes decides whether data belonging to installed web apps (“protectedWeb”) and extensions is included — by default, only ordinary web data is cleared.

Step-by-step: precise clearing

1. Declare the permission

1{ "permissions": ["browsingData", "activeTab"] }

Execution context: the manifest. browsingData shows an install warning in Chrome (“Clear browsing data” — and reviewers will ask why). It does not need host permissions; origins are passed as data. activeTab is only needed if you want to read the current tab’s URL to offer “clear this site”.

2. Clear one site’s storage

 1// sw.js
 2export async function clearSite(origin) {
 3  await chrome.browsingData.remove(
 4    { origins: [origin] },                                // e.g. "https://app.example.com"
 5    {
 6      cookies: true,
 7      localStorage: true,
 8      indexedDB: true,
 9      cacheStorage: true,
10      serviceWorkers: true,
11      cache: true,
12      fileSystems: true,
13    }
14  );
15}

Execution context: the service worker or an extension page. Origins must be exact — scheme, host and port, no path or trailing slash. Clearing cookies for https://app.example.com does not remove domain cookies set for .example.com that are sent to other subdomains; to sign out completely, include each origin the site uses, or remove specific cookies with chrome.cookies. Omitting since clears all time.

3. Clear history and caches for a time range

1export async function clearLastHour() {
2  await chrome.browsingData.remove(
3    { since: Date.now() - 60 * 60 * 1000 },
4    { history: true, downloads: true, cache: true, formData: true }
5  );
6}

Execution context: the service worker. since is milliseconds since the epoch; everything created after it is removed. Types that cannot be filtered by origin — history, downloads, form data — can only be cleared this way. Combining them with origins throws “origin filtering is not supported for …”. Clearing the downloads list removes entries from chrome://downloads, not the files on disk.

4. Protect sites the user wants to keep

1export async function clearEverythingExcept(keepOrigins) {
2  await chrome.browsingData.remove(
3    { excludeOrigins: keepOrigins },
4    { cookies: true, localStorage: true, indexedDB: true, cacheStorage: true, serviceWorkers: true }
5  );
6}

Execution context: the service worker. excludeOrigins is the inverse of origins — clear everywhere except these — and has the same type restrictions. It is the right tool for “clear everything except my email and bank” features. You cannot pass both origins and excludeOrigins in one call.

5. Decide about installed web apps and extensions

1await chrome.browsingData.remove(
2  { since: 0, originTypes: { unprotectedWeb: true, protectedWeb: false, extension: false } },
3  { localStorage: true, indexedDB: true }
4);

Execution context: the service worker. unprotectedWeb is ordinary sites (the default). protectedWeb covers sites installed as apps; clearing them can wipe offline data the user expects to keep. extension covers all extensions’ storage, including your own — almost never what you want. Leave the defaults unless your feature specifically targets those categories, and say so in the UI.

6. Confirm before destructive actions

1// popup.js
2clearBtn.addEventListener("click", async () => {
3  const origin = new URL((await chrome.tabs.query({ active: true, currentWindow: true }))[0].url).origin;
4  if (!confirm(`Clear cookies and site data for ${origin}? You will be signed out.`)) return;
5  await chrome.runtime.sendMessage({ type: "clear-site", origin });
6});

Execution context: the popup. Clearing data is irreversible, and “signed out of every account on this site” surprises users. A plain confirmation names the consequence. For scheduled or automatic clearing, show what was cleared afterwards in the popup or a notification so the user can connect cause and effect.

7. Report what was cleared

1export async function clearSiteWithReport(origin) {
2  const before = await chrome.cookies.getAll({ url: origin });
3  await clearSite(origin);
4  const after = await chrome.cookies.getAll({ url: origin });
5  return { origin, cookiesRemoved: before.length - after.length, at: Date.now() };
6}

Execution context: the service worker, with the cookies permission and host access for the origin if you want counts. browsingData.remove resolves without saying how much it removed; a before-and-after count for the types you can observe gives the user feedback (“Removed 14 cookies and all site storage for app.example.com”) and gives you a way to notice when clearing silently does nothing — usually because the origin string was malformed. Keep a short history of clear actions in local storage so a user who wonders why they were signed out can see that the extension did it, and when.

Common mistakes

• Mixing history with origins. The call throws; split into two calls.
• Expecting domain cookies to be cleared. Origin filters match exact origins; .example.com cookies remain.
• Clearing extension data accidentally. Setting originTypes.extension: true wipes your own storage too.
• Origins with paths. "https://example.com/app" is not an origin; strip to new URL(u).origin.
• No user confirmation. Unexpected sign-outs are a common source of one-star reviews.

Cross-browser variation

• Chrome / Edge: full API including origins, excludeOrigins and originTypes.
• Firefox: browser.browsingData supports a smaller set of types and filters by hostnames (not full origins) for cookies, local storage and a few others; excludeOrigins is not supported. Check browser.browsingData.settings() for what the user’s Firefox can clear.
• Safari: no browsingData API. Use cookies.remove for cookies; other site data cannot be cleared from an extension.

Verification

1. Open a test site that sets cookies, local storage and a service worker; confirm them in DevTools → Application.
2. Run clearSite("https://test.example") from the worker console.
3. Reload DevTools → Application: storage, cookies and service worker registrations are gone for that origin and untouched for others.
4. Run clearLastHour() and confirm recent history entries disappear from chrome://history.

FAQ

Can I clear data for a single tab?

No. Data belongs to origins and profiles, not tabs. Clear the tab’s origin.

Does clearing cache stop a page’s service worker immediately?

The registration is removed, but an open page keeps its running worker until reload. Reload affected tabs afterwards.

Can I clear incognito data?

Incognito data is discarded when the incognito session ends; browsingData targets the regular profile.

Related

• Searching and pruning browsing history — removing specific history entries.
• Reacting to cookie changes — noticing the sign-out you caused.
• Justifying sensitive data permissions — explaining browsingData to reviewers.
• Browser data APIs: bookmarks, history and downloads — the parent topic.