diff --git a/components/online_image.rst b/components/online_image.rst
index a7ddf94dc6..c9dc5367a0 100644
--- a/components/online_image.rst
+++ b/components/online_image.rst
@@ -66,6 +66,28 @@ Automations
 
 - **on_download_finished** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the image has been successfully downloaded.
 
+The variable ``cached`` is a boolean available in :ref:`lambdas <config-lambda>` that indicates cache status:
+ - ``true`` if the image was loaded from cache (cache hit).
+ - ``false`` if the image was freshly downloaded (cache miss).
+
+Caching follows standard HTTP mechanisms (see `HTTP caching <https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching>`_), utilizing the ``Last-Modified`` and ``ETag`` headers.
+
+For example:
+
+.. code-block:: yaml
+
+    online_image:
+      - url: "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
+        format: png
+        id: my_online_image
+        on_download_finished:
+          lambda: |-
+            if (cached) {
+              ESP_LOGD("online_image", "Cache hit: using cached image");
+            } else {
+              ESP_LOGD("online_image", "Cache miss: fresh download");
+            }
+
 A good example for that is to update the display component after the download succeeded.
 
 - **on_error** (*Optional*, :ref:`Automation <automation>`): An automation to perform when an error happened during download or decode.