sessions Permission

6 min read

sessions Permission

Overview

API Methods

chrome.sessions.getRecentlyClosed(filter?)

Gets a list of recently closed tabs/windows.

interface Filter {
  maxResults?: number; // Default: 25, Maximum: 25
}

interface Session {
  lastModified: number; // Timestamp in milliseconds
  tab?: Tab;           // Present if closed item was a tab
  window?: Window;     // Present if closed item was a window
}

// Returns array of Session objects
const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 10 });

chrome.sessions.restore(sessionId?)

Restores a closed tab or window.

// Omit sessionId to restore most recently closed item
const restored = await chrome.sessions.restore();

// Restore a specific session
const restored = await chrome.sessions.restore(sessionId);

// Returns the restored Session object

chrome.sessions.getDevices(filter?)

Gets tabs from other signed-in devices.

interface Filter {
  maxResults?: number;
}

interface Device {
  deviceName: string;   // Name of the other device
  sessions: Session[]; // Sessions from that device
}

// Returns array of Device objects
const devices = await chrome.sessions.getDevices({ maxResults: 10 });

Types

Session

{
  lastModified: number;    // Unix timestamp
  tab?: chrome.tabs.Tab;   // Tab object (either tab OR window, not both)
  window?: chrome.windows.Window; // Window object
}

Device

{
  deviceName: string;     // e.g., "Mike's MacBook Pro"
  sessions: Session[];    // Array of sessions from this device
}

Constants

Events

Manifest Declaration

{
  "permissions": ["sessions"]
}

Note: Also needs "tabs" permission to see tab URLs/titles.

Use Cases

Session Restore UI

Build a “recently closed” dropdown showing tabs the user can reopen:

async function getRecentlyClosedTabs() {
  const sessions = await chrome.sessions.getRecentlyClosed();
  return sessions
    .filter(s => s.tab)
    .map(s => ({
      title: s.tab?.title,
      url: s.tab?.url,
      lastModified: s.lastModified
    }));
}

“Undo Close Tab” Feature

Implement keyboard shortcut to restore the most recent tab:

// Restore most recently closed tab
async function undoCloseTab() {
  const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 1 });
  if (sessions.length > 0) {
    await chrome.sessions.restore(sessions[0].tab?.sessionId);
  }
}

Cross-Device Tab Access

Show tabs from other signed-in devices:

async function getCrossDeviceTabs() {
  const devices = await chrome.sessions.getDevices();
  const allTabs: Array<{ device: string; title: string; url: string }> = [];
  
  for (const device of devices) {
    for (const session of device.sessions) {
      if (session.tab) {
        allTabs.push({
          device: device.deviceName,
          title: session.tab.title || "Untitled",
          url: session.tab.url || ""
        });
      }
    }
  }
  return allTabs;
}

Store Session Snapshots with @theluckystrike/webext-storage

import { createStorage, defineSchema } from "@theluckystrike/webext-storage";

const schema = defineSchema({
  sessionSnapshots: [] as Array<{
    id: string;
    tabs: Array<{ title: string; url: string }>;
    savedAt: number;
  }>
});

const storage = createStorage({ schema });

async function saveSessionSnapshot() {
  const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 25 });
  const snapshot = {
    id: crypto.randomUUID(),
    tabs: sessions
      .filter(s => s.tab)
      .map(s => ({ title: s.tab!.title || "", url: s.tab!.url || "" })),
    savedAt: Date.now()
  };
  
  const snapshots = await storage.get("sessionSnapshots");
  await storage.set("sessionSnapshots", [snapshot, ...snapshots].slice(0, 10));
}

Cross-references

Frequently Asked Questions

What can I do with the sessions API?

chrome.sessions allows your extension to query and restore recently closed tabs and windows, useful for session management extensions.

Can I sync sessions across devices?

Sessions API provides local session data only. For cross-device sync, you’d need to implement your own cloud storage. —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article
No next article