{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/amazon-ecs/json-schema/amazon-ecs-start-task-request-schema.json",
  "title": "StartTaskRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/amazon-ecs-tasks-api-openapi.yml#/components/schemas/StartTaskRequest",
  "type": "object",
  "properties": {
    "cluster": {
      "type": "string",
      "description": "The short name or full Amazon Resource Name (ARN) of the cluster where to start your task. If you do not specify a cluster, the default cluster is assumed."
    },
    "containerInstances": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The container instance IDs or full ARN entries for the container instances where you would like to place your task. You can specify up to 10 container instances."
    },
    "enableECSManagedTags": {
      "type": "boolean",
      "description": "Specifies whether to use Amazon ECS managed tags for the task. For more information, see Tagging Your Amazon ECS Resources in the Amazon Elastic Container Service Developer Guide."
    },
    "enableExecuteCommand": {
      "type": "boolean",
      "description": "Whether or not the execute command functionality is turned on for the task. If true, this turns on the execute command functionality on all containers in the task."
    },
    "group": {
      "type": "string",
      "description": "The name of the task group to associate with the task. The default value is the family name of the task definition (for example, family:my-family-name)."
    },
    "networkConfiguration": {
      "$ref": "#/$defs/NetworkConfiguration"
    },
    "overrides": {
      "$ref": "#/$defs/TaskOverride"
    },
    "propagateTags": {
      "type": "string",
      "enum": [
        "TASK_DEFINITION",
        "SERVICE",
        "NONE"
      ],
      "description": "Specifies whether to propagate the tags from the task definition or the service to the task. If no value is specified, the tags aren't propagated."
    },
    "referenceId": {
      "type": "string",
      "description": "This parameter is only used by Amazon ECS. It is not intended for use by customers."
    },
    "startedBy": {
      "type": "string",
      "description": "An optional tag specified when a task is started. For example, if you automatically trigger a task to run a batch process job, you could apply a unique identifier for that job to your task with the startedBy parameter. You can then identify which tasks belong to that job by filtering the results of a ListTasks call with the startedBy value. Up to 36 letters (uppercase and lowercase), numbers, hyphens (-), forward slash (/), and underscores (_) are allowed. If a task is started by an Amazon ECS service, the startedBy parameter contains the deployment ID of the service that starts it."
    },
    "tags": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Tag"
      },
      "description": "The metadata that you apply to the task to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. The following basic restrictions apply to tags: Maximum number of tags per resource - 50 For each resource, each tag key must be unique, and each tag key can have only one value. Maximum key length - 128 Unicode characters in UTF-8 Maximum value length - 256 Unicode characters in UTF-8 If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally "
    },
    "taskDefinition": {
      "type": "string",
      "description": "The family and revision (family:revision) or full ARN of the task definition to start. If a revision isn't specified, the latest ACTIVE revision is used."
    },
    "volumeConfigurations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TaskVolumeConfiguration"
      },
      "description": "The details of the volume that was configuredAtLaunch. You can configure the size, volumeType, IOPS, throughput, snapshot and encryption in TaskManagedEBSVolumeConfiguration. The name of the volume must match the name from the task definition."
    }
  },
  "required": [
    "containerInstances",
    "taskDefinition"
  ],
  "$defs": {
    "AwsVpcConfiguration": {
      "type": "object",
      "properties": {
        "subnets": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The IDs of the subnets associated with the task or service. There's a limit of 16 subnets that can be specified. All specified subnets must be from the same VPC."
        },
        "securityGroups": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The IDs of the security groups associated with the task or service. If you don't specify a security group, the default security group for the VPC is used. There's a limit of 5 security groups that can be specified. All specified security groups must be from the same VPC."
        },
        "assignPublicIp": {
          "type": "string",
          "enum": [
            "ENABLED",
            "DISABLED"
          ],
          "description": "Whether the task's elastic network interface receives a public IP address. Consider the following when you set this value: When you use create-service or update-service, the default is DISABLED. When the service deploymentController is ECS, the value must be DISABLED."
        }
      },
      "required": [
        "subnets"
      ]
    },
    "ContainerOverride": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the container that receives the override. This parameter is required if any override is specified."
        },
        "command": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name."
        },
        "environment": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/KeyValuePair"
          },
          "description": "The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition. You must also specify a container name."
        },
        "environmentFiles": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EnvironmentFile"
          },
          "description": "A list of files containing the environment variables to pass to a container, instead of the value from the container definition."
        },
        "cpu": {
          "type": "integer",
          "description": "The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name."
        },
        "memory": {
          "type": "integer",
          "description": "The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name."
        },
        "memoryReservation": {
          "type": "integer",
          "description": "The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name."
        },
        "resourceRequirements": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ResourceRequirement"
          },
          "description": "The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices."
        }
      }
    },
    "EBSTagSpecification": {
      "type": "object",
      "properties": {
        "resourceType": {
          "type": "string",
          "enum": [
            "volume"
          ],
          "description": "The type of volume resource."
        },
        "tags": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Tag"
          },
          "description": "The tags applied to this Amazon EBS volume. AmazonECSCreated and AmazonECSManaged are reserved tags that can't be used."
        },
        "propagateTags": {
          "type": "string",
          "enum": [
            "TASK_DEFINITION",
            "SERVICE",
            "NONE"
          ],
          "description": "Determines whether to propagate the tags from the task definition to the Amazon EBS volume. Tags can only propagate to a SERVICE specified in ServiceVolumeConfiguration. If no value is specified, the tags aren't propagated."
        }
      },
      "required": [
        "resourceType"
      ]
    },
    "EnvironmentFile": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file."
        },
        "type": {
          "type": "string",
          "enum": [
            "s3"
          ],
          "description": "The file type to use. Environment files are objects in Amazon S3. The only supported value is s3."
        }
      },
      "required": [
        "value",
        "type"
      ]
    },
    "EphemeralStorage": {
      "type": "object",
      "properties": {
        "sizeInGiB": {
          "type": "integer",
          "description": "The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB."
        }
      },
      "required": [
        "sizeInGiB"
      ]
    },
    "InferenceAcceleratorOverride": {
      "type": "object",
      "properties": {
        "deviceName": {
          "type": "string",
          "description": "The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition."
        },
        "deviceType": {
          "type": "string",
          "description": "The Elastic Inference accelerator type to use."
        }
      }
    },
    "KeyValuePair": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the key-value pair. For environment variables, this is the name of the environment variable."
        },
        "value": {
          "type": "string",
          "description": "The value of the key-value pair. For environment variables, this is the value of the environment variable."
        }
      }
    },
    "NetworkConfiguration": {
      "type": "object",
      "properties": {
        "awsvpcConfiguration": {
          "$ref": "#/$defs/AwsVpcConfiguration"
        }
      }
    },
    "NvidiaMpsAllocation": {
      "type": "object",
      "properties": {
        "memory": {
          "type": "integer",
          "description": "The amount of GPU memory, in MiB, to allocate to the container. Amazon ECS assigns the container a GPU that has at least the specified amount of memory available, and sets the CUDA_MPS_PINNED_DEVICE_MEM_LIMIT environment variable in the container to limit its memory to this amount. The memory must be available on a single GPU. If more than one container in a task uses nvidiaMps, Amazon ECS assigns them the same GPU, which must have enough memory available for all of them."
        },
        "maxComputePercent": {
          "type": "integer",
          "description": "The maximum percentage of the GPU's compute capacity that the container can use. Amazon ECS sets the CUDA_MPS_ACTIVE_THREAD_PERCENTAGE environment variable in the container to this value. This value is a limit, not a reservation. If you don't specify this parameter, Amazon ECS doesn't set CUDA_MPS_ACTIVE_THREAD_PERCENTAGE, and the active thread percentage of the MPS server on the container instance applies. By default, this is 100 percent."
        }
      },
      "required": [
        "memory"
      ]
    },
    "ResourceRequirement": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "The value for the specified resource type. You must specify this parameter unless the type is GPU and you specify sharingStrategy. When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container. When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devic"
        },
        "type": {
          "type": "string",
          "enum": [
            "GPU",
            "InferenceAccelerator",
            "NeuronDevice"
          ],
          "description": "The type of resource to assign to a container."
        },
        "sharingStrategy": {
          "$ref": "#/$defs/SharingStrategy"
        }
      },
      "required": [
        "type"
      ]
    },
    "SharingStrategy": {
      "type": "object",
      "properties": {
        "nvidiaMps": {
          "$ref": "#/$defs/NvidiaMpsAllocation"
        }
      },
      "description": "Exactly one member is set."
    },
    "Tag": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values."
        },
        "value": {
          "type": "string",
          "description": "The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key)."
        }
      }
    },
    "TaskManagedEBSVolumeConfiguration": {
      "type": "object",
      "properties": {
        "encrypted": {
          "type": "boolean",
          "description": "Indicates whether the volume should be encrypted. If you turn on Region-level Amazon EBS encryption by default but set this value as false, the setting is overridden and the volume is encrypted with the KMS key specified for Amazon EBS encryption by default. This parameter maps 1:1 with the Encrypted parameter of the CreateVolume API in the Amazon EC2 API Reference."
        },
        "kmsKeyId": {
          "type": "string",
          "description": "The Amazon Resource Name (ARN) identifier of the Amazon Web Services Key Management Service key to use for Amazon EBS encryption. When a key is specified using this parameter, it overrides Amazon EBS default encryption or any KMS key that you specified for cluster-level managed storage encryption. This parameter maps 1:1 with the KmsKeyId parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information about encrypting Amazon EBS volumes attached to a task, see Encrypt data stored in Amazon EBS volumes attached to Amazon ECS tasks. Amazon Web Services authenticates the A"
        },
        "volumeType": {
          "type": "string",
          "description": "The volume type. This parameter maps 1:1 with the VolumeType parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information, see Amazon EBS volume types in the Amazon EC2 User Guide. The following are the supported volume types. General Purpose SSD: gp2|gp3 Provisioned IOPS SSD: io1|io2 Throughput Optimized HDD: st1 Cold HDD: sc1 Magnetic: standard The magnetic volume type is not supported on Fargate."
        },
        "sizeInGiB": {
          "type": "integer",
          "description": "The size of the volume in GiB. You must specify either a volume size or a snapshot ID. If you specify a snapshot ID, the snapshot size is used for the volume size by default. You can optionally specify a volume size greater than or equal to the snapshot size. This parameter maps 1:1 with the Size parameter of the CreateVolume API in the Amazon EC2 API Reference. The following are the supported volume size values for each volume type. gp2 and gp3: 1-16,384 io1 and io2: 4-16,384 st1 and sc1: 125-16,384 standard: 1-1,024"
        },
        "snapshotId": {
          "type": "string",
          "description": "The snapshot that Amazon ECS uses to create the volume. You must specify either a snapshot ID or a volume size. This parameter maps 1:1 with the SnapshotId parameter of the CreateVolume API in the Amazon EC2 API Reference."
        },
        "volumeInitializationRate": {
          "type": "integer",
          "description": "The rate, in MiB/s, at which data is fetched from a snapshot of an existing Amazon EBS volume to create a new volume for attachment to the task. This property can be specified only if you specify a snapshotId. For more information, see Initialize Amazon EBS volumes in the Amazon EBS User Guide."
        },
        "iops": {
          "type": "integer",
          "description": "The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting. The following are the supported values for each volume type. gp3: 3,000 - 16,000 IOPS io1: 100 - 64,000 IOPS io2: 100 - 256,000 IOPS This parameter is required for io1 and io2 volume types. The default for gp3 volumes is 3,000 IOPS. This parameter is not supported for st1, sc1, or standard volume types. T"
        },
        "throughput": {
          "type": "integer",
          "description": "The throughput to provision for a volume, in MiB/s, with a maximum of 1,000 MiB/s. This parameter maps 1:1 with the Throughput parameter of the CreateVolume API in the Amazon EC2 API Reference. This parameter is only supported for the gp3 volume type."
        },
        "tagSpecifications": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EBSTagSpecification"
          },
          "description": "The tags to apply to the volume. Amazon ECS applies service-managed tags by default. This parameter maps 1:1 with the TagSpecifications.N parameter of the CreateVolume API in the Amazon EC2 API Reference."
        },
        "roleArn": {
          "type": "string",
          "description": "The ARN of the IAM role to associate with this volume. This is the Amazon ECS infrastructure IAM role that is used to manage your Amazon Web Services infrastructure. We recommend using the Amazon ECS-managed AmazonECSInfrastructureRolePolicyForVolumes IAM policy with this role. For more information, see Amazon ECS infrastructure IAM role in the Amazon ECS Developer Guide."
        },
        "terminationPolicy": {
          "$ref": "#/$defs/TaskManagedEBSVolumeTerminationPolicy"
        },
        "filesystemType": {
          "type": "string",
          "enum": [
            "ext3",
            "ext4",
            "xfs",
            "ntfs"
          ],
          "description": "The Linux filesystem type for the volume. For volumes created from a snapshot, you must specify the same filesystem type that the volume was using when the snapshot was created. If there is a filesystem type mismatch, the task will fail to start. The available filesystem types are ext3, ext4, and xfs. If no value is specified, the xfs filesystem type is used by default."
        }
      },
      "required": [
        "roleArn"
      ]
    },
    "TaskManagedEBSVolumeTerminationPolicy": {
      "type": "object",
      "properties": {
        "deleteOnTermination": {
          "type": "boolean",
          "description": "Indicates whether the volume should be deleted on when the task stops. If a value of true is specified, Amazon ECS deletes the Amazon EBS volume on your behalf when the task goes into the STOPPED state. If no value is specified, the default value is true is used. When set to false, Amazon ECS leaves the volume in your account."
        }
      },
      "required": [
        "deleteOnTermination"
      ]
    },
    "TaskOverride": {
      "type": "object",
      "properties": {
        "containerOverrides": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ContainerOverride"
          },
          "description": "One or more container overrides that are sent to a task."
        },
        "cpu": {
          "type": "string",
          "description": "The CPU override for the task."
        },
        "inferenceAcceleratorOverrides": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InferenceAcceleratorOverride"
          },
          "description": "The Elastic Inference accelerator override for the task."
        },
        "executionRoleArn": {
          "type": "string",
          "description": "The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide."
        },
        "memory": {
          "type": "string",
          "description": "The memory override for the task."
        },
        "taskRoleArn": {
          "type": "string",
          "description": "The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide."
        },
        "ephemeralStorage": {
          "$ref": "#/$defs/EphemeralStorage"
        }
      }
    },
    "TaskVolumeConfiguration": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the volume. This value must match the volume name from the Volume object in the task definition."
        },
        "managedEBSVolume": {
          "$ref": "#/$defs/TaskManagedEBSVolumeConfiguration"
        }
      },
      "required": [
        "name"
      ]
    }
  }
}