Implementation:Apache Airflow TaskInstance Model

Knowledge Sources	Apache Airflow
Domains	State_Management, ORM
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for tracking and managing individual task execution state provided by the TaskInstance model.

Description

The TaskInstance class is a SQLAlchemy model that serves as the authority and single source of truth for task execution state. It tracks task identity (dag_id, task_id, run_id, map_index), execution state, retry counts, pool allocation, executor assignment, and trigger associations for deferrable tasks.

Usage

TaskInstance is primarily managed by the scheduler and executor. Users interact with it through the UI, CLI (airflow tasks), or API for monitoring and manual state changes.

Code Reference

Source Location

• Repository: Apache Airflow
• File: airflow-core/src/airflow/models/taskinstance.py
• Lines: L363-2169

Signature

class TaskInstance(Base, LoggingMixin):
    __tablename__ = "task_instance"

    id: Mapped[str]              # UUID primary key
    task_id: Mapped[str]
    dag_id: Mapped[str]
    run_id: Mapped[str]
    map_index: Mapped[int]       # -1 for non-mapped tasks
    start_date: Mapped[datetime | None]
    end_date: Mapped[datetime | None]
    duration: Mapped[float | None]
    state: Mapped[str | None]    # none, scheduled, queued, running, success, failed, etc.
    try_number: Mapped[int]
    max_tries: Mapped[int]
    pool: Mapped[str]
    pool_slots: Mapped[int]
    queue: Mapped[str]
    priority_weight: Mapped[int]
    executor: Mapped[str | None]
    trigger_id: Mapped[int | None]
    trigger_timeout: Mapped[datetime | None]
    next_method: Mapped[str | None]
    next_kwargs: Mapped[dict | None]
    dag_version_id: Mapped[str | None]

Import

from airflow.models.taskinstance import TaskInstance

I/O Contract

Inputs

Name	Type	Required	Description
task_id	str	Yes	Task identifier within the DAG
dag_id	str	Yes	Parent DAG identifier
run_id	str	Yes	Parent DagRun identifier
map_index	int	No	Index for mapped tasks (default -1)
pool	str	Yes	Pool for concurrency management

Outputs

Name	Type	Description
state	str	Current execution state
XCom values	JSON	Task return values stored via XCom
Logs	Text	Task execution logs
Duration	float	Execution duration in seconds

Usage Examples

Query Task Instances

# List task instances for a DAG run
airflow tasks states-for-dag-run my_dag 2024-01-01

# Manually set task state
airflow tasks set-state my_dag my_task 2024-01-01 success

Related Pages

Implements Principle

• Principle:Apache_Airflow_Task_Instance_State

Requires Environment

• Environment:Apache_Airflow_Python_Runtime_Environment
• Environment:Apache_Airflow_Database_Backend_Environment

Uses Heuristic

• Heuristic:Apache_Airflow_Scheduler_Performance_Tuning