diff --git a/docs/api.md b/docs/api.md
index 75ac02504a0..943bb12ea84 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -2035,6 +2035,19 @@ Dispatches a `keyup` event.
 
 The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
 
+Every `page` object has it's own Mouse, accessible with [`page.mouse`](#pagemouse).
+
+```js
+// Using ‘page.mouse’ to trace a 100x100 square.
+await page.mouse.move(0, 0);
+await page.mouse.down();
+await page.mouse.move(0, 100);
+await page.mouse.move(100, 100);
+await page.mouse.move(100, 0);
+await page.mouse.move(0, 0);
+await page.mouse.up();
+```
+
 #### mouse.click(x, y, [options])
 - `x` <[number]>
 - `y` <[number]>