backup_jobs

Creates, updates, deletes, gets or lists a backup_jobs resource.

Overview

Name	backup_jobs
Type	Resource
Id	aws.backup.backup_jobs

Fields

The following fields are returned by SELECT queries:

describe_backup_job

Name	Datatype	Description
account_id	string	Returns the account ID that owns the backup job. (pattern: <code>^[0-9]{12}$</code>)
backup_job_id	string	Uniquely identifies a request to Backup to back up a resource.
backup_options	object	Represents the options specified as part of backup plan or on-demand backup job.
backup_size_in_bytes	integer (int64)	The size, in bytes, of a backup (recovery point). This value can render differently depending on the resource type as Backup pulls in data information from other Amazon Web Services services. For example, the value returned may show a value of 0, which may differ from the anticipated value. The expected behavior for values by resource type are described as follows: Amazon Aurora, Amazon DocumentDB, and Amazon Neptune do not have this value populate from the operation GetBackupJobStatus. For Amazon DynamoDB with advanced features, this value refers to the size of the recovery point (backup). Amazon EC2 and Amazon EBS show volume size (provisioned storage) returned as part of this value. Amazon EBS does not return backup size information; snapshot size will have the same value as the original resource that was backed up. For Amazon EFS, this value refers to the delta bytes transferred during a backup. For Amazon EKS, this value refers to the size of your nested EKS recovery point. Amazon FSx does not populate this value from the operation GetBackupJobStatus for FSx file systems. An Amazon RDS instance will show as 0. For virtual machines running VMware, this value is passed to Backup through an asynchronous workflow, which can mean this displayed value can under-represent the actual backup size.
backup_type	string	Represents the actual backup type selected for a backup job. For example, if a successful Windows Volume Shadow Copy Service (VSS) backup was taken, BackupType returns "WindowsVSS". If BackupType is empty, then the backup type was a regular backup.
backup_vault_arn	string	An Amazon Resource Name (ARN) that uniquely identifies a backup vault; for example, arn:aws:backup:us-east-1:123456789012:backup-vault:aBackupVault.
backup_vault_name	string	The name of a logical container where backups are stored. Backup vaults are identified by names that are unique to the account used to create them and the Amazon Web Services Region where they are created. (pattern: <code>^[a-zA-Z0-9-_]{2,50}$</code>)
bytes_transferred	integer (int64)	The size in bytes transferred to a backup vault at the time that the job status was queried.
child_jobs_in_state	object	This returns the statistics of the included child (nested) backup jobs.
completion_date	string (date-time)	The date and time that a job to create a backup job is completed, in Unix format and Coordinated Universal Time (UTC). The value of CompletionDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
created_by	object	Contains identifying information about the creation of a backup job, including the BackupPlanArn, BackupPlanId, BackupPlanVersion, and BackupRuleId of the backup plan that is used to create it.
creation_date	string (date-time)	The date and time that a backup job is created, in Unix format and Coordinated Universal Time (UTC). The value of CreationDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
encryption_key_arn	string	The Amazon Resource Name (ARN) of the KMS key used to encrypt the backup. This can be a customer-managed key or an Amazon Web Services managed key, depending on the vault configuration.
expected_completion_date	string (date-time)	The date and time that a job to back up resources is expected to be completed, in Unix format and Coordinated Universal Time (UTC). The value of ExpectedCompletionDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
iam_role_arn	string	Specifies the IAM role ARN used to create the target recovery point; for example, arn:aws:iam::123456789012:role/S3Access.
initiation_date	string (date-time)	The date a backup job was initiated.
is_encrypted	boolean	A boolean value indicating whether the backup is encrypted. All backups in Backup are encrypted, but this field indicates the encryption status for transparency.
is_parent	boolean	This returns the boolean value that a backup job is a parent (composite) job.
message_category	string	The job count for the specified message category. Example strings may include AccessDenied, SUCCESS, AGGREGATE_ALL, and INVALIDPARAMETERS. View Monitoring for a list of accepted MessageCategory strings.
number_of_child_jobs	integer (int64)	This returns the number of child (nested) backup jobs.
parent_job_id	string	This returns the parent (composite) resource backup job ID.
percent_done	string	Contains an estimated percentage that is complete of a job at the time the job status was queried.
recovery_point_arn	string	An ARN that uniquely identifies a recovery point; for example, arn:aws:backup:us-east-1:123456789012:recovery-point:1EB3B5E7-9EB0-435A-A80B-108B488B0D45.
recovery_point_lifecycle	object	Specifies the time period, in days, before a recovery point transitions to cold storage or is deleted. Backups transitioned to cold storage must be stored in cold storage for a minimum of 90 days. Therefore, on the console, the retention setting must be 90 days greater than the transition to cold after days setting. The transition to cold after days setting can't be changed after a backup has been transitioned to cold. Resource types that can transition to cold storage are listed in the Feature availability by resource table. Backup ignores this expression for other resource types. To remove the existing lifecycle and retention periods and keep your recovery points indefinitely, specify -1 for MoveToColdStorageAfterDays and DeleteAfterDays.
resource_arn	string	An ARN that uniquely identifies a saved resource. The format of the ARN depends on the resource type.
resource_name	string	The non-unique name of the resource that belongs to the specified backup.
resource_type	string	The type of Amazon Web Services resource to be backed up; for example, an Amazon Elastic Block Store (Amazon EBS) volume or an Amazon Relational Database Service (Amazon RDS) database. (pattern: <code>^[a-zA-Z0-9-_.]{1,50}$</code>)
start_by	string (date-time)	Specifies the time in Unix format and Coordinated Universal Time (UTC) when a backup job must be started before it is canceled. The value is calculated by adding the start window to the scheduled time. So if the scheduled time were 6:00 PM and the start window is 2 hours, the StartBy time would be 8:00 PM on the date specified. The value of StartBy is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
state	string	The current state of a backup job. (CREATED, PENDING, RUNNING, ABORTING, ABORTED, COMPLETED, FAILED, EXPIRED, PARTIAL)
status_message	string	A detailed message explaining the status of the job to back up a resource.
vault_lock_state	string	The lock state of the backup vault. For logically air-gapped vaults, this indicates whether the vault is locked in compliance mode. Valid values include LOCKED and UNLOCKED.
vault_type	string	The type of backup vault where the recovery point is stored. Valid values are BACKUP_VAULT for standard backup vaults and LOGICALLY_AIR_GAPPED_BACKUP_VAULT for logically air-gapped vaults.

