diff --git a/doc/api/url.md b/doc/api/url.md
index 38cb95d6097ae9..a423061f7b2945 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -971,6 +971,20 @@ changes:
 The `url.format()` method returns a formatted URL string derived from
 `urlObject`.
 
+```js
+url.format({
+  protocol: 'https',
+  hostname: 'example.com',
+  pathname: '/some/path',
+  query: {
+    page: 1,
+    format: 'json'
+  }
+});
+
+// => 'https://example.com/some/path?page=1&format=json'
+```
+
 If `urlObject` is not an object or a string, `url.format()` will throw a
 [`TypeError`][].