ListBackupsCommand

Suggest an Edit

List DynamoDB backups that are associated with an Amazon Web Services account and weren't made with Amazon Web Services Backup. To list these backups for a given table, specify TableName. ListBackups returns a paginated list of results with at most 1 MB worth of items in a page. You can also specify a maximum number of entries to be returned in a page.

In the request, start time is inclusive, but end time is exclusive. Note that these boundaries are for the time at which the original backup was requested.

You can call ListBackups a maximum of five times per second.

If you want to retrieve the complete list of backups made with Amazon Web Services Backup, use the Amazon Web Services Backup list API. 

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { DynamoDBClient, ListBackupsCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import
// const { DynamoDBClient, ListBackupsCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import
const client = new DynamoDBClient(config);
const input = { // ListBackupsInput
  TableName: "STRING_VALUE",
  Limit: Number("int"),
  TimeRangeLowerBound: new Date("TIMESTAMP"),
  TimeRangeUpperBound: new Date("TIMESTAMP"),
  ExclusiveStartBackupArn: "STRING_VALUE",
  BackupType: "USER" || "SYSTEM" || "AWS_BACKUP" || "ALL",
};
const command = new ListBackupsCommand(input);
const response = await client.send(command);
// { // ListBackupsOutput
//   BackupSummaries: [ // BackupSummaries
//     { // BackupSummary
//       TableName: "STRING_VALUE",
//       TableId: "STRING_VALUE",
//       TableArn: "STRING_VALUE",
//       BackupArn: "STRING_VALUE",
//       BackupName: "STRING_VALUE",
//       BackupCreationDateTime: new Date("TIMESTAMP"),
//       BackupExpiryDateTime: new Date("TIMESTAMP"),
//       BackupStatus: "CREATING" || "DELETED" || "AVAILABLE",
//       BackupType: "USER" || "SYSTEM" || "AWS_BACKUP",
//       BackupSizeBytes: Number("long"),
//     },
//   ],
//   LastEvaluatedBackupArn: "STRING_VALUE",
// };

ListBackupsCommand Input

See ListBackupsCommandInput for more details

Parameter
Type
Description
BackupType
BackupTypeFilter | undefined

The backups from the table specified by BackupType are listed.

Where BackupType can be:

  • USER - On-demand backup created by you. (The default setting if no other backup types are specified.)

  • SYSTEM - On-demand backup automatically created by DynamoDB.

  • ALL - All types of on-demand backups (USER and SYSTEM).

ExclusiveStartBackupArn
string | undefined

LastEvaluatedBackupArn is the Amazon Resource Name (ARN) of the backup last evaluated when the current page of results was returned, inclusive of the current page of results. This value may be specified as the ExclusiveStartBackupArn of a new ListBackups operation in order to fetch the next page of results.

Limit
number | undefined

Maximum number of backups to return at once.

TableName
string | undefined

Lists the backups from the table specified in TableName. You can also provide the Amazon Resource Name (ARN) of the table in this parameter.

TimeRangeLowerBound
Date | undefined

Only backups created after this time are listed. TimeRangeLowerBound is inclusive.

TimeRangeUpperBound
Date | undefined

Only backups created before this time are listed. TimeRangeUpperBound is exclusive.

ListBackupsCommand Output

See ListBackupsCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
BackupSummaries
BackupSummary[] | undefined

List of BackupSummary objects.

LastEvaluatedBackupArn
string | undefined

The ARN of the backup last evaluated when the current page of results was returned, inclusive of the current page of results. This value may be specified as the ExclusiveStartBackupArn of a new ListBackups operation in order to fetch the next page of results.

If LastEvaluatedBackupArn is empty, then the last page of results has been processed and there are no more results to be retrieved.

If LastEvaluatedBackupArn is not empty, this may or may not indicate that there is more data to be returned. All results are guaranteed to have been returned if and only if no value for LastEvaluatedBackupArn is returned.

Throws

Name
Fault
Details
InternalServerError
server

An error occurred on the server side.

InvalidEndpointException
client
DynamoDBServiceException
Base exception class for all service exceptions from DynamoDB service.