1 files changed, 49 insertions, 0 deletions
diff --git a/doc/api/v8.markdown b/doc/api/v8.markdown
index 70abd6c647..c6d760b0d5 100644
--- a/doc/api/v8.markdown
+++ b/doc/api/v8.markdown
@@ -21,6 +21,55 @@ Returns an object with the following properties
 }
 ```
 
+## getHeapSpaceStatistics()
+
+Returns statistics about the V8 heap spaces, i.e. the segments which make up
+the V8 heap. Order of heap spaces nor availability of a heap space can be
+guaranteed as the statistics are provided via the V8 `GetHeapSpaceStatistics`
+function.
+
+Example result:
+
+```
+[
+  {
+    "space_name": "new_space",
+    "space_size": 2063872,
+    "space_used_size": 951112,
+    "space_available_size": 80824,
+    "physical_space_size": 2063872
+  },
+  {
+    "space_name": "old_space",
+    "space_size": 3090560,
+    "space_used_size": 2493792,
+    "space_available_size": 0,
+    "physical_space_size": 3090560
+  },
+  {
+    "space_name": "code_space",
+    "space_size": 1260160,
+    "space_used_size": 644256,
+    "space_available_size": 960,
+    "physical_space_size": 1260160
+  },
+  {
+    "space_name": "map_space",
+    "space_size": 1094160,
+    "space_used_size": 201608,
+    "space_available_size": 0,
+    "physical_space_size": 1094160
+  },
+  {
+    "space_name": "large_object_space",
+    "space_size": 0,
+    "space_used_size": 0,
+    "space_available_size": 1490980608,
+    "physical_space_size": 0
+  }
+]
+```
+
 ## setFlagsFromString(string)
 
 Set additional V8 command line flags.  Use with care; changing settings