ecs-task-metadata.openapi.yaml

openapi: 3.0.3
info:
  title: Amazon ECS Task Metadata Endpoint v4
  description: |
    The Amazon ECS Task Metadata Endpoint v4 provides metadata about tasks and containers running on Amazon ECS.
    This endpoint is available inside containers via the `ECS_CONTAINER_METADATA_URI_V4` environment variable.
  version: '4.0.0'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/ecs/
servers:
  - url: '{baseUrl}'
    description: Task Metadata Endpoint
    variables:
      baseUrl:
        default: '${ECS_CONTAINER_METADATA_URI_V4}'
        description: The base URL for the task metadata endpoint, provided via environment variable

paths:
  /:
    get:
      summary: Container Metadata
      description: Returns metadata for the container
      operationId: getContainerMetadata
      responses:
        '200':
          description: Container metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerMetadata'
  
  /task:
    get:
      summary: Task Metadata
      description: Returns metadata for the task, including a list of container IDs and names for all containers associated with the task
      operationId: getTaskMetadata
      responses:
        '200':
          description: Task metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskMetadata'
  
  /taskWithTags:
    get:
      summary: Task Metadata with Tags
      description: |
        Returns the metadata for the task included in the /task endpoint in addition to the task and container instance tags
        that can be retrieved using the ListTagsForResource API.
        
        Note: This endpoint requires the ecs.ListTagsForResource permission.
      operationId: getTaskMetadataWithTags
      responses:
        '200':
          description: Task metadata with tags
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/TaskMetadata'
                  - type: object
                    properties:
                      Tags:
                        type: object
                        additionalProperties:
                          type: string
                        description: Tags attached to the task
                      Errors:
                        type: array
                        items:
                          type: string
                        description: Errors encountered when retrieving tag metadata
  
  /stats:
    get:
      summary: Container Stats
      description: |
        Returns Docker stats for the specific container. 
        For Amazon ECS tasks that use the awsvpc or bridge network modes hosted on Amazon EC2 Linux instances
        running at least version 1.43.0 of the container agent, there will be additional network rate stats included in the response.
      operationId: getContainerStats
      parameters:
        - name: stream
          in: query
          description: Stream the output. If false, the stats will be output once and then it will disconnect.
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Container stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerStats'
        '404':
          description: No such container
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: The error message
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    description: The error message
  
  /task/stats:
    get:
      summary: Task Stats
      description: |
        Returns Docker stats for all of the containers associated with the task.
        For Amazon ECS tasks that use the awsvpc or bridge network modes hosted on Amazon EC2 Linux instances
        running at least version 1.43.0 of the container agent, there will be additional network rate stats included in the response.
      operationId: getTaskStats
      responses:
        '200':
          description: Task stats
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ContainerStats'
                description: Map of container IDs to their stats