list_backup_jobs

Name	Datatype	Description
account_id	string	The account ID that owns the backup job. (pattern: <code>^[0-9]{12}$</code>)
backup_job_id	string	Uniquely identifies a request to Backup to back up a resource.
backup_options	object	Specifies the backup option for a selected resource. This option is only available for Windows Volume Shadow Copy Service (VSS) backup jobs. Valid values: Set to "WindowsVSS":"enabled" to enable the WindowsVSS backup option and create a Windows VSS backup. Set to "WindowsVSS":"disabled" to create a regular backup. If you specify an invalid option, you get an InvalidParameterValueException exception.
backup_size_in_bytes	integer (int64)	The size, in bytes, of a backup (recovery point). This value can render differently depending on the resource type as Backup pulls in data information from other Amazon Web Services services. For example, the value returned may show a value of 0, which may differ from the anticipated value. The expected behavior for values by resource type are described as follows: Amazon Aurora, Amazon DocumentDB, and Amazon Neptune do not have this value populate from the operation GetBackupJobStatus. For Amazon DynamoDB with advanced features, this value refers to the size of the recovery point (backup). Amazon EC2 and Amazon EBS show volume size (provisioned storage) returned as part of this value. Amazon EBS does not return backup size information; snapshot size will have the same value as the original resource that was backed up. For Amazon EFS, this value refers to the delta bytes transferred during a backup. For Amazon EKS, this value refers to the size of your nested EKS recovery point. Amazon FSx does not populate this value from the operation GetBackupJobStatus for FSx file systems. An Amazon RDS instance will show as 0. For virtual machines running VMware, this value is passed to Backup through an asynchronous workflow, which can mean this displayed value can under-represent the actual backup size.
backup_type	string	Represents the type of backup for a backup job.
backup_vault_arn	string	An Amazon Resource Name (ARN) that uniquely identifies a backup vault; for example, arn:aws:backup:us-east-1:123456789012:backup-vault:aBackupVault.
backup_vault_name	string	The name of a logical container where backups are stored. Backup vaults are identified by names that are unique to the account used to create them and the Amazon Web Services Region where they are created. (pattern: <code>^[a-zA-Z0-9-_]{2,50}$</code>)
bytes_transferred	integer (int64)	The size in bytes transferred to a backup vault at the time that the job status was queried.
completion_date	string (date-time)	The date and time a job to create a backup job is completed, in Unix format and Coordinated Universal Time (UTC). The value of CompletionDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
created_by	object	Contains information about the backup plan and rule that Backup used to initiate the recovery point backup.
creation_date	string (date-time)	The date and time a backup job is created, in Unix format and Coordinated Universal Time (UTC). The value of CreationDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
encryption_key_arn	string	The Amazon Resource Name (ARN) of the KMS key used to encrypt the backup. This can be a customer-managed key or an Amazon Web Services managed key, depending on the vault configuration.
expected_completion_date	string (date-time)	The date and time a job to back up resources is expected to be completed, in Unix format and Coordinated Universal Time (UTC). The value of ExpectedCompletionDate is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
iam_role_arn	string	Specifies the IAM role ARN used to create the target recovery point. IAM roles other than the default role must include either AWSBackup or AwsBackup in the role name. For example, arn:aws:iam::123456789012:role/AWSBackupRDSAccess. Role names without those strings lack permissions to perform backup jobs.
initiation_date	string (date-time)	The date on which the backup job was initiated.
is_encrypted	boolean	A boolean value indicating whether the backup is encrypted. All backups in Backup are encrypted, but this field indicates the encryption status for transparency.
is_parent	boolean	This is a boolean value indicating this is a parent (composite) backup job.
message_category	string	This parameter is the job count for the specified message category. Example strings may include AccessDenied, SUCCESS, AGGREGATE_ALL, and INVALIDPARAMETERS. See Monitoring for a list of MessageCategory strings. The the value ANY returns count of all message categories. AGGREGATE_ALL aggregates job counts for all message categories and returns the sum.
parent_job_id	string	This uniquely identifies a request to Backup to back up a resource. The return will be the parent (composite) job ID.
percent_done	string	Contains an estimated percentage complete of a job at the time the job status was queried.
recovery_point_arn	string	An ARN that uniquely identifies a recovery point; for example, arn:aws:backup:us-east-1:123456789012:recovery-point:1EB3B5E7-9EB0-435A-A80B-108B488B0D45.
recovery_point_lifecycle	object	Specifies the time period, in days, before a recovery point transitions to cold storage or is deleted. Backups transitioned to cold storage must be stored in cold storage for a minimum of 90 days. Therefore, on the console, the retention setting must be 90 days greater than the transition to cold after days setting. The transition to cold after days setting can't be changed after a backup has been transitioned to cold. Resource types that can transition to cold storage are listed in the Feature availability by resource table. Backup ignores this expression for other resource types. To remove the existing lifecycle and retention periods and keep your recovery points indefinitely, specify -1 for MoveToColdStorageAfterDays and DeleteAfterDays.
resource_arn	string	An ARN that uniquely identifies a resource. The format of the ARN depends on the resource type.
resource_name	string	The non-unique name of the resource that belongs to the specified backup.
resource_type	string	The type of Amazon Web Services resource to be backed up; for example, an Amazon Elastic Block Store (Amazon EBS) volume or an Amazon Relational Database Service (Amazon RDS) database. For Windows Volume Shadow Copy Service (VSS) backups, the only supported resource type is Amazon EC2. (pattern: <code>^[a-zA-Z0-9-_.]{1,50}$</code>)
start_by	string (date-time)	Specifies the time in Unix format and Coordinated Universal Time (UTC) when a backup job must be started before it is canceled. The value is calculated by adding the start window to the scheduled time. So if the scheduled time were 6:00 PM and the start window is 2 hours, the StartBy time would be 8:00 PM on the date specified. The value of StartBy is accurate to milliseconds. For example, the value 1516925490.087 represents Friday, January 26, 2018 12:11:30.087 AM.
state	string	The current state of a backup job. (CREATED, PENDING, RUNNING, ABORTING, ABORTED, COMPLETED, FAILED, EXPIRED, PARTIAL)
status_message	string	A detailed message explaining the status of the job to back up a resource.
vault_lock_state	string	The lock state of the backup vault. For logically air-gapped vaults, this indicates whether the vault is locked in compliance mode. Valid values include LOCKED and UNLOCKED.
vault_type	string	The type of backup vault where the recovery point is stored. Valid values are BACKUP_VAULT for standard backup vaults and LOGICALLY_AIR_GAPPED_BACKUP_VAULT for logically air-gapped vaults.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_backup_job	select	backup_job_id, region		Returns backup job details for the specified BackupJobId.
list_backup_jobs	select	region	nextToken, maxResults, resourceArn, state, backupVaultName, createdBefore, createdAfter, resourceType, accountId, completeAfter, completeBefore, parentJobId, messageCategory	Returns a list of existing backup jobs for an authenticated account for the last 30 days. For a longer period of time, consider using these monitoring tools.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
backup_job_id	string	Uniquely identifies a request to Backup to back up a resource.
region	string	AWS region (default: us-east-1)
accountId	string	The account ID to list the jobs from. Returns only backup jobs associated with the specified account ID. If used from an Organizations management account, passing * returns all jobs across the organization.
backupVaultName	string	Returns only backup jobs that will be stored in the specified backup vault. Backup vaults are identified by names that are unique to the account used to create them and the Amazon Web Services Region where they are created.
completeAfter	string (date-time)	Returns only backup jobs completed after a date expressed in Unix format and Coordinated Universal Time (UTC).
completeBefore	string (date-time)	Returns only backup jobs completed before a date expressed in Unix format and Coordinated Universal Time (UTC).
createdAfter	string (date-time)	Returns only backup jobs that were created after the specified date.
createdBefore	string (date-time)	Returns only backup jobs that were created before the specified date.
maxResults	integer	The maximum number of items to be returned.
messageCategory	string	This is an optional parameter that can be used to filter out jobs with a MessageCategory which matches the value you input. Example strings may include AccessDenied, SUCCESS, AGGREGATE_ALL, and InvalidParameters. View Monitoring The wildcard () returns count of all message categories. AGGREGATE_ALL aggregates job counts for all message categories and returns the sum.
nextToken	string	The next item following a partial list of returned items. For example, if a request is made to return MaxResults number of items, NextToken allows you to return more items in your list starting at the location pointed to by the next token.
parentJobId	string	This is a filter to list child (nested) jobs based on parent job ID.
resourceArn	string	Returns only backup jobs that match the specified resource Amazon Resource Name (ARN).
resourceType	string	Returns only backup jobs for the specified resources: Aurora for Amazon Aurora CloudFormation for CloudFormation DocumentDB for Amazon DocumentDB (with MongoDB compatibility) DynamoDB for Amazon DynamoDB EBS for Amazon Elastic Block Store EC2 for Amazon Elastic Compute Cloud EFS for Amazon Elastic File System EKS for Amazon Elastic Kubernetes Service FSx for Amazon FSx Neptune for Amazon Neptune RDS for Amazon Relational Database Service Redshift for Amazon Redshift S3 for Amazon Simple Storage Service (Amazon S3) SAP HANA on Amazon EC2 for SAP HANA databases on Amazon Elastic Compute Cloud instances Storage Gateway for Storage Gateway Timestream for Amazon Timestream VirtualMachine for VMware virtual machines
state	string	Returns only backup jobs that are in the specified state. Completed with issues is a status found only in the Backup console. For API, this status refers to jobs with a state of COMPLETED and a MessageCategory with a value other than SUCCESS; that is, the status is completed but comes with a status message. To obtain the job count for Completed with issues, run two GET requests, and subtract the second, smaller number: GET /backup-jobs/?state=COMPLETED GET /backup-jobs/?messageCategory=SUCCESS&state=COMPLETED

