docs(api): Document query refresh param properly

frontend/src/queries/schema.json

@@ -7451,8 +7451,6 @@
             "properties": {
                 "async": {
                     "deprecated": "Use `refresh` instead.",
-                    "description": "(Experimental) Whether to run the query asynchronously. Defaults to False. If True, the `id` of the query can be used to check the status and to cancel it.",
-                    "examples": [true],
                     "type": "boolean"
                 },
                 "client_query_id": {
@@ -7467,7 +7465,9 @@
                     "description": "Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query.\n\nExample payload:\n\n```\n\n{\"query\": {\"kind\": \"HogQLQuery\", \"query\": \"select * from events limit 100\"}}\n\n```\n\nFor more details on HogQL queries, see the [PostHog HogQL documentation](/docs/hogql#api-access)."
                 },
                 "refresh": {
-                    "$ref": "#/definitions/RefreshType"
+                    "$ref": "#/definitions/RefreshType",
+                    "default": "blocking",
+                    "description": "Whether to refresh the insight, how aggresively, and if sync or async:\n- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh results are already cached\n- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the `query_status` response field."
                 }
             },
             "required": ["query"],

frontend/src/queries/schema.ts

@@ -1169,15 +1169,21 @@ export type RefreshType =
 export interface QueryRequest {
     /** Client provided query ID. Can be used to retrieve the status or cancel the query. */
     client_query_id?: string
+    // Sync the `refresh` description here with the one in posthog/api/insight.py
     /**
-     * (Experimental)
-     * Whether to run the query asynchronously. Defaults to False.
-     * If True, the `id` of the query can be used to check the status and to cancel it.
-     * @example true
-     * @deprecated Use `refresh` instead.
+     * Whether to refresh the insight, how aggresively, and if sync or async:
+     * - `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
+     * - `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
+     * - `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache
+     * - `'force_blocking'` - calculate synchronously, even if fresh results are already cached
+     * - `'force_async'` - kick off background calculation, even if fresh results are already cached
+     * - `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates
+     * Background calculation can be tracked using the `query_status` response field.
+     * @default 'blocking'
      */
-    async?: boolean
     refresh?: RefreshType
+    /** @deprecated Use `refresh` instead. */
+    async?: boolean
     /**
      * Submit a JSON string representing a query for PostHog data analysis,
      * for example a HogQL query.

posthog/api/insight.py

@@ -809,9 +809,15 @@ def _filter_request(self, request: request.Request, queryset: QuerySet) -> Query
                 name="refresh",
                 enum=list(ExecutionMode),
                 default=ExecutionMode.CACHE_ONLY_NEVER_CALCULATE,
+                # Sync the `refresh` description here with the one in frontend/src/queries/schema.ts
                 description="""
-Whether to refresh the insight and how aggressively. (The default `force_cache` value never refreshes.)
-If an `_async` mode is chosen, this request kicks off a background query and returns immediately.
+Whether to refresh the insight, how aggresively, and if sync or async:
+- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
+- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
+- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache
+- `'force_blocking'` - calculate synchronously, even if fresh results are already cached
+- `'force_async'` - kick off background calculation, even if fresh results are already cached
+- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates
 Background calculation can be tracked using the `query_status` response field.""",
             ),
             OpenApiParameter(

posthog/schema.py

@@ -5963,15 +5963,7 @@ class QueryRequest(BaseModel):
     model_config = ConfigDict(
         extra="forbid",
     )
-    async_: Optional[bool] = Field(
-        default=None,
-        alias="async",
-        description=(
-            "(Experimental) Whether to run the query asynchronously. Defaults to False. If True, the `id` of the query"
-            " can be used to check the status and to cancel it."
-        ),
-        examples=[True],
-    )
+    async_: Optional[bool] = Field(default=None, alias="async")
     client_query_id: Optional[str] = Field(
         default=None, description="Client provided query ID. Can be used to retrieve the status or cancel the query."
     )
@@ -6021,7 +6013,20 @@ class QueryRequest(BaseModel):
         ),
         discriminator="kind",
     )
-    refresh: Optional[Union[bool, str]] = None
+    refresh: Optional[Union[bool, str]] = Field(
+        default="blocking",
+        description=(
+            "Whether to refresh the insight, how aggresively, and if sync or async:\n- `'blocking'` - calculate"
+            " synchronously (returning only when the query is done), UNLESS there are very fresh results in the"
+            " cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS"
+            " there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS"
+            " there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if"
+            " fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh"
+            " results are already cached\n- `'force_cache'` - return cached data or a cache miss; always completes"
+            " immediately as it never calculates Background calculation can be tracked using the `query_status`"
+            " response field."
+        ),
+    )
 
 
 class QuerySchemaRoot(