Usage Statistics - Amazon Macie

Usage Statistics

The Usage Statistics resource provides information about current quotas and usage statistics for your Amazon Macie account. This includes metrics that report the estimated cost of using Macie to perform specific types of tasks, and current account quotas for those tasks. The data can help you track your use of the service and determine whether to adjust your quotas or use of the service. For information about how Macie calculates usage statistics and data for your account, see Forecasting and monitoring costs in the Amazon Macie User Guide.

If you're participating in a 30-day free trial, the applicable cost estimates are based on your use of Macie thus far during the trial. They can help you understand what your usage costs might be after the trial ends. This resource also provides information about when each trial started for your account.

You can use the Usage Statistics resource to retrieve (query) aggregated data for usage metrics that apply to your Macie account and the quotas that correspond to those metrics. If you're the Macie administrator for an organization, this resource provides a breakdown of quota, usage, and free-trial data for individual member accounts in your organization.

To customize your query, you can use supported parameters to filter and sort the data. You can also specify a time range for the data. The time range can be the preceding 30 days or the current calendar month to date.

URI

/usage/statistics

HTTP methods

POST

Operation ID: GetUsageStatistics

Retrieves (queries) quotas and aggregated usage data for one or more accounts.

Responses
Status codeResponse modelDescription
200GetUsageStatisticsResponse

The request succeeded.

400ValidationException

The request failed because the input doesn't satisfy the constraints specified by the service.

402ServiceQuotaExceededException

The request failed because fulfilling the request would exceed one or more service quotas for your account.

403AccessDeniedException

The request was denied because you don't have sufficient access to the specified resource.

404ResourceNotFoundException

The request failed because the specified resource wasn't found.

409ConflictException

The request failed because it conflicts with the current state of the specified resource.

429ThrottlingException

The request failed because you sent too many requests during a certain amount of time.

500InternalServerException

The request failed due to an unknown internal server error, exception, or failure.

Schemas

Request bodies

{ "filterBy": [ { "comparator": enum, "key": enum, "values": [ "string" ] } ], "maxResults": integer, "nextToken": "string", "sortBy": { "key": enum, "orderBy": enum }, "timeRange": enum }

Response bodies

{ "nextToken": "string", "records": [ { "accountId": "string", "automatedDiscoveryFreeTrialStartDate": "string", "freeTrialStartDate": "string", "usage": [ { "currency": enum, "estimatedCost": "string", "serviceLimit": { "isServiceLimited": boolean, "unit": enum, "value": integer }, "type": enum } ] } ], "timeRange": enum }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }
{ "message": "string" }

Properties

AccessDeniedException

Provides information about an error that occurred due to insufficient access to a specified resource.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

ConflictException

Provides information about an error that occurred due to a versioning conflict for a specified resource.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

Currency

The type of currency that the data for an Amazon Macie usage metric is reported in. Possible values are:

  • USD

GetUsageStatisticsRequest

Specifies criteria for filtering, sorting, and paginating the results of a query for quotas and aggregated usage data for one or more Amazon Macie accounts.

PropertyTypeRequiredDescription
filterBy

Array of type UsageStatisticsFilter

False

An array of objects, one for each condition to use to filter the query results. If you specify more than one condition, Amazon Macie uses an AND operator to join the conditions.

maxResults

integer

Format: int32

False

The maximum number of items to include in each page of the response.

nextToken

string

False

The nextToken string that specifies which page of results to return in a paginated response.

sortBy

UsageStatisticsSortBy

False

The criteria to use to sort the query results.

timeRange

TimeRange

False

The inclusive time period to query usage data for. Valid values are: MONTH_TO_DATE, for the current calendar month to date; and, PAST_30_DAYS, for the preceding 30 days. If you don't specify a value, Amazon Macie provides usage data for the preceding 30 days.

GetUsageStatisticsResponse

Provides the results of a query that retrieved quotas and aggregated usage data for one or more Amazon Macie accounts.

PropertyTypeRequiredDescription
nextToken

string

False

The string to use in a subsequent request to get the next page of results in a paginated response. This value is null if there are no additional pages.

records

Array of type UsageRecord

False

An array of objects that contains the results of the query. Each object contains the data for an account that matches the filter criteria specified in the request.

timeRange

TimeRange

False

The inclusive time period that the usage data applies to. Possible values are: MONTH_TO_DATE, for the current calendar month to date; and, PAST_30_DAYS, for the preceding 30 days.

InternalServerException

Provides information about an error that occurred due to an unknown internal server error, exception, or failure.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

ResourceNotFoundException

Provides information about an error that occurred because a specified resource wasn't found.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

ServiceLimit

Specifies a current quota for an Amazon Macie account.

PropertyTypeRequiredDescription
isServiceLimited

boolean

False

