mcp

get_task_instance

Read-onlyIdempotent

Retrieves details of a specific task instance from a Managed Airflow environment.

Use this tool to retrieve details of a specific task instance, such as its state, start time, end time, or parameters, to understand its status or to debug a failure.

This tool does not return task instance logs directly. Instead, use the cloud_logging_filter field from the response to query Cloud Logging for the logs for this task instance.

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": {
      "environment": "<environment>",
      "dagId": "<dagId>",
      "dagRunId": "<dagRunId>",
      "taskId": "<taskId>"
    },
    "name": "get_task_instance"
  }
}

Input Schema

Name	Required	Description
`dagId`	Yes	Required. The Airflow DAG ID.
`taskId`	Yes	Required. The Airflow task ID.
`dagRunId`	Yes	Required. The Airflow DAG run ID.
`mapIndex`	No	Optional. For mapped tasks, the map index of the task. It should not be populated for non-mapped tasks.
`environment`	Yes	Required. The name of the environment. Format: `projects/{projectId}/locations/{locationId}/environments/{environmentId}`

Output Schema

Name	Required	Description
`id`	No	The task instance ID. It is the same as the task ID of a DAG.
`name`	No	Required. The resource name of the task instance, in the form: "projects/{project_id}/locations/{location_id}/environments/{environment_id}/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_instance_id_with_optional_map_index}".
`note`	No	The note content of the task instance. Added in Airflow 2.10.0.
`pool`	No	The slot pool this task runs in.
`dagId`	No	The DAG ID of the DAG whose execution is described by the DAG run the taskInstance belongs to.
`queue`	No	Which queue to target when running this task.
`state`	No	Task instance state.
`taskId`	No	The task instance ID. It is the same as the task ID in the DAG.
`endDate`	No	Timestamp when the task instance finished execution.
`dagRunId`	No	The DAG run ID the task instance belongs to.
`hostname`	No	Hostname of the machine or pod the task runs on.
`mapIndex`	No	If is_dynamically_mapped is set to true, this field contains index of the dynamically-mapped TaskInstance, If is_dynamically_mapped is set to false, this field has no meaning.
`maxTries`	No	The number of tries that should be performed before failing the task.
`runAfter`	No	Timestamp when the parent DAG run was scheduled to start. Added in Airflow 3.
`taskType`	No	The operator used in this task.
`startDate`	No	Timestamp when the task instance started execution.
`tryNumber`	No	The try number that this task number will be when it is actually run.
`queuedDttm`	No	Timestamp when the task was queued.
`executionDate`	No	Execution date for the task.
`priorityWeight`	No	Priority weight of this task against other tasks.
`renderedMapIndex`	No	Named mapping - a rendered map index template for this task instance. If task doesn't have a template specified or is_dynamically_mapped is set to false, this field is empty.
`cloudLoggingFilter`	No	Output only. A Cloud Logging filter that can be used to retrieve the logs of this task instance.
`externalExecutorId`	No	ID of the external executor.
`isDynamicallyMapped`	No	Whether this TaskInstance is dynamically mapped.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 6, 2026

changedOutput schema / properties / cloudLoggingFilter / description

Previous value: -"A Cloud Logging filter that can be used to retrieve the logs of this task instance."New value: +"Output only. A Cloud Logging filter that can be used to retrieve the logs of this task instance."

addedOutput schema / properties / cloudLoggingFilter / readOnly
```
Added value: +true
```

First observedApr 19, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavioral context: the response will not contain logs and instead carries a cloud_logging_filter field for a follow-up Cloud Logging query. It does not cover failure behavior for a nonexistent instance, which keeps it from a 5.

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?

The definition is front-loaded with purpose and then layers usage and a log-lookup caveat in separate short paragraphs, which is easy to scan. The second sentence restates 'retrieve details of a specific task instance' from the first, a minor redundancy, though it does add concrete examples of the returned fields.

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?

With a full input schema, complete parameter descriptions, an output schema, and strong annotations, the description's main remaining job is the log-redirect caveat, which it handles well. Only error or not-found behavior is unaddressed, a small gap for a simple read tool.

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

Parameters3/5

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

Schema description coverage is 100%, so all five parameters, including the optional mapIndex semantics for mapped tasks, are already documented in the schema. The description adds no parameter-level detail beyond listing example fields that can be retrieved, so the baseline of 3 applies.

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?

The description opens with a specific verb and resource ('Retrieves details of a specific task instance') and scopes it to a Managed Airflow environment, which separates it from the list_* and get_dag/get_dag_run siblings. It stops short of explicitly naming which sibling to use for adjacent needs (e.g., list_failed_task_instances), so it is clear but not fully differentiated.

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

Usage Guidelines4/5

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

It gives a concrete use case ('to understand its status or to debug a failure') and explicitly rules out an adjacent expectation by stating it does not return logs, redirecting to Cloud Logging via the cloud_logging_filter field. There is no explicit statement of when to prefer a sibling tool such as get_dag_run or list_failed_task_instances instead.

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

All mcp tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?