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 928d5b4ba29 Docs: clarify BaseSensorOperator parameters in Sensors
guide (#60275)
928d5b4ba29 is described below
commit 928d5b4ba29dec84b636c300fc1b6915aceef243
Author: jaymasiwal <[email protected]>
AuthorDate: Wed Jan 21 05:40:15 2026 +0530
Docs: clarify BaseSensorOperator parameters in Sensors guide (#60275)
---
airflow-core/docs/core-concepts/sensors.rst | 64 +++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/airflow-core/docs/core-concepts/sensors.rst
b/airflow-core/docs/core-concepts/sensors.rst
index ea82f5e3b3d..b727f8ce35b 100644
--- a/airflow-core/docs/core-concepts/sensors.rst
+++ b/airflow-core/docs/core-concepts/sensors.rst
@@ -31,3 +31,67 @@ The ``poke`` and ``reschedule`` modes can be configured
directly when you instan
Much like Operators, Airflow has a large set of pre-built Sensors you can use,
both in core Airflow as well as via our *providers* system.
.. seealso:: :doc:`../authoring-and-scheduling/deferring`
+
+BaseSensorOperator parameters
+-----------------------------
+
+All sensors in Airflow ultimately inherit from ``BaseSensorOperator``
(directly or indirectly).
+This base class defines the common behavior and parameters that control
+how a sensor waits, retries, and manages worker resources.
+
+As of the Task SDK refactor, ``BaseSensorOperator`` is implemented in the
+Task SDK. Because provider documentation is generated separately, these
+parameters may not always be directly visible on individual provider
+sensor API pages. However, they apply to *all* sensors.
+
+Common parameters
+^^^^^^^^^^^^^^^^^
+
+The following parameters are provided by ``BaseSensorOperator`` and are
+available on all sensors:
+
+``poke_interval``
+ Time in seconds between successive checks. In ``poke`` mode, the sensor
+ sleeps between checks while occupying a worker slot. In ``reschedule``
+ mode, the task is deferred and rescheduled after this interval.
+
+``timeout``
+ Maximum time in seconds the sensor is allowed to run before failing.
+ This timeout is measured from the first execution attempt, not per poke.
+
+``mode``
+ Determines how the sensor occupies worker resources.
+
+ * ``poke`` (default): occupies a worker slot for the entire duration
+ * ``reschedule``: releases the worker slot between checks
+
+``soft_fail``
+ If set to ``True``, the sensor will be marked as ``SKIPPED`` instead of
+ ``FAILED`` when the timeout is reached.
+
+``exponential_backoff``
+ If enabled, the time between checks increases exponentially up to
+ ``max_wait``. This is useful when polling external systems with
+ unpredictable availability.
+
+``max_wait``
+ Upper bound (in seconds) for the delay between checks when
+ ``exponential_backoff`` is enabled.
+
+For the authoritative API reference, see the Task SDK documentation for
+``BaseSensorOperator``:
+
+https://airflow.apache.org/docs/task-sdk/stable/api.html#airflow.sdk.BaseSensorOperator
+
+Example
+^^^^^^^
+
+.. code-block:: python
+
+ BashSensor(
+ task_id="wait_for_file",
+ bash_command="test -f /data/input.csv",
+ poke_interval=60,
+ timeout=60 * 60,
+ mode="reschedule",
+ )
