Skip to main content
Glama

list_task_instances

Read-only

List task instances for a DAG run using state, date, duration, and other Airflow filters, with cursor or offset pagination to inspect task executions.

Instructions

List task executions with all Airflow 3.3.1 API query filters.

Use '~' for all DAGs or runs. Date filters are timezone-aware ISO 8601 strings. Lists use repeated query parameters; order_by accepts '-' for descending order. cursor='' starts cursor pagination; pass returned next_cursor for the next page. When cursor is supplied, Airflow ignores offset. Patterns match substrings; prefix patterns are case-sensitive. No rendered fields or XCom values are returned. ID regexes use Python search with inline flags and combine with native filters using AND. Regex scans at most 1000 candidates before offset/limit pagination, forbids cursor, and returns a filtered total. With regex, limit=0 returns all matches.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "dag_id": "<dag_id>",
      "dag_run_id": "<dag_run_id>"
    },
    "name": "list_task_instances"
  }
}

Input Schema

NameRequiredDescriptionDefault
poolNo
limitNo
queueNo
stateNo
cursorNo
dag_idYes
offsetNo
task_idNo
executorNo
operatorNo
order_byNo
map_indexNo
dag_run_idYes
try_numberNo
duration_gtNo
duration_ltNo
end_date_gtNo
end_date_ltNo
dag_id_regexNo
duration_gteNo
duration_lteNo
end_date_gteNo
end_date_lteNo
run_after_gtNo
run_after_ltNo
run_after_gteNo
run_after_lteNo
start_date_gtNo
start_date_ltNo
task_group_idNo
task_id_regexNo
updated_at_gtNo
updated_at_ltNo
dag_id_patternNo
run_id_patternNo
start_date_gteNo
start_date_lteNo
updated_at_gteNo
updated_at_lteNo
version_numberNo
logical_date_gtNo
logical_date_ltNo
logical_date_gteNo
logical_date_lteNo
pool_name_patternNo
queue_name_patternNo
dag_id_prefix_patternNo
operator_name_patternNo
run_id_prefix_patternNo
pool_name_prefix_patternNo
queue_name_prefix_patternNo
task_display_name_patternNo
rendered_map_index_patternNo
operator_name_prefix_patternNo
task_display_name_prefix_patternNo
rendered_map_index_prefix_patternNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/openWorld/non-destructive, and the description adds substantial behavior beyond that: rendered fields and XCom values are excluded from results, regex scans cap at 1000 candidates, regex forbids cursor, regex yields a filtered total, and cursor-supplied requests have offset ignored. These are real constraints an agent could not derive from the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six short sentences, each front-loading a distinct convention with no filler; the wildcard, date-format, and pagination rules come early. It is dense and terse to the point that a couple of sentences (patterns vs prefix patterns, regex limits) require a second read, but nothing is waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 56-parameter tool with no output schema, the description covers the conventions that would otherwise cause misuse: pagination interplay, wildcard syntax, date formatting, and regex restrictions. It would be fuller if it sketched the returned task-instance shape or grouped the undocumented filter families, but the critical calling pitfalls are addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 56 parameters and 0% schema description coverage, the description carries the full burden and does document the cross-cutting conventions: '~' wildcard, timezone-aware ISO 8601 date strings, repeated query params for list values, '-' prefix for descending order_by, substring vs case-sensitive prefix matching, and Python-search regex semantics ANDed with native filters. Many individual filters (duration_gt, try_number, map_index, updated_at, version_number) remain unaddressed, but their names are largely self-describing, so the added meaning is strong though not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List task executions') and scopes it to the Airflow 3.3.1 query-filter API, so an agent knows this is the filtered enumeration endpoint. It is reasonably distinguishable from list_tasks/list_runs by the 'task executions' framing and the explicit dag_id+dag_run_id requirement, but it never names a sibling or contrast case, leaving the boundary implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Offers some operational guidance ('Use ~ for all DAGs or runs', cursor vs offset, limit=0 with regex), which implies usage contexts. However, there is no explicit statement of when to prefer this over list_tasks or inspect_run, and no prerequisites or exclusions for the many filter families; usage must be inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.