mdn · rebloor · Jun 23, 2026 · Jun 16, 2026 · Jun 18, 2026 · Jun 18, 2026
@@ -34,7 +34,7 @@ Events have three functions:
     - `request`
       - : An object containing information about the request the rule matched.
         - `documentId` {{optional_inline}}
-          - : A `string`. The unique identifier for the frame's document, if this request is for a frame.
+          - : A `string`. The unique identifier for the frame's document, if this request is for a frame. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
         - `documentLifecycle` {{optional_inline}}
           - : A `string`. The lifecycle of the frame's document, if this request is for a frame. Possible values are: `"prerender"`, `"active"`, `"cached"`, or `"pending_deletion"`.
         - `frameId`
@@ -46,7 +46,7 @@ Events have three functions:
         - `method`
           - : A `string`. A standard HTTP method.
         - `parentDocumentId` {{optional_inline}}
-          - : A `string`. The unique identifier for the frame's parent document, if this request is for a frame and has a parent.
+          - : A `string`. The unique identifier for the frame's parent document, if this request is for a frame and has a parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
         - `parentFrameId`
           - : A `number`. The ID of the frame that wraps the frame which sent the request. Set to `-1` if there is no parent frame.
         - `requestId`

@@ -14,6 +14,8 @@ Values of this type are objects. They contain the following properties:
 
 - `cookieStoreId`
   - : `string`. The cookie store ID of the current context. See [Work with contextual identities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities) for more information.
+- `documentId` {{optional_inline}}
+  - : `string`. The UUID of the document making the request. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentUrl`
   - : `string`. URL of the page into which the requested resource will be loaded.
 - `frameId`
@@ -26,6 +28,8 @@ Values of this type are objects. They contain the following properties:
   - : `string`. Standard HTTP method: for example, "GET" or "POST".
 - `originUrl`
   - : `string`. URL of the resource that triggered the request. Note that this may not be the same as the URL of the page into which the requested resource will be loaded. For example, if a document triggers a load in a different window through the [target attribute of a link](/en-US/docs/Web/HTML/Reference/Elements/a#target), or a CSS document includes an image using the [`url()` functional notation](/en-US/docs/Web/CSS/Reference/Values/url_function), then this is the URL of the original document or of the CSS document, respectively.
+- `parentDocumentId` {{optional_inline}}
+  - : `string`. A UUID of the parent document that owns the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `parentFrameId`
   - : `integer`. ID of the frame that contains the frame that sent the request. Set to -1 if no parent frame exists.
 - `requestId`

@@ -25,7 +25,7 @@ let gettingContexts = await browser.runtime.getContexts(
     - `contextTypes` {{optional_inline}}
       - : An array of `string`. The types of extension views associated with contexts to return. Takes the values `"BACKGROUND"`, `"POPUP"`, `"SIDE_PANEL"`, and `"TAB"`.
     - `documentIds` {{optional_inline}}
-      - : An array of `string`. UUIDs of documents associated with the contexts to return.
+      - : An array of `string`. UUIDs of documents associated with the contexts to return. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
     - `documentOrigins` {{optional_inline}}
       - : An array of `string`. The origins of documents associated with the contexts to return.
     - `documentUrls` {{optional_inline}}
@@ -48,7 +48,7 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that
 - `contextType`
   - : `string`. The type of extension view. Returned as one of `"BACKGROUND"`, `"POPUP"`, `"SIDE_PANEL"`, or `"TAB"`.
 - `documentId`
-  - : `string`. UUID of the document associated with the context, or undefined if the context is not hosted in a document.
+  - : `string`. UUID of the document associated with the context, or undefined if the context is not hosted in a document. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentOrigin`
   - : `string`. The origin of the document associated with the context or undefined if the context is not hosted in a document.
 - `documentUrl`

