This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new cc7c94348d2 adding link to api docs (#53346)
cc7c94348d2 is described below
commit cc7c94348d2ba1eaabb1654333075343fc300bf1
Author: Bowrna <[email protected]>
AuthorDate: Sat Sep 13 04:22:26 2025 +0530
adding link to api docs (#53346)
---
airflow-core/docs/core-concepts/dag-run.rst | 22 ++++++++++++++++++++++
.../core_api/openapi/v2-rest-api-generated.yaml | 3 ++-
.../api_fastapi/core_api/routes/public/dag_run.py | 2 +-
.../ui/openapi-gen/queries/ensureQueryData.ts | 4 ++--
.../src/airflow/ui/openapi-gen/queries/prefetch.ts | 4 ++--
.../src/airflow/ui/openapi-gen/queries/queries.ts | 4 ++--
.../src/airflow/ui/openapi-gen/queries/suspense.ts | 4 ++--
.../ui/openapi-gen/requests/services.gen.ts | 4 ++--
clients/python/README.md | 1 +
9 files changed, 36 insertions(+), 12 deletions(-)
diff --git a/airflow-core/docs/core-concepts/dag-run.rst
b/airflow-core/docs/core-concepts/dag-run.rst
index f524515e3b1..e1e54d8aa7b 100644
--- a/airflow-core/docs/core-concepts/dag-run.rst
+++ b/airflow-core/docs/core-concepts/dag-run.rst
@@ -278,6 +278,28 @@ Example of a parameterized Dag:
**Note**: The parameters from ``dag_run.conf`` can only be used in a template
field of an operator.
+Wait for a Dag Run
+------------------
+
+Airflow provides an experimental API to **wait for a Dag run to complete**.
This is particularly useful when integrating Airflow into external systems or
automation pipelines that need to pause execution until a Dag finishes.
+
+The endpoint blocks (by polling) until the specified Dag run reaches a
terminal state: ``success``, ``failed``, or ``canceled``.
+
+This endpoint streams responses using the **NDJSON (Newline-Delimited JSON)**
format. Each line in the response is a JSON object representing the state of
the Dag run at that moment.
+
+For example:
+
+.. code-block:: none
+
+ {"state": "running"}
+ {"state": "success", "results": {"op": 42}}
+
+This allows clients to monitor the run in real time and optionally collect
XCom results from specific tasks.
+
+.. note::
+
+ This feature is **experimental** and may change or be removed in future
Airflow versions.
+
Using CLI
^^^^^^^^^^^
diff --git
a/airflow-core/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
b/airflow-core/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
index b1b5faf6493..9150f12c012 100644
---
a/airflow-core/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
+++
b/airflow-core/src/airflow/api_fastapi/core_api/openapi/v2-rest-api-generated.yaml
@@ -2336,7 +2336,8 @@ paths:
summary: 'Experimental: Wait for a dag run to complete, and return task
results
if requested.'
description: "\U0001F6A7 This is an experimental endpoint and may change
or\
- \ be removed without notice."
+ \ be removed without notice.Successful response are streamed as
newline-delimited\
+ \ JSON (NDJSON). Each line is a JSON object representing the DAG run
state."
operationId: wait_dag_run_until_finished
security:
- OAuth2PasswordBearer: []
diff --git
a/airflow-core/src/airflow/api_fastapi/core_api/routes/public/dag_run.py
b/airflow-core/src/airflow/api_fastapi/core_api/routes/public/dag_run.py
index 8056c6fbda4..a1b686fa605 100644
--- a/airflow-core/src/airflow/api_fastapi/core_api/routes/public/dag_run.py
+++ b/airflow-core/src/airflow/api_fastapi/core_api/routes/public/dag_run.py
@@ -459,7 +459,7 @@ def trigger_dag_run(
"/{dag_run_id}/wait",
tags=["experimental"],
summary="Experimental: Wait for a dag run to complete, and return task
results if requested.",
- description="🚧 This is an experimental endpoint and may change or be
removed without notice.",
+ description="🚧 This is an experimental endpoint and may change or be
removed without notice.Successful response are streamed as newline-delimited
JSON (NDJSON). Each line is a JSON object representing the DAG run state.",
responses={
**create_openapi_http_exception_doc([status.HTTP_404_NOT_FOUND]),
status.HTTP_200_OK: {
diff --git a/airflow-core/src/airflow/ui/openapi-gen/queries/ensureQueryData.ts
b/airflow-core/src/airflow/ui/openapi-gen/queries/ensureQueryData.ts
index 923eae15e15..da76a35a8ce 100644
--- a/airflow-core/src/airflow/ui/openapi-gen/queries/ensureQueryData.ts
+++ b/airflow-core/src/airflow/ui/openapi-gen/queries/ensureQueryData.ts
@@ -325,7 +325,7 @@ export const ensureUseDagRunServiceGetDagRunsData =
(queryClient: QueryClient, {
}) => queryClient.ensureQueryData({ queryKey:
Common.UseDagRunServiceGetDagRunsKeyFn({ dagId, dagVersion, endDateGt,
endDateGte, endDateLt, endDateLte, limit, logicalDateGt, logicalDateGte,
logicalDateLt, logicalDateLte, offset, orderBy, runAfterGt, runAfterGte,
runAfterLt, runAfterLte, runIdPattern, runType, startDateGt, startDateGte,
startDateLt, startDateLte, state, triggeringUserNamePattern, updatedAtGt,
updatedAtGte, updatedAtLt, updatedAtLte }), queryFn: () =>
DagRunService.getDagR [...]
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
@@ -342,7 +342,7 @@ export const
ensureUseDagRunServiceWaitDagRunUntilFinishedData = (queryClient: Q
}) => queryClient.ensureQueryData({ queryKey:
Common.UseDagRunServiceWaitDagRunUntilFinishedKeyFn({ dagId, dagRunId,
interval, result }), queryFn: () => DagRunService.waitDagRunUntilFinished({
dagId, dagRunId, interval, result }) });
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
diff --git a/airflow-core/src/airflow/ui/openapi-gen/queries/prefetch.ts
b/airflow-core/src/airflow/ui/openapi-gen/queries/prefetch.ts
index 96408ad07c8..af773c94bdd 100644
--- a/airflow-core/src/airflow/ui/openapi-gen/queries/prefetch.ts
+++ b/airflow-core/src/airflow/ui/openapi-gen/queries/prefetch.ts
@@ -325,7 +325,7 @@ export const prefetchUseDagRunServiceGetDagRuns =
(queryClient: QueryClient, { d
}) => queryClient.prefetchQuery({ queryKey:
Common.UseDagRunServiceGetDagRunsKeyFn({ dagId, dagVersion, endDateGt,
endDateGte, endDateLt, endDateLte, limit, logicalDateGt, logicalDateGte,
logicalDateLt, logicalDateLte, offset, orderBy, runAfterGt, runAfterGte,
runAfterLt, runAfterLte, runIdPattern, runType, startDateGt, startDateGte,
startDateLt, startDateLte, state, triggeringUserNamePattern, updatedAtGt,
updatedAtGte, updatedAtLt, updatedAtLte }), queryFn: () =>
DagRunService.getDagRun [...]
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
@@ -342,7 +342,7 @@ export const
prefetchUseDagRunServiceWaitDagRunUntilFinished = (queryClient: Que
}) => queryClient.prefetchQuery({ queryKey:
Common.UseDagRunServiceWaitDagRunUntilFinishedKeyFn({ dagId, dagRunId,
interval, result }), queryFn: () => DagRunService.waitDagRunUntilFinished({
dagId, dagRunId, interval, result }) });
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
diff --git a/airflow-core/src/airflow/ui/openapi-gen/queries/queries.ts
b/airflow-core/src/airflow/ui/openapi-gen/queries/queries.ts
index 346b4ae43a4..6c70c69ac5c 100644
--- a/airflow-core/src/airflow/ui/openapi-gen/queries/queries.ts
+++ b/airflow-core/src/airflow/ui/openapi-gen/queries/queries.ts
@@ -325,7 +325,7 @@ export const useDagRunServiceGetDagRuns = <TData =
Common.DagRunServiceGetDagRun
}, queryKey?: TQueryKey, options?: Omit<UseQueryOptions<TData, TError>,
"queryKey" | "queryFn">) => useQuery<TData, TError>({ queryKey:
Common.UseDagRunServiceGetDagRunsKeyFn({ dagId, dagVersion, endDateGt,
endDateGte, endDateLt, endDateLte, limit, logicalDateGt, logicalDateGte,
logicalDateLt, logicalDateLte, offset, orderBy, runAfterGt, runAfterGte,
runAfterLt, runAfterLte, runIdPattern, runType, startDateGt, startDateGte,
startDateLt, startDateLte, state, triggeringUserNamePattern, upd [...]
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
@@ -342,7 +342,7 @@ export const useDagRunServiceWaitDagRunUntilFinished =
<TData = Common.DagRunSer
}, queryKey?: TQueryKey, options?: Omit<UseQueryOptions<TData, TError>,
"queryKey" | "queryFn">) => useQuery<TData, TError>({ queryKey:
Common.UseDagRunServiceWaitDagRunUntilFinishedKeyFn({ dagId, dagRunId,
interval, result }, queryKey), queryFn: () =>
DagRunService.waitDagRunUntilFinished({ dagId, dagRunId, interval, result }) as
TData, ...options });
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
diff --git a/airflow-core/src/airflow/ui/openapi-gen/queries/suspense.ts
b/airflow-core/src/airflow/ui/openapi-gen/queries/suspense.ts
index 5d3d0f2f19c..79a5f974e07 100644
--- a/airflow-core/src/airflow/ui/openapi-gen/queries/suspense.ts
+++ b/airflow-core/src/airflow/ui/openapi-gen/queries/suspense.ts
@@ -325,7 +325,7 @@ export const useDagRunServiceGetDagRunsSuspense = <TData =
Common.DagRunServiceG
}, queryKey?: TQueryKey, options?: Omit<UseQueryOptions<TData, TError>,
"queryKey" | "queryFn">) => useSuspenseQuery<TData, TError>({ queryKey:
Common.UseDagRunServiceGetDagRunsKeyFn({ dagId, dagVersion, endDateGt,
endDateGte, endDateLt, endDateLte, limit, logicalDateGt, logicalDateGte,
logicalDateLt, logicalDateLte, offset, orderBy, runAfterGt, runAfterGte,
runAfterLt, runAfterLte, runIdPattern, runType, startDateGt, startDateGte,
startDateLt, startDateLte, state, triggeringUserNamePatt [...]
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
@@ -342,7 +342,7 @@ export const
useDagRunServiceWaitDagRunUntilFinishedSuspense = <TData = Common.D
}, queryKey?: TQueryKey, options?: Omit<UseQueryOptions<TData, TError>,
"queryKey" | "queryFn">) => useSuspenseQuery<TData, TError>({ queryKey:
Common.UseDagRunServiceWaitDagRunUntilFinishedKeyFn({ dagId, dagRunId,
interval, result }, queryKey), queryFn: () =>
DagRunService.waitDagRunUntilFinished({ dagId, dagRunId, interval, result }) as
TData, ...options });
/**
* Experimental: Wait for a dag run to complete, and return task results if
requested.
-* 🚧 This is an experimental endpoint and may change or be removed without
notice.
+* 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
diff --git a/airflow-core/src/airflow/ui/openapi-gen/requests/services.gen.ts
b/airflow-core/src/airflow/ui/openapi-gen/requests/services.gen.ts
index 5f38c32a9d2..ed570c2fc9d 100644
--- a/airflow-core/src/airflow/ui/openapi-gen/requests/services.gen.ts
+++ b/airflow-core/src/airflow/ui/openapi-gen/requests/services.gen.ts
@@ -1080,7 +1080,7 @@ export class DagRunService {
/**
* Experimental: Wait for a dag run to complete, and return task results
if requested.
- * 🚧 This is an experimental endpoint and may change or be removed without
notice.
+ * 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
@@ -1142,7 +1142,7 @@ export class DagRunService {
export class ExperimentalService {
/**
* Experimental: Wait for a dag run to complete, and return task results
if requested.
- * 🚧 This is an experimental endpoint and may change or be removed without
notice.
+ * 🚧 This is an experimental endpoint and may change or be removed without
notice.Successful response are streamed as newline-delimited JSON (NDJSON).
Each line is a JSON object representing the DAG run state.
* @param data The data for the request.
* @param data.dagId
* @param data.dagRunId
diff --git a/clients/python/README.md b/clients/python/README.md
index f071d077354..e164f4b5ca8 100644
--- a/clients/python/README.md
+++ b/clients/python/README.md
@@ -394,6 +394,7 @@ Class | Method | HTTP request | Description
*DagRunApi* | [**get_dag_runs**](docs/DagRunApi.md#get_dag_runs) | **GET**
/api/v2/dags/{dag_id}/dagRuns | Get Dag Runs
*DagRunApi* |
[**get_list_dag_runs_batch**](docs/DagRunApi.md#get_list_dag_runs_batch) |
**POST** /api/v2/dags/{dag_id}/dagRuns/list | Get List Dag Runs Batch
*DagRunApi* |
[**get_upstream_asset_events**](docs/DagRunApi.md#get_upstream_asset_events) |
**GET** /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/upstreamAssetEvents | Get
Upstream Asset Events
+*DagRunApi* |
[**wait_dag_run_until_finished**](docs/DagRunApi.md#wait_dag_run_until_finished)
| **GET** /api/v2/dags/{dag_id}/dagRuns/{dag_run_id}/wait | Experimental: Wait
for a dag run to complete, and return task results if requested.
*DagRunApi* | [**patch_dag_run**](docs/DagRunApi.md#patch_dag_run) | **PATCH**
/api/v2/dags/{dag_id}/dagRuns/{dag_run_id} | Patch Dag Run
*DagRunApi* | [**trigger_dag_run**](docs/DagRunApi.md#trigger_dag_run) |
**POST** /api/v2/dags/{dag_id}/dagRuns | Trigger Dag Run
*DagSourceApi* | [**get_dag_source**](docs/DagSourceApi.md#get_dag_source) |
**GET** /api/v2/dagSources/{dag_id} | Get Dag Source