SELECT examples

describe_backup_job

Returns backup job details for the specified BackupJobId.

SELECT
account_id,
backup_job_id,
backup_options,
backup_size_in_bytes,
backup_type,
backup_vault_arn,
backup_vault_name,
bytes_transferred,
child_jobs_in_state,
completion_date,
created_by,
creation_date,
encryption_key_arn,
expected_completion_date,
iam_role_arn,
initiation_date,
is_encrypted,
is_parent,
message_category,
number_of_child_jobs,
parent_job_id,
percent_done,
recovery_point_arn,
recovery_point_lifecycle,
resource_arn,
resource_name,
resource_type,
start_by,
state,
status_message,
vault_lock_state,
vault_type
FROM aws.backup.backup_jobs
WHERE backup_job_id = '{{ backup_job_id }}' -- required
AND region = '{{ region }}' -- required
;

list_backup_jobs

Returns a list of existing backup jobs for an authenticated account for the last 30 days. For a longer period of time, consider using these monitoring tools.

SELECT
account_id,
backup_job_id,
backup_options,
backup_size_in_bytes,
backup_type,
backup_vault_arn,
backup_vault_name,
bytes_transferred,
completion_date,
created_by,
creation_date,
encryption_key_arn,
expected_completion_date,
iam_role_arn,
initiation_date,
is_encrypted,
is_parent,
message_category,
parent_job_id,
percent_done,
recovery_point_arn,
recovery_point_lifecycle,
resource_arn,
resource_name,
resource_type,
start_by,
state,
status_message,
vault_lock_state,
vault_type
FROM aws.backup.backup_jobs
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
AND resourceArn = '{{ resourceArn }}'
AND state = '{{ state }}'
AND backupVaultName = '{{ backupVaultName }}'
AND createdBefore = '{{ createdBefore }}'
AND createdAfter = '{{ createdAfter }}'
AND resourceType = '{{ resourceType }}'
AND accountId = '{{ accountId }}'
AND completeAfter = '{{ completeAfter }}'
AND completeBefore = '{{ completeBefore }}'
AND parentJobId = '{{ parentJobId }}'
AND messageCategory = '{{ messageCategory }}'
;