diff --git a/docs/inventory_refresh.md b/docs/inventory_refresh.md
index edcbe5d358..e5840c8bbe 100644
--- a/docs/inventory_refresh.md
+++ b/docs/inventory_refresh.md
@@ -11,8 +11,32 @@ from `InventorySource` completely in Tower 3.3. As a result the related field on
 `inventory_source` has been renamed `deprecated_inventory_source` and will also be removed in Tower 3.3.
 
 
-## Fact Searching and Caching
+## Fact Searching
+Facts generated by an Ansible playbook during a Job Template run are stored by Tower into the database
+whenever `store_facts=True` is set per-Job-Template. New facts are merged with existing
+facts and are per-host. These stored facts can be used to filter hosts via the
+`/api/v2/hosts` endpoint, using the GET query parameter `host_filter` i.e.
+`/api/v2/hosts?host_filter=ansible_facts__ansible_processor_vcpus=8`
 
+The grammer of `host_filter` allows for:
+* grouping via `()`
+* the boolean `and` operator
+* `__` to reference related fields in relational fields
+* `__` is used on `ansible_facts` to separate keys in a JSON key path
+* `[]` is used to denote a json array in the path specification
+* `""` can be used in the value when spaces are wanted in the value
+* "classic" Django queries may be embedded in the `host_filter`
+
+Examples:
+```
+/api/v2/hosts/?host_filter=name=localhost
+/api/v2/hosts/?host_filter=ansible_facts__ansible_date_time__weekday_number="3"
+/api/v2/hosts/?host_filter=ansible_facts__ansible_processor[]="GenuineIntel"
+/api/v2/hosts/?host_filter=ansible_facts__ansible_lo__ipv6[]__scope="host"
+/api/v2/hosts/?host_filter=ansible_facts__ansible_processor_vcpus=8
+/api/v2/hosts/?host_filter=ansible_facts__ansible_env__PYTHONUNBUFFERED="true"
+/api/v2/hosts/?host_filter=(name=localhost or name=database) and (groups__name=east or groups__name="west coast") and ansible_facts__ansible_processor_vcpus=8
+```
 
 ## Smart Inventory
 Starting in Tower 3.2, Tower will support the ability to define a _Smart Inventory_.