Sign in

v1

latestOpenAPI 3.0.0Apache 2.0 License2026-07-1456373564.1 KB

Returns a list of task definitions that are registered to your account. You can filter the results by family name with the <code>familyPrefix</code> parameter or by status with the <code>status</code> parameter.

post/#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTaskDefinitions

Query parameters

maxResultsstring

Pagination limit

nextTokenstring

Pagination token

Headers

X-Amz-Target'AmazonEC2ContainerServiceV20141113.ListTaskDefinitions' required

Request body

familyPrefixstring

The full family name to filter the <code>ListTaskDefinitions</code> results with. Specifying a <code>familyPrefix</code> limits the listed task definitions to task definition revisions that belong to that family.

status'ACTIVE' | 'INACTIVE' | 'DELETE_IN_PROGRESS'

The task definition status to filter the <code>ListTaskDefinitions</code> results with. By default, only <code>ACTIVE</code> task definitions are listed. By setting this parameter to <code>INACTIVE</code>, you can view task definitions that are <code>INACTIVE</code> as long as an active task or service still references them. If you paginate the resulting output, be sure to keep the <code>status</code> value constant in each subsequent request.

sort'ASC' | 'DESC'

The order to sort the results in. Valid values are <code>ASC</code> and <code>DESC</code>. By default, (<code>ASC</code>) task definitions are listed lexicographically by family name and in ascending numerical order by revision so that the newest task definitions in a family are listed last. Setting this parameter to <code>DESC</code> reverses the sort order on family name and revision. This is so that the newest task definitions in a family are listed first.

nextTokenstring
<p>The <code>nextToken</code> value returned from a <code>ListTaskDefinitions</code> request indicating that more results are available to fulfill the request and further calls will be needed. If <code>maxResults</code> was provided, it is possible the number of results to be fewer than <code>maxResults</code>.</p> <note> <p>This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.</p> </note>
maxResultsinteger

The maximum number of task definition results that <code>ListTaskDefinitions</code> returned in paginated output. When this parameter is used, <code>ListTaskDefinitions</code> only returns <code>maxResults</code> results in a single page along with a <code>nextToken</code> response element. The remaining results of the initial request can be seen by sending another <code>ListTaskDefinitions</code> request with the returned <code>nextToken</code> value. This value can be between 1 and 100. If this parameter isn't used, then <code>ListTaskDefinitions</code> returns up to 100 results and a <code>nextToken</code> value if applicable.

Response

Success

taskDefinitionArnsString[]

The list of task definition Amazon Resource Name (ARN) entries for the <code>ListTaskDefinitions</code> request.

nextTokenstring

The <code>nextToken</code> value to include in a future <code>ListTaskDefinitions</code> request. When the results of a <code>ListTaskDefinitions</code> request exceed <code>maxResults</code>, this value can be used to retrieve the next page of results. This value is <code>null</code> when there are no more results to return.

Example response

{
  "taskDefinitionArns": [
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:3",
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:4",
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:5",
    "arn:aws:ecs:us-east-1:<aws_account_id>:task-definition/wordpress:6"
  ]
}