@@ -0,0 +1,43 @@
+---
+title: runtime.getDocumentId()
+slug: Mozilla/Add-ons/WebExtensions/API/runtime/getDocumentId
+page-type: webextension-api-function
+browser-compat: webextensions.api.runtime.getDocumentId
+sidebar: addonsidebar
+---
+
+Returns the document ID of any window global or frame element. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
+
+## Syntax
+
+```js-nolint
+let documentId = browser.runtime.getDocumentId(
+  target               // object
+)
+```
+
+### Parameters
+
+- `target`
+  - : A {{glossary("WindowProxy")}} or a {{glossary("browsing context")}} container {{DOMxRef("Element","element")}} (iframe, frame, embed, or object) for the target frame.
+
+### Return value
+
+Returns the document UUID of the target. Throws an error if the window or frame was unloaded.
+
+## Examples
+
+This code gets the document IDs of the top-level frame and its child frames:
+
+```js
+const documentId = browser.runtime.getDocumentId(window);
+const frameDocumentId = browser.runtime.getDocumentId(
+  document.querySelector("iframe"),
+);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -50,6 +50,8 @@ It also provides messaging APIs enabling you to:
 
 - {{WebExtAPIRef("runtime.getBackgroundPage()")}}
   - : Retrieves the [Window](/en-US/docs/Web/API/Window) object for the background page running inside the current extension.
+- {{WebExtAPIRef("runtime.getDocumentId()")}}
+  - : Returns the document ID of any window global or frame element.
 - {{WebExtAPIRef("runtime.openOptionsPage()")}}
   - : Opens your extension's [options page](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages).
 - {{WebExtAPIRef("runtime.getContexts()")}}

@@ -8,14 +8,17 @@ sidebar: addonsidebar
 
 An object containing information about the sender of a message or connection request that is passed to the {{WebExtAPIRef("runtime.onMessage()")}} listener.
 
-It is also a property of {{WebExtAPIRef("runtime.Port")}}, but only in the `Port` instance passed into the {{WebExtAPIRef("runtime.onConnect()")}} or {{WebExtAPIRef("runtime.onConnectExternal()")}} listeners.
+Available for:
+
+- connections in the {{WebExtAPIRef("runtime.onConnect")}}, {{WebExtAPIRef("runtime.onConnectExternal")}}, and {{WebExtAPIRef("runtime.onUserScriptConnect")}} listeners. In the {{WebExtAPIRef("runtime.onConnect()")}} and {{WebExtAPIRef("runtime.onConnectExternal()")}} listeners, it's a property of the `port` argument ({{WebExtAPIRef("runtime.Port")}}).
+- messages in {{WebExtAPIRef("runtime.onMessage")}}, {{WebExtAPIRef("runtime.onMessageExternal")}}, and {{WebExtAPIRef("runtime.onUserScriptMessage")}} listeners.
 
 ## Type
 
 Values of this type are objects. They contain the following properties:
 
 - `documentId` {{optional_inline}}
-  - : `string`. A UUID of the document that opened the connection.
+  - : `string`. A UUID of the document that opened the connection. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle` {{optional_inline}}
   - : `string`. The lifecycle state the document that opened the connection was in when the port was created. Note that the lifecycle state of the document may have changed since the port was created.
 - `frameId` {{optional_inline}}

@@ -53,7 +53,7 @@ The promise is rejected if the injection fails, such as when the injection targe
 Each `InjectionResult` object has these properties:
 
 - `documentId`
-  - : `string`. The document associated with the injection.
+  - : `string`. The document associated with the injection. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `frameId`
   - : `number`. The frame ID associated with the injection.
 - `result` {{optional_inline}}

@@ -16,7 +16,7 @@ Values of this type are objects. They contain these properties:
   - : `boolean`. Whether the script or CSS is injected into all frames within the tab. Defaults to `false`. Cannot be `true` if `frameIds` is specified.
 
 - `documentIds` {{optional_inline}}
-  - : `array` of `string`. The IDs of the documents to inject into. Must not be specified if `frameIds` is set.
+  - : `array` of `string`. The IDs of the documents to inject into. Must not be specified if `frameIds` is set. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 
 - `frameIds` {{optional_inline}}
   - : `array` of `number`. Array of the IDs of the frames to inject into. Must not be specified if `documentIds` is set.

@@ -28,7 +28,7 @@ browser.tabs.connect(
 - `connectInfo` {{optional_inline}}
   - : An object with the following properties:
     - `documentId` {{optional_inline}}
-      - : `string`. Open a port to a specific document identified by `documentId` instead of all frames in the tab.
+      - : `string`. Open a port to a specific document, instead of all frames in the tab. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
     - `name` {{optional_inline}}
       - : `string`. Will be passed into {{WebExtAPIRef("runtime.onConnect")}} event listeners in content scripts belonging to this extension and running in the specified tab.
     - `frameId` {{optional_inline}}

@@ -34,9 +34,9 @@ const sending = browser.tabs.sendMessage(
 - `options` {{optional_inline}}
   - : `object`.
     - `documentId` {{optional_inline}}
-      - : `string`. Send a message to a specific document identified by `documentId` instead of all frames in the tab.
+      - : `string`. Send a message to a specific document, instead of all frames in the tab. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
     - `frameId` {{optional_inline}}
-      - : `integer`. Sends the message to a specific frame identified by `frameId` instead of all frames in the tab. Whether the content script is executed in all frames depends on the `all_frames` setting in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) section of `manifest.json`.
+      - : `integer`. Sends the message to a specific frame, instead of all frames in the tab. Whether the content script is executed in all frames depends on the `all_frames` setting in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) section of `manifest.json`.
 
 ### Return value
 