Specifies whether the account has met the quota that corresponds to the metric specified by the UsageByAccount.type field in the response.

unit

string

Values: TERABYTES

False

The unit of measurement for the value specified by the value field.

value

integer

Format: int64

False

The value for the metric specified by the UsageByAccount.type field in the response.

ServiceQuotaExceededException

Provides information about an error that occurred due to one or more service quotas for an account.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

ThrottlingException

Provides information about an error that occurred because too many requests were sent during a certain amount of time.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

TimeRange

An inclusive time period that Amazon Macie usage data applies to. Possible values are:

  • MONTH_TO_DATE

  • PAST_30_DAYS

UsageByAccount

Provides data for a specific usage metric and the corresponding quota for an Amazon Macie account.

PropertyTypeRequiredDescription
currency

Currency

False

The type of currency that the value for the metric (estimatedCost) is reported in.

estimatedCost

string

False

The estimated value for the metric.

serviceLimit

ServiceLimit

False

The current value for the quota that corresponds to the metric specified by the type field.

type

UsageType

False

The name of the metric. Possible values are: AUTOMATED_OBJECT_MONITORING, to monitor S3 objects for automated sensitive data discovery; AUTOMATED_SENSITIVE_DATA_DISCOVERY, to analyze S3 objects for automated sensitive data discovery; DATA_INVENTORY_EVALUATION, to monitor S3 buckets; and, SENSITIVE_DATA_DISCOVERY, to run classification jobs.

UsageRecord

Provides quota and aggregated usage data for an Amazon Macie account.

PropertyTypeRequiredDescription
accountId

string

False

The unique identifier for the AWS account that the data applies to.

automatedDiscoveryFreeTrialStartDate

string

Format: date-time

False

The date and time, in UTC and extended ISO 8601 format, when the free trial of automated sensitive data discovery started for the account. This value is null if automated sensitive data discovery hasn't been enabled for the account.

freeTrialStartDate

string

Format: date-time

False

The date and time, in UTC and extended ISO 8601 format, when the Amazon Macie free trial started for the account.

usage

Array of type UsageByAccount

False

An array of objects that contains usage data and quotas for the account. Each object contains the data for a specific usage metric and the corresponding quota.

UsageStatisticsFilter

Specifies a condition for filtering the results of a query for quota and usage data for one or more Amazon Macie accounts.

PropertyTypeRequiredDescription
comparator

UsageStatisticsFilterComparator

False

The operator to use in the condition. If the value for the key property is accountId, this value must be CONTAINS. If the value for the key property is any other supported field, this value can be EQ, GT, GTE, LT, LTE, or NE.

key

UsageStatisticsFilterKey

False

The field to use in the condition.

values

Array of type string

False

An array that lists values to use in the condition, based on the value for the field specified by the key property. If the value for the key property is accountId, this array can specify multiple values. Otherwise, this array can specify only one value.

Valid values for each supported field are:

  • accountId - The unique identifier for an AWS account.

  • freeTrialStartDate - The date and time, in UTC and extended ISO 8601 format, when the Amazon Macie free trial started for an account.

  • serviceLimit - A Boolean (true or false) value that indicates whether an account has reached its monthly quota.

  • total - A string that represents the current estimated cost for an account.

UsageStatisticsFilterComparator

The operator to use in a condition that filters the results of a query for Amazon Macie account quotas and usage data. Valid values are:

  • GT

  • GTE

  • LT

  • LTE

  • EQ

  • NE

  • CONTAINS

UsageStatisticsFilterKey

The field to use in a condition that filters the results of a query for Amazon Macie account quotas and usage data. Valid values are:

  • accountId

  • serviceLimit

  • freeTrialStartDate

  • total

UsageStatisticsSortBy

Specifies criteria for sorting the results of a query for Amazon Macie account quotas and usage data.

PropertyTypeRequiredDescription
key

UsageStatisticsSortKey

False

The field to sort the results by.

orderBy

string

Values: ASC | DESC

False

The sort order to apply to the results, based on the value for the field specified by the key property. Valid values are: ASC, sort the results in ascending order; and, DESC, sort the results in descending order.

UsageStatisticsSortKey

The field to use to sort the results of a query for Amazon Macie account quotas and usage data. Valid values are:

  • accountId

  • total

  • serviceLimitValue

  • freeTrialStartDate

UsageType

The name of an Amazon Macie usage metric for an account. Possible values are:

  • DATA_INVENTORY_EVALUATION

  • SENSITIVE_DATA_DISCOVERY

  • AUTOMATED_SENSITIVE_DATA_DISCOVERY

  • AUTOMATED_OBJECT_MONITORING

ValidationException

Provides information about an error that occurred due to a syntax error in a request.

PropertyTypeRequiredDescription
message

string

False

The explanation of the error that occurred.

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

GetUsageStatistics