diff --git a/files/en-us/web/api/notrestoredreasondetails/index.md b/files/en-us/web/api/notrestoredreasondetails/index.md
new file mode 100644
index 000000000000000..1e6f606e4d32114
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasondetails/index.md
@@ -0,0 +1,41 @@
+---
+title: NotRestoredReasonDetails
+slug: Web/API/NotRestoredReasonDetails
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.NotRestoredReasonDetails
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`NotRestoredReasonDetails`** interface of the {{domxref("Performance API", "Performance API", "", "nocode")}} represents a single reason why a navigated page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+An array of `NotRestoredReasonDetails` objects can be accessed via the {{domxref("NotRestoredReasons.reasons")}} property.
+
+## Instance properties
+
+- {{domxref("NotRestoredReasonDetails.reason", "reason")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string describing a reason that the page was blocked from using the back/forward cache.
+
+## Instance methods
+
+- {{domxref("NotRestoredReasonDetails.toJSON", "toJSON()")}} {{Experimental_Inline}}
+  - : A {{Glossary("Serialization","serializer")}}; returns a JSON representation of the {{domxref("NotRestoredReasonDetails")}} object.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasondetails/reason/index.md b/files/en-us/web/api/notrestoredreasondetails/reason/index.md
new file mode 100644
index 000000000000000..e077f5fe7e4d046
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasondetails/reason/index.md
@@ -0,0 +1,63 @@
+---
+title: "NotRestoredReasonDetails: reason property"
+short-title: reason
+slug: Web/API/NotRestoredReasonDetails/reason
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasonDetails.reason
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`reason`** read-only property of the
+{{domxref("NotRestoredReasonDetails")}} interface returns a string describing a reason that the page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+## Value
+
+A string.
+
+There are many different reasons why blocking could occur, and browsers can choose to implement their own specific reasons for blocking, based on how they operate. Developers should avoid depending on specific wording for reasons and be prepared to handle new reasons being added and deleted.
+
+The initial values listed in the specification are:
+
+- `"fetch"`
+  - : While unloading, a fetch initiated by the current document (e.g. via {{domxref("fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache.
+- `"lock"`
+  - : While unloading, held locks and lock requests were terminated, so the page was not in a stable state that could be stored in the bfcache.
+- `"masked"`
+  - : The exact reason is hidden for privacy purposes. This value can mean one of the following:
+    - The current document has children contained in a cross-origin {{htmlelement("iframe")}}, and they prevented storage in the bfcache.
+    - The current Document could not be stored in the bfcache for user agent-specific reasons.
+- `"navigation-failure"`
+  - : The original navigation that created the current document errored, and storing the resulting error document in the bfcache was prevented.
+- `"parser-aborted"`
+  - : The current document never finished its initial HTML parsing, and storing the unfinished document in the bfcache was prevented.
+- `"websocket"`
+  - : While unloading, an open [WebSocket](/en-US/docs/Web/API/WebSockets_API) connect was shut down, so the page was not in a stable state that could be stored in the bfcache.
+
+Additional blocking reasons may be used by some browsers, for example:
+
+- `"unload-listener"`
+  - : The page registers an [`unload`](/en-US/docs/Web/API/Window/unload_event) handler, which prevents bfcache usage. This serves as a useful warning, as `unload` is deprecated. See [Deprecating the unload event](https://developer.chrome.com/docs/web-platform/deprecating-unload) for more information.
+- `"response-cache-control-no-store"`
+  - : The page uses `no-store` as a {{httpheader("Cache-Control")}} header value.
+- `"related-active-contents"`
+  - : The page was opened from another page that still has a reference to this page, for example using "duplicate tab" functionality.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasondetails/tojson/index.md b/files/en-us/web/api/notrestoredreasondetails/tojson/index.md
new file mode 100644
index 000000000000000..ec87afcc2e08b05
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasondetails/tojson/index.md
@@ -0,0 +1,52 @@
+---
+title: "NotRestoredReasonDetails: toJSON() method"
+short-title: toJSON()
+slug: Web/API/NotRestoredReasonDetails/toJSON
+page-type: web-api-instance-method
+browser-compat: api.NotRestoredReasonDetails.toJSON
+spec-urls: https://html.spec.whatwg.org/multipage/nav-history-apis.html#notrestoredreasondetails
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`toJSON()`** method of the {{domxref("NotRestoredReasonDetails")}} interface is a {{Glossary("Serialization","serializer")}}; it returns a JSON representation of the {{domxref("NotRestoredReasonDetails")}} object.
+
+## Syntax
+
+```js-nolint
+toJSON()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref("JSON")}} object that is the serialization of the {{domxref("NotRestoredReasonDetails")}} object.
+
+## Examples
+
+The following function will return a JSON representation of the first `NotRestoredReasonDetails` object of the `NotRestoredReasons` object from the first `PerformanceNavigationTiming` object currently present in the performance timeline:
+
+```js
+function returnNRR() {
+  const navEntries = performance.getEntriesByType("navigation");
+  let navEntry = navEntries[0];
+  return navEntry.notRestoredReasons.reasons[0].toJSON();
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("JSON")}}
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/children/index.md b/files/en-us/web/api/notrestoredreasons/children/index.md
new file mode 100644
index 000000000000000..e59173ae5f4305a
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/children/index.md
@@ -0,0 +1,39 @@
+---
+title: "NotRestoredReasons: children property"
+short-title: children
+slug: Web/API/NotRestoredReasons/children
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.children
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`children`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns an array of {{domxref("NotRestoredReasons")}} objects, one for each child {{htmlelement("iframe")}} embedded in the current document, which may contain reasons why the top-level frame was blocked relating to the child frames.
+
+Each object has the same structure as the parent object — this way, any number of levels of embedded `<iframe>`s can be represented inside the object recursively.
+
+## Value
+
+An array of {{domxref("NotRestoredReasons")}} objects.
+
+If the frame has no children, the array will be empty; if the document is in a cross-origin `<iframe>`, `children` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/id/index.md b/files/en-us/web/api/notrestoredreasons/id/index.md
new file mode 100644
index 000000000000000..6055a6acf6ef2e3
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/id/index.md
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: id property"
+short-title: id
+slug: Web/API/NotRestoredReasons/id
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.id
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`id`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the `id` attribute value of the {{htmlelement("iframe")}} the document is contained in (for example `<iframe id="foo" src="...">`).
+
+## Value
+
+A string.
+
+If the document is not in an `<iframe>` or the `<iframe>` has no `id` set, `id` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/index.md b/files/en-us/web/api/notrestoredreasons/index.md
new file mode 100644
index 000000000000000..7640a90fb5be3cb
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/index.md
@@ -0,0 +1,51 @@
+---
+title: NotRestoredReasons
+slug: Web/API/NotRestoredReasons
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`NotRestoredReasons`** interface of the {{domxref("Performance API", "Performance API", "", "nocode")}} provides report data containing reasons why the current document was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache) on navigation.
+
+These objects are accessed via the {{domxref("PerformanceNavigationTiming.notRestoredReasons")}} property.
+
+## Instance properties
+
+- {{domxref("NotRestoredReasons.children", "children")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : An array of {{domxref("NotRestoredReasons")}} objects, one for each child {{htmlelement("iframe")}} embedded in the current document, which may contain reasons why the top-level frame was blocked relating to the child frames. Each object has the same structure as the parent object — this way, any number of levels of embedded `<iframe>`s can be represented inside the object recursively. If the frame has no children, the array will be empty; if the document is in a cross-origin `<iframe>`, `children` will return `null`.
+- {{domxref("NotRestoredReasons.id", "id")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the `id` attribute value of the `<iframe>` the document is contained in (for example `<iframe id="foo" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `id` set, `id` will return `null`.
+- {{domxref("NotRestoredReasons.name", "name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the `name` attribute value of the `<iframe>` the document is contained in (for example `<iframe name="bar" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `name` set, `name` will return `null`.
+- {{domxref("NotRestoredReasons.reasons", "reasons")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : An array of {{domxref("NotRestoredReasonDetails")}} objects, each representing a reason why the navigated page was blocked from using the bfcache. If the document is in a cross-origin `<iframe>`, `reasons` will return `null`, but the parent document may show a `reason` of `"masked"` if any `<iframe>`s blocked bfcache usage for the top-level frame.
+- {{domxref("NotRestoredReasons.src", "src")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the path to the source of the `<iframe>` the document is contained in (for example `<iframe src="exampleframe.html">`). If the document is not in an `<iframe>`, `src` will return `null`.
+- {{domxref("NotRestoredReasons.url", "url")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the URL of the navigated page or `<iframe>`. If the document is in a cross-origin `<iframe>`, `url` will return `null`.
+
+## Instance methods
+
+- {{domxref("NotRestoredReasons.toJSON", "toJSON()")}} {{Experimental_Inline}}
+  - : A {{Glossary("Serialization","serializer")}}; returns a JSON representation of the {{domxref("NotRestoredReasons")}} object.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/name/index.md b/files/en-us/web/api/notrestoredreasons/name/index.md
new file mode 100644
index 000000000000000..65bb2f0fbfc8eae
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/name/index.md
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: name property"
+short-title: name
+slug: Web/API/NotRestoredReasons/name
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.name
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`name`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the `name` attribute value of the {{htmlelement("iframe")}} the document is contained in (for example `<iframe name="bar" src="...">`).
+
+## Value
+
+A string.
+
+If the document is not in an `<iframe>` or the `<iframe>` has no `name` set, `name` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/reasons/index.md b/files/en-us/web/api/notrestoredreasons/reasons/index.md
new file mode 100644
index 000000000000000..14fe293063d4613
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/reasons/index.md
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: reasons property"
+short-title: reasons
+slug: Web/API/NotRestoredReasons/reasons
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.reasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`reasons`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns an array of {{domxref("NotRestoredReasonDetails")}} objects, each representing a reason why the navigated page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+## Value
+
+An array of {{domxref("NotRestoredReasonDetails")}} objects. See [Blocking reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons#blocking_reasons) for a list of the possible blocking reasons.
+
+If the document is in a cross-origin {{htmlelement("iframe")}}, `reasons` will return `null`, but the parent document may show a `reason` of `"masked"` if any `<iframe>`s blocked bfcache usage for the top-level frame.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/src/index.md b/files/en-us/web/api/notrestoredreasons/src/index.md
new file mode 100644
index 000000000000000..b0d1a015019c436
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/src/index.md
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: src property"
+short-title: src
+slug: Web/API/NotRestoredReasons/src
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.src
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`src`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the path to the source of the {{htmlelement("iframe")}} the document is contained in (for example `<iframe src="b.html">`).
+
+## Value
+
+A string.
+
+If the document is not in an `<iframe>`, `src` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/tojson/index.md b/files/en-us/web/api/notrestoredreasons/tojson/index.md
new file mode 100644
index 000000000000000..af1cc8826d6c4d5
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/tojson/index.md
@@ -0,0 +1,52 @@
+---
+title: "NotRestoredReasons: toJSON() method"
+short-title: toJSON()
+slug: Web/API/NotRestoredReasons/toJSON
+page-type: web-api-instance-method
+browser-compat: api.NotRestoredReasons.toJSON
+spec-urls: https://html.spec.whatwg.org/multipage/nav-history-apis.html#notrestoredreasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`toJSON()`** method of the {{domxref("NotRestoredReasons")}} interface is a {{Glossary("Serialization","serializer")}}; it returns a JSON representation of the {{domxref("NotRestoredReasons")}} object.
+
+## Syntax
+
+```js-nolint
+toJSON()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref("JSON")}} object that is the serialization of the {{domxref("NotRestoredReasons")}} object.
+
+## Examples
+
+The following function will return a JSON representation of the `NotRestoredReasons` object of the first `PerformanceNavigationTiming` object currently present in the performance timeline:
+
+```js
+function returnNRR() {
+  const navEntries = performance.getEntriesByType("navigation");
+  let navEntry = navEntries[0];
+  return navEntry.notRestoredReasons.toJSON();
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("JSON")}}
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/notrestoredreasons/url/index.md b/files/en-us/web/api/notrestoredreasons/url/index.md
new file mode 100644
index 000000000000000..5cb224d43c3366c
--- /dev/null
+++ b/files/en-us/web/api/notrestoredreasons/url/index.md
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: url property"
+short-title: url
+slug: Web/API/NotRestoredReasons/url
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.NotRestoredReasons.url
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`url`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the URL of the navigated page or {{htmlelement("iframe")}}.
+
+## Value
+
+A string.
+
+If the document is in a cross-origin `<iframe>`, `url` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
diff --git a/files/en-us/web/api/performance_api/index.md b/files/en-us/web/api/performance_api/index.md
index ed22dd964d0a9ba..9e844136105e608 100644
--- a/files/en-us/web/api/performance_api/index.md
+++ b/files/en-us/web/api/performance_api/index.md
@@ -90,6 +90,7 @@ The following guides help you to understand key concepts of the Performance API
 - [Navigation timing](/en-US/docs/Web/API/Performance_API/Navigation_timing): Measuring navigation timing of a document.
 - [User timing](/en-US/docs/Web/API/Performance_API/User_timing): Measuring and recording performance data custom to your application.
 - [Server timing](/en-US/docs/Web/API/Performance_API/Server_timing): Collecting server-side metrics.
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons): Reporting on why the current document was blocked from using the [back/forward cache](https://web.dev/bfcache/) (bfcache).
 
 ## Specifications
 
diff --git a/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md b/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md
new file mode 100644
index 000000000000000..2efb0b07d22e7a3
--- /dev/null
+++ b/files/en-us/web/api/performance_api/reporting_backforward_cache_not_restored_reasons/index.md
@@ -0,0 +1,177 @@
+---
+title: Reporting back/forward cache not restored reasons
+slug: Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons
+page-type: web-api-overview
+status:
+  - experimental
+browser-compat: api.PerformanceNavigationTiming.notRestoredReasons
+---
+
+{{DefaultAPISidebar("Performance API")}}{{SeeCompatTable}}
+
+The {{domxref("PerformanceNavigationTiming.notRestoredReasons")}} property reports information on why the current document was blocked from using the [back/forward cache (bfcache)](https://web.dev/bfcache/) on navigation. Developers can use this information to identify pages that need updates to make them bfcache-compatible, thereby improving site performance.
+
+## Concepts and usage
+
+Modern browsers provide an optimization feature for history navigation called the [back/forward cache (bfcache)](https://web.dev/bfcache/). This enables an instant loading experience when users go back to a page they have already visited. Pages can be blocked from entering the bfcache or get evicted while in the bfcache for different reasons, some required by a specification and some specific to browser implementations.
+
+To enable monitoring bfcache blocking in the field the [`PerformanceNavigationTiming`](/en-US/docs/Web/API/PerformanceNavigationTiming) class includes a `notRestoredReasons` property. This returns an object containing related information on the top-level frame and all {{htmlelement("iframe")}}s present in the document:
+
+- Reasons why bfcache usage was blocked.
+- Details such as frame `id` and `name`, to help identify `<iframe>`s in the HTML.
+
+> **Note:** There is also a [test in Chrome dev tools](https://web.dev/bfcache/#test) that reports on whether your pages are cacheable.
+
+## Examples
+
+A [`PerformanceNavigationTiming`](/en-US/docs/Web/API/PerformanceNavigationTiming) instance can be obtained from features such as [`Performance.getEntriesByType()`](/en-US/docs/Web/API/Performance/getEntriesByType) and [`PerformanceObserver`](/en-US/docs/Web/API/PerformanceObserver).
+
+For example, you could invoke the following function to return all `PerformanceNavigationTiming` objects currently present in the performance timeline and log their `notRestoredReasons`:
+
+```js
+function returnNRR() {
+  const navEntries = performance.getEntriesByType("navigation");
+  for (let i = 0; i < navEntries.length; i++) {
+    console.log(`Navigation entry ${i}`);
+    let navEntry = navEntries[i];
+    console.log(navEntry.notRestoredReasons);
+  }
+}
+```
+
+For history navigations, the {{domxref("PerformanceNavigationTiming.notRestoredReasons")}} property returns a {{domxref("NotRestoredReasons")}} object with the following structure, which represents the blocked state of the top-level frame:
+
+```js
+{
+  children: [],
+  id: null,
+  name: null,
+  reasons: [
+    { reason: "unload-listener" }
+  ],
+  src: "",
+  url: "example.com",
+}
+```
+
+The properties are as follows:
+
+- {{domxref("NotRestoredReasons.children", "children")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : An array of {{domxref("NotRestoredReasons")}} objects, one for each child {{htmlelement("iframe")}} embedded in the current document, which may contain reasons why the top-level frame was blocked relating to the child frames. Each object has the same structure as the parent object — this way, any number of levels of embedded `<iframe>`s can be represented inside the object recursively. If the frame has no children, the array will be empty; if the document is in a cross-origin `<iframe>`, `children` will return `null`.
+- {{domxref("NotRestoredReasons.id", "id")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the `id` attribute value of the `<iframe>` the document is contained in (for example `<iframe id="foo" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `id` set, `id` will return `null`.
+- {{domxref("NotRestoredReasons.name", "name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the `name` attribute value of the `<iframe>` the document is contained in (for example `<iframe name="bar" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `name` set, `name` will return `null`.
+- {{domxref("NotRestoredReasons.reasons", "reasons")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : An array of {{domxref("NotRestoredReasonDetails")}} objects, each representing a reason why the navigated page was blocked from using the bfcache. If the document is in a cross-origin `<iframe>`, `reasons` will return `null`, but the parent document may show a `reason` of `"masked"` if any `<iframe>`s blocked bfcache usage for the top-level frame. See [Blocking reasons](#blocking_reasons) for more details on the reasons.
+- {{domxref("NotRestoredReasons.src", "src")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the path to the source of the `<iframe>` the document is contained in (for example `<iframe src="exampleframe.html">`). If the document is not in an `<iframe>`, `src` will return `null`.
+- {{domxref("NotRestoredReasons.url", "url")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : A string representing the URL of the navigated page or `<iframe>`. If the document is in a cross-origin `<iframe>`, `url` will return `null`.
+
+### Reporting bfcache blocking in same-origin `<iframe>`s
+
+When a page has same-origin `<iframe>`s embedded, the returned `notRestoredReasons` value will contain an array of objects inside the `children` property representing the blocking reasons related to each embedded frame.
+
+For example:
+
+```js
+{
+  children: [
+    {
+      children: [],
+      id: "iframe-id",
+      name: "iframe-name",
+      reasons: [],
+      src: "./index.html",
+      url: "https://www.example.com/iframe-examples.html"
+    },
+    {
+      children: [],
+      id: "iframe-id2",
+      name: "iframe-name2",
+      reasons: [
+        { "reason": "unload-listener" }
+      ],
+      src: "./unload-examples.html",
+      url: "https://www.example.com/unload-examples.html"
+    },
+  ],
+  id: null,
+  name: null,
+  reasons: [],
+  src: null,
+  url:"https://www.example.com"
+}
+```
+
+### Reporting bfcache blocking in cross-origin `<iframe>`s
+
+When a page has cross-origin frames embedded, we limit the amount of information shared about them to avoid leaking cross-origin information. We only include information that the outer page already knows, and whether the cross-origin subtree caused bfcache blocking or not. We don't include any blocking reasons or information about lower levels of the subtree (even if some sub-levels are same-origin).
+
+For example:
+
+```js
+{
+  children: [
+    {
+      children: [],
+      id: "iframe-id",
+      name: "iframe-name",
+      reasons: [],
+      src: "https://www.example2.com/",
+      url: null
+    }
+  ],
+  id: null,
+  name: null,
+  reasons: [
+        { "reason": "masked" }
+  ],
+  src: null,
+  url:"https://www.example.com"
+}
+
+```
+
+For all the cross-origin `<iframe>`s, no blocking reasons are reported; for the top-level frame a reason of `"masked"` is reported, to indicate that the reasons are being kept hidden for privacy purposes. Note that `"masked"` may also be used for hiding user agent-specific reasons; it doesn't always indicate an issue in an `<iframe>`.
+
+## Blocking reasons
+
+There are many different reasons why blocking could occur, and browsers can choose to implement their own specific reasons for blocking, based on how they operate. Developers should avoid depending on specific wording for reasons and be prepared to handle new reasons being added and deleted.
+
+The initial values listed in the specification are:
+
+- `"fetch"`
+  - : While unloading, a fetch initiated by the current document (e.g. via {{domxref("fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache.
+- `"lock"`
+  - : While unloading, held locks and lock requests were terminated, so the page was not in a stable state that could be stored in the bfcache.
+- `"masked"`
+  - : The exact reason is hidden for privacy purposes. This value can mean one of the following:
+    - The current document has children contained in a cross-origin {{htmlelement("iframe")}}, and they prevented storage in the bfcache.
+    - The current Document could not be stored in the bfcache for user agent-specific reasons.
+- `"navigation-failure"`
+  - : The original navigation that created the current document errored, and storing the resulting error document in the bfcache was prevented.
+- `"parser-aborted"`
+  - : The current document never finished its initial HTML parsing, and storing the unfinished document in the bfcache was prevented.
+- `"websocket"`
+  - : While unloading, an open [WebSocket](/en-US/docs/Web/API/WebSockets_API) connect was shut down, so the page was not in a stable state that could be stored in the bfcache.
+
+Additional blocking reasons may be used by some browsers, for example:
+
+- `"unload-listener"`
+  - : The page registers an [`unload`](/en-US/docs/Web/API/Window/unload_event) handler, which prevents bfcache usage. This serves as a useful warning, as `unload` is deprecated. See [Deprecating the unload event](https://developer.chrome.com/docs/web-platform/deprecating-unload) for more information.
+- `"response-cache-control-no-store"`
+  - : The page uses `no-store` as a {{httpheader("Cache-Control")}} header value.
+- `"related-active-contents"`
+  - : The page was opened from another page that still has a reference to this page, for example using "duplicate tab" functionality.
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`notRestoredReasons` API Explainer](https://github.com/WICG/bfcache-not-restored-reason/blob/main/NotRestoredReason.md)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
+- {{domxref("NotRestoredReasons")}}
diff --git a/files/en-us/web/api/performancenavigationtiming/index.md b/files/en-us/web/api/performancenavigationtiming/index.md
index 3264f906bd80a55..5268a7f057a7783 100644
--- a/files/en-us/web/api/performancenavigationtiming/index.md
+++ b/files/en-us/web/api/performancenavigationtiming/index.md
@@ -53,6 +53,8 @@ The interface also supports the following properties:
   - : A {{domxref("DOMHighResTimeStamp")}} representing the time immediately after the current document's [`load`](/en-US/docs/Web/API/Window/load_event) event handler completes.
 - {{domxref('PerformanceNavigationTiming.loadEventStart')}} {{ReadOnlyInline}}
   - : A {{domxref("DOMHighResTimeStamp")}} representing the time immediately before the current document's [`load`](/en-US/docs/Web/API/Window/load_event) event handler starts.
+- {{domxref('PerformanceNavigationTiming.notRestoredReasons')}} {{ReadOnlyInline}}
+  - : A {{domxref("NotRestoredReasons")}} object providing report data on reasons why the current document was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache) on navigation.
 - {{domxref('PerformanceNavigationTiming.redirectCount')}} {{ReadOnlyInline}}
   - : A number representing the number of redirects since the last non-redirect navigation in the current browsing context.
 - {{domxref('PerformanceNavigationTiming.type')}} {{ReadOnlyInline}}
diff --git a/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md b/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md
new file mode 100644
index 000000000000000..a962ca212e9f153
--- /dev/null
+++ b/files/en-us/web/api/performancenavigationtiming/notrestoredreasons/index.md
@@ -0,0 +1,66 @@
+---
+title: "PerformanceNavigationTiming: notRestoredReasons property"
+short-title: notRestoredReasons
+slug: Web/API/PerformanceNavigationTiming/notRestoredReasons
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceNavigationTiming.notRestoredReasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`notRestoredReasons`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("NotRestoredReasons")}} object providing report data on reasons why the current document was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache) on navigation.
+
+## Value
+
+When the associated `PerformanceNavigationTiming` object represents a history navigation, `notRestoredReasons` returns a {{domxref("NotRestoredReasons")}} object.
+
+When the `PerformanceNavigationTiming` object does not represent a history navigation, `notRestoredReasons` will return `null`. This is useful for determining whether bfcache is not relevant to a particular navigation (as opposed to `notRestoredReasons` not being supported, in which case it would return `undefined`).
+
+> **Note:** `notRestoredReasons` may return `null` despite the navigation type being reported as a back/forward navigation. These circumstances include duplicating a back/forward navigation in a new tab and restoring a back/forward navigation tab after a browser restart. In such cases, some browsers copy the navigation type from the original tab, but as these are not actually back/forward navigations, `notRestoredReasons` returns `null`.
+
+## Examples
+
+A [`PerformanceNavigationTiming`](/en-US/docs/Web/API/PerformanceNavigationTiming) instance can be obtained from features such as [`Performance.getEntriesByType()`](/en-US/docs/Web/API/Performance/getEntriesByType) and [`PerformanceObserver`](/en-US/docs/Web/API/PerformanceObserver).
+
+For example, you could invoke the following function to return all `PerformanceNavigationTiming` objects currently present in the performance timeline and log their `notRestoredReasons`:
+
+```js
+function returnNRR() {
+  const navEntries = performance.getEntriesByType("navigation");
+  for (let i = 0; i < navEntries.length; i++) {
+    console.log(`Navigation entry ${i}`);
+    let navEntry = navEntries[i];
+    console.log(navEntry.notRestoredReasons);
+  }
+}
+```
+
+The `PerformanceNavigationTiming.notRestoredReasons` property returns an object with the following structure, which provides reasons why the current document was blocked from using the bfcache. In this example the top-level frame has no embedded child `<iframe>`s:
+
+```js
+{
+  children: [],
+  id: null,
+  name: null,
+  reasons: [
+    { reason: "unload-listener" }
+  ],
+  src: "",
+  url: "example.com",
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceResourceTiming")}}
diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json
index c6f3863c240d2a5..1c7f187973b5c98 100644
--- a/files/jsondata/GroupData.json
+++ b/files/jsondata/GroupData.json
@@ -1076,13 +1076,16 @@
         "/docs/Web/API/Performance_API/Resource_timing",
         "/docs/Web/API/Performance_API/Navigation_timing",
         "/docs/Web/API/Performance_API/User_timing",
-        "/docs/Web/API/Performance_API/Server_timing"
+        "/docs/Web/API/Performance_API/Server_timing",
+        "/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons"
       ],
       "interfaces": [
         "EventCounts",
         "LargestContentfulPaint",
         "LayoutShift",
         "LayoutShiftAttribution",
+        "NotRestoredReasons",
+        "NotRestoredReasonDetails",
         "Performance",
         "PerformanceEntry",
         "PerformanceElementTiming",