@@ -33,7 +33,7 @@ let executeUserScript = browser.userScripts.execute(
         - `allFrames` {{optional_inline}}
           - : `boolean`. If set to `true`, the script is injected into all available frames. Defaults to `false`, in which the script is only injected into the top frame.
         - `documentIds` {{optional_inline}}
-          - : `array` of `string`. The IDs of the documents to inject into. Must not be specified if `frameIds` is set.
+          - : `array` of `string`. The IDs of the documents to inject into. Must not be specified if `frameIds` is set. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
         - `frameIds` {{optional_inline}}
           - : `array` of `integer`. The IDs of the frames to inject into. Must not be specified if `documentIds` is set.
         - `tabId`
@@ -48,7 +48,7 @@ let executeUserScript = browser.userScripts.execute(
 A {{JSxRef("Promise")}} fulfilled with an array of objects describing the outcome of the injection with these properties:
 
 - `documentId`
-  - : `string`. Document ID associated with the injection.
+  - : `string`. Document ID associated with the injection. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `error` {{optional_inline}}
   - : `string`. Error message if any. This is mutually exclusive with `result`
 - `frameId`

@@ -40,9 +40,9 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that
 - `parentFrameId`
   - : `integer`. ID of this frame's parent. This is -1 if there is no parent frame: that is, if this frame is the top-level browsing context in the tab.
 - `documentId`
-  - : `string`. A UUID of the frame's document.
+  - : `string`. A UUID of the frame's document. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `parentDocumentId`
-  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent.
+  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle`
   - : `string`. The lifecycle the document is in. Returns the values `"prerender"`, `"active"`, `"cached"`, or `"pending_deletion"`.
 - `processId` {{optional_inline}} {{deprecated_inline}}

@@ -21,17 +21,15 @@ let gettingFrame = browser.webNavigation.getFrame(
 ### Parameters
 
 - `details`
-  - : `object`. Information about the frame to retrieve information about. Must include one of `tabId`, `frameId`, or `documentId`.
+  - : `object`. Information about the frame to retrieve. Must include either `documentId`, or `tabId` and `frameId`.
     - `tabId` {{optional_inline}}
-      - : `integer`. The ID of the tab in which the frame is.
+      - : `integer`. The ID of the tab in which the frame is. Required if `documentId` is not specified.
     - `processId` {{optional_inline}} {{deprecated_inline}}
       - : `integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.
     - `frameId` {{optional_inline}}
-      - : `integer`. The ID of the frame in the given tab.
+      - : `integer`. The ID of the frame in the given tab. Required if `documentId` is not specified.
     - `documentId` {{optional_inline}}
-      - : `string`. The UUID of the frame's document.
-
-Must include one of
+      - : `string`. The UUID of the frame's document. If `tabId` and `frameId` are also specified, the frame is only returned if all properties match. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 
 ### Return value
 
@@ -46,9 +44,9 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that
 - `parentFrameId`
   - : `integer`. ID of this frame's parent. This is -1 if there is no parent frame: that is, if this frame is the top-level browsing context in the tab.
 - `documentId`
-  - : `string`. A UUID of the frame's document.
+  - : `string`. A UUID of the frame's document. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `parentDocumentId`
-  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent.
+  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle`
   - : `string`. The lifecycle the document is in. Returns the values `"prerender"`, `"active"`, `"cached"`, or `"pending_deletion"`.
 

@@ -56,7 +56,9 @@ Events have three functions:
 - `parentFrameId`
   - : `integer`. ID of this frame's parent. Set to `-1` if this is a top-level frame.
 - `parentDocumentId`
-  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent.
+  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
+    > [!NOTE]
+    > This event doesn't include `documentId` because the navigation's target document doesn't exist when the event fires. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle`
   - : `string`. The lifecycle the document is in. Returns the values `"prerender"`, `"active"`, `"cached"`, or `"pending_deletion"`.
 - `timeStamp`

@@ -55,9 +55,9 @@ Events have three functions:
 - `parentFrameId`
   - : `integer`. ID of this frame's parent. Set to `-1` if this is a top-level frame.
 - `documentId`
-  - : `string`. A UUID of the document loaded.
+  - : `string`. A UUID of the document loaded. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `parentDocumentId`
-  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent.
+  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle`
   - : `string`. The lifecycle the document is in. Returns the values `"prerender"`, `"active"`, `"cached"`, and `"pending_deletion"`.
 - `transitionType`

@@ -55,9 +55,9 @@ Events have three functions:
 - `parentFrameId`
   - : `integer`. ID of this frame's parent. Set to `-1` if this is a top-level frame.
 - `documentId`
-  - : `string`. A UUID of the document loaded.
+  - : `string`. A UUID of the document loaded. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `parentDocumentId`
-  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent.
+  - : `string`. A UUID of the parent document owning the frame. Not set if there is no parent. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
 - `documentLifecycle`
   - : `string`. The lifecycle the document is in. Returns the values `"prerender"`, `"active"`, `"cached"`, and `"pending_deletion"`.
 - `timeStamp`

@@ -15,6 +15,9 @@ The event is not sent if a tab or window is created without a navigation target
 
 If this event is fired, it will be fired before {{WebExtAPIRef("webNavigation.onBeforeNavigate")}}.
 
+> [!NOTE]
+> This event doesn't include `documentId`, `frameId`, `parentDocumentId`, or `parentFrameId` because the navigation's target document don't exist when the event fires. See the [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) article for more information.
+
 ## Syntax
 
 ```js-nolint