components:
  schemas:
    ContainerMetadata:
      type: object
      properties:
        DockerId:
          type: string
          description: The Docker ID for the container. When using Fargate, the ID is a 32-digit hex followed by a 10-digit number.
        Name:
          type: string
          description: The name of the container as specified in the task definition.
        DockerName:
          type: string
          description: The name of the container supplied to Docker. The Amazon ECS container agent generates a unique name for the container.
        Image:
          type: string
          description: The image for the container.
        ImageID:
          type: string
          description: The SHA-256 digest for the image.
        Ports:
          type: array
          description: Any ports exposed for the container. This parameter is omitted if there are no exposed ports.
          items:
            type: object
            properties:
              ContainerPort:
                type: integer
                description: The port number on the container.
              HostPort:
                type: integer
                description: The port number on the host.
              BindIp:
                type: string
                description: The binding IP.
              Protocol:
                type: string
                description: The network protocol.
        Labels:
          type: object
          additionalProperties:
            type: string
          description: Any labels applied to the container. This parameter is omitted if there are no labels applied.
        DesiredStatus:
          type: string
          description: The desired status for the container from Amazon ECS.
        KnownStatus:
          type: string
          description: The known status for the container from Amazon ECS.
        ExitCode:
          type: integer
          description: The exit code for the container. This parameter is omitted if the container has not exited.
        Limits:
          type: object
          description: The resource limits specified at the container level. This parameter is omitted if no resource limits are defined.
          properties:
            CPU:
              type: number
              description: CPU limits expressed in CPU units.
            Memory:
              type: integer
              description: Memory limits in MB.
        CreatedAt:
          type: string
          format: date-time
          description: The timestamp for when the container was created. This parameter is omitted if the container has not been created yet.
        StartedAt:
          type: string
          format: date-time
          description: The timestamp for when the container started. This parameter is omitted if the container has not started yet.
        FinishedAt:
          type: string
          format: date-time
          description: The timestamp for when the container stopped. This parameter is omitted if the container has not stopped yet.
        Type:
          type: string
          description: The type of the container.
        LogDriver:
          type: string
          description: The log driver the container is using.
        LogOptions:
          type: object
          additionalProperties:
            type: string
          description: The log driver options defined for the container.
        ContainerARN:
          type: string
          description: The Amazon Resource Name (ARN) of the container.
        Networks:
          type: array
          description: The network information for the container. This parameter is omitted if no network information is defined.
          items:
            type: object
            properties:
              NetworkMode:
                type: string
                description: The network mode.
              IPv4Addresses:
                type: array
                items:
                  type: string
                description: The IPv4 addresses assigned to the container.
        RestartCount:
          type: integer
          description: The number of times the container has been restarted.
          
    TaskMetadata:
      type: object
      properties:
        Cluster:
          type: string
          description: The Amazon Resource Name (ARN) or short name of the Amazon ECS cluster to which the task belongs.
        ServiceName:
          type: string
          description: The name of the service to which the task belongs. Available for Amazon EC2 and Amazon ECS Anywhere container instances if the task is associated with a service.
        VPCID:
          type: string
          description: The VPC ID of the Amazon EC2 container instance. This field only appears for Amazon EC2 instances.
        TaskARN:
          type: string
          description: The Amazon Resource Name (ARN) of the task to which the container belongs.
        Family:
          type: string
          description: The family of the Amazon ECS task definition for the task.
        Revision:
          type: string
          description: The revision of the Amazon ECS task definition for the task.
        DesiredStatus:
          type: string
          description: The desired status for the task from Amazon ECS.
        KnownStatus:
          type: string
          description: The known status for the task from Amazon ECS.
        Limits:
          type: object
          description: The resource limits specified at the task level. This parameter is omitted if no resource limits are defined.
          properties:
            CPU:
              type: number
              description: CPU limits expressed in vCPUs.
            Memory:
              type: integer
              description: Memory limits in MB.
        PullStartedAt:
          type: string
          format: date-time
          description: The timestamp for when the first container image pull began.
        PullStoppedAt:
          type: string
          format: date-time
          description: The timestamp for when the last container image pull finished.
        AvailabilityZone:
          type: string
          description: The Availability Zone the task is in.
        LaunchType:
          type: string
          description: The launch type the task is using.
        Containers:
          type: array
          description: A list of container metadata for each container associated with the task.
          items:
            $ref: '#/components/schemas/ContainerMetadata'
        ExecutionStoppedAt:
          type: string
          format: date-time
          description: The timestamp for when the tasks DesiredStatus moved to STOPPED.
    
    ContainerStats:
      type: object
      description: Docker stats for the container
      properties:
        read:
          type: string
          format: date-time
          description: The timestamp when the stats were read
        preread:
          type: string
          format: date-time
          description: The timestamp of the previous read
        pids_stats:
          type: object
          properties:
            current:
              type: integer
              description: Current number of PIDs in the cgroup
            limit:
              type: integer
              description: The hard limit on PIDs in the cgroup
        blkio_stats:
          type: object
          description: Block I/O stats
        num_procs:
          type: integer
          description: Number of processes in the container
        storage_stats:
          type: object
          description: Storage stats
        cpu_stats:
          type: object
          description: CPU usage statistics
          properties:
            cpu_usage:
              type: object
              properties:
                total_usage:
                  type: integer
                  description: Total CPU time consumed
                percpu_usage:
                  type: array
                  items:
                    type: integer
                  description: CPU time consumed per CPU
                usage_in_kernelmode:
                  type: integer
                  description: CPU time consumed in kernel mode
                usage_in_usermode:
                  type: integer
                  description: CPU time consumed in user mode
            system_cpu_usage:
              type: integer
              description: Total CPU time of the host
            online_cpus:
              type: integer
              description: Number of online CPUs
            throttling_data:
              type: object
              properties:
                periods:
                  type: integer
                  description: Number of periods throttled
                throttled_periods:
                  type: integer
                  description: Number of throttled periods
                throttled_time:
                  type: integer
                  description: Total throttled time
        precpu_stats:
          type: object
          description: Previous CPU stats
        memory_stats:
          type: object
          description: Memory usage statistics
          properties:
            usage:
              type: integer
              description: Current memory usage
            max_usage:
              type: integer
              description: Maximum memory usage
            limit:
              type: integer
              description: Memory limit
            stats:
              type: object
              description: Detailed memory statistics
        networks:
          type: object
          additionalProperties:
            type: object
            properties:
              rx_bytes:
                type: integer
                description: Received bytes
              rx_packets:
                type: integer
                description: Received packets
              rx_errors:
                type: integer
                description: Receive errors
              rx_dropped:
                type: integer
                description: Receive packets dropped
              tx_bytes:
                type: integer
                description: Sent bytes
              tx_packets:
                type: integer
                description: Sent packets
              tx_errors:
                type: integer
                description: Transmit errors
              tx_dropped:
                type: integer
                description: Transmit packets dropped
              rx_rate:
                type: number
                description: Receive rate (bytes/sec)
              rx_packets_rate:
                type: number
                description: Receive packet rate (packets/sec)
              tx_rate:
                type: number
                description: Transmit rate (bytes/sec)
              tx_packets_rate:
                type: number
                description: Transmit packet rate (packets/sec)
          description: Network usage statistics
        name:
          type: string
          description: Container name
        id:
          type: string
          description: Container ID