SDK for PHP 3.x

AWS Free Tier 2023-09-07

Client: Aws\FreeTier\FreeTierClient
Service ID: freetier
Version: 2023-09-07

This page describes the parameters and results for the operations of the AWS Free Tier (2023-09-07), and shows how to use the Aws\FreeTier\FreeTierClient object to call the described operations. This documentation is specific to the 2023-09-07 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

GetAccountActivity ( array $params = [] )
Returns a specific activity record that is available to the customer.
GetAccountPlanState ( array $params = [] )
This returns all of the information related to the state of the account plan related to Free Tier.
GetFreeTierUsage ( array $params = [] )
Returns a list of all Free Tier usage objects that match your filters.
ListAccountActivities ( array $params = [] )
Returns a list of activities that are available.
UpgradeAccountPlan ( array $params = [] )
The account plan type for the Amazon Web Services account.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetFreeTierUsage
ListAccountActivities

Operations

GetAccountActivity 

$result = $client->getAccountActivity([/* ... */]);
$promise = $client->getAccountActivityAsync([/* ... */]);

Returns a specific activity record that is available to the customer.

Parameter Syntax

$result = $client->getAccountActivity([
    'activityId' => '<string>', // REQUIRED
    'languageCode' => 'en-US|en-GB|id-ID|de-DE|es-ES|fr-FR|ja-JP|it-IT|pt-PT|ko-KR|zh-CN|zh-TW|tr-TR',
]);

Parameter Details

Members
activityId
Required: Yes
Type: string

A unique identifier that identifies the activity.

languageCode
Type: string

The language code used to return translated title and description fields.

Result Syntax

[
    'activityId' => '<string>',
    'completedAt' => <DateTime>,
    'description' => '<string>',
    'estimatedTimeToCompleteInMinutes' => <integer>,
    'expiresAt' => <DateTime>,
    'instructionsUrl' => '<string>',
    'reward' => [
        'credit' => [
            'amount' => <float>,
            'unit' => 'USD',
        ],
    ],
    'startedAt' => <DateTime>,
    'status' => 'NOT_STARTED|IN_PROGRESS|COMPLETED|EXPIRING',
    'title' => '<string>',
]

Result Details

Members
activityId
Required: Yes
Type: string

A unique identifier that identifies the activity.

completedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the activity is completed. This field appears only for activities in the COMPLETED state.

description
Required: Yes
Type: string

Provides detailed information about the activity and its expected outcomes.

estimatedTimeToCompleteInMinutes
Type: int

The estimated time to complete the activity. This is the duration in minutes.

expiresAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The time by which the activity must be completed to receive a reward.

instructionsUrl
Required: Yes
Type: string

The URL resource that provides guidance on activity requirements and completion.

reward
Required: Yes
Type: ActivityReward structure

A reward granted upon activity completion.

startedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp when the activity started. This field appears only for activities in the IN_PROGRESS or COMPLETED states.

status
Required: Yes
Type: string

The current activity status.

title
Required: Yes
Type: string

A short activity title.

Errors

InternalServerException:

An unexpected error occurred during the processing of your request.

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

ResourceNotFoundException:

This exception is thrown when the requested resource cannot be found.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: Fetching an Account activity by id 
$result = $client->getAccountActivity([
    'activityId' => 'd622f48bf4014286a2686ab10cacfb2e',
    'languageCode' => 'en-US',
]);

Result syntax:

[
    'activityId' => 'd622f48bf4014286a2686ab10cacfb2e',
    'completedAt' => ,
    'description' => 'Set up three notifications: one for your costs reach ...',
    'estimatedTimeToCompleteInMinutes' => 15,
    'expiresAt' => ,
    'instructionsUrl' => 'https://catalog.us-east-1.prod.workshops.aws/workshops/2a5fc82d-2b5f-4105-83c2-91a1b4d7abfe/en-US/2-foundation/lab1-create',
    'reward' => [
        'credit' => [
            'amount' => 20,
            'unit' => 'USD',
        ],
    ],
    'startedAt' => ,
    'status' => 'COMPLETED',
    'title' => 'Configure Your Access in the AWS Identity and Access Management (IAM) center',
]

GetAccountPlanState 

$result = $client->getAccountPlanState([/* ... */]);
$promise = $client->getAccountPlanStateAsync([/* ... */]);

This returns all of the information related to the state of the account plan related to Free Tier.

Parameter Syntax

$result = $client->getAccountPlanState([
]);

Parameter Details

Members

Result Syntax

[
    'accountId' => '<string>',
    'accountPlanExpirationDate' => <DateTime>,
    'accountPlanRemainingCredits' => [
        'amount' => <float>,
        'unit' => 'USD',
    ],
    'accountPlanStatus' => 'NOT_STARTED|ACTIVE|EXPIRED',
    'accountPlanType' => 'FREE|PAID',
]

Result Details

Members
accountId
Required: Yes
Type: string

A unique identifier that identifies the account.

accountPlanExpirationDate
Type: timestamp (string|DateTime or anything parsable by strtotime)

The timestamp for when the current account plan expires.

accountPlanRemainingCredits
Type: MonetaryAmount structure

The amount of credits remaining for the account.

accountPlanStatus
Required: Yes
Type: string

The current status for the account plan.

accountPlanType
Required: Yes
Type: string

The plan type for the account.

Errors

InternalServerException:

An unexpected error occurred during the processing of your request.

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

AccessDeniedException:

You don't have sufficient access to perform this action.

ResourceNotFoundException:

This exception is thrown when the requested resource cannot be found.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: Fetching account plan state by id 
$result = $client->getAccountPlanState([
]);

Result syntax:

[
    'accountId' => '111122223333',
    'accountPlanExpirationDate' => ,
    'accountPlanRemainingCredits' => [
        'amount' => 25,
        'unit' => 'USD',
    ],
    'accountPlanStatus' => 'ACTIVE',
    'accountPlanType' => 'FREE',
]
Example 2: Attempt to fetch account plan state by id with insufficient permissions 
$result = $client->getAccountPlanState([
]);
Example 3: Internal service error 
$result = $client->getAccountPlanState([
]);
Example 4: Attempt to fetch plan state by id for an account without account plan 
$result = $client->getAccountPlanState([
]);
Example 5: Request rate exceeds limits 
$result = $client->getAccountPlanState([
]);

GetFreeTierUsage 

$result = $client->getFreeTierUsage([/* ... */]);
$promise = $client->getFreeTierUsageAsync([/* ... */]);

Returns a list of all Free Tier usage objects that match your filters.

Parameter Syntax

$result = $client->getFreeTierUsage([
    'filter' => [
        'And' => [
            [...], // RECURSIVE
            // ...
        ],
        'Dimensions' => [
            'Key' => 'SERVICE|OPERATION|USAGE_TYPE|REGION|FREE_TIER_TYPE|DESCRIPTION|USAGE_PERCENTAGE', // REQUIRED
            'MatchOptions' => ['<string>', ...], // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        'Not' => [...], // RECURSIVE
        'Or' => [
            [...], // RECURSIVE
            // ...
        ],
    ],
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
filter
Type: Expression structure

An expression that specifies the conditions that you want each FreeTierUsage object to meet.

maxResults
Type: int

The maximum number of results to return in the response. MaxResults means that there can be up to the specified number of values, but there might be fewer results based on your filters.

nextToken
Type: string

The pagination token that indicates the next set of results to retrieve.

Result Syntax

[
    'freeTierUsages' => [
        [
            'actualUsageAmount' => <float>,
            'description' => '<string>',
            'forecastedUsageAmount' => <float>,
            'freeTierType' => '<string>',
            'limit' => <float>,
            'operation' => '<string>',
            'region' => '<string>',
            'service' => '<string>',
            'unit' => '<string>',
            'usageType' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
freeTierUsages
Required: Yes
Type: Array of FreeTierUsage structures

The list of Free Tier usage objects that meet your filter expression.

nextToken
Type: string

The pagination token that indicates the next set of results to retrieve.

Errors

InternalServerException:

An unexpected error occurred during the processing of your request.

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

ThrottlingException:

The request was denied due to request throttling.

ListAccountActivities 

$result = $client->listAccountActivities([/* ... */]);
$promise = $client->listAccountActivitiesAsync([/* ... */]);

Returns a list of activities that are available. This operation supports pagination and filtering by status.

Parameter Syntax

$result = $client->listAccountActivities([
    'filterActivityStatuses' => ['<string>', ...],
    'languageCode' => 'en-US|en-GB|id-ID|de-DE|es-ES|fr-FR|ja-JP|it-IT|pt-PT|ko-KR|zh-CN|zh-TW|tr-TR',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
filterActivityStatuses
Type: Array of strings

The activity status filter. This field can be used to filter the response by activities status.

languageCode
Type: string

The language code used to return translated titles.

maxResults
Type: int

The maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output.

nextToken
Type: string

A token from a previous paginated response. If this is specified, the response includes records beginning from this token (inclusive), up to the number specified by maxResults.

Result Syntax

[
    'activities' => [
        [
            'activityId' => '<string>',
            'reward' => [
                'credit' => [
                    'amount' => <float>,
                    'unit' => 'USD',
                ],
            ],
            'status' => 'NOT_STARTED|IN_PROGRESS|COMPLETED|EXPIRING',
            'title' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
activities
Required: Yes
Type: Array of ActivitySummary structures

A brief information about the activities.

nextToken
Type: string

The token to include in another request to get the next page of items. This value is null when there are no more items to return.

Errors

InternalServerException:

An unexpected error occurred during the processing of your request.

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: Fetching a page of completed activities 
$result = $client->listAccountActivities([
    'filterActivityStatuses' => [
        'COMPLETED',
    ],
    'languageCode' => 'en-US',
    'maxResults' => 1,
]);

Result syntax:

[
    'activities' => [
        [
            'activityId' => 'd622f48bf4014286a2686ab10cacfb2e',
            'reward' => [
                'credit' => [
                    'amount' => 20,
                    'unit' => 'USD',
                ],
            ],
            'status' => 'COMPLETED',
            'title' => 'Configure Your Access in the AWS Identity and Access Management (IAM) center',
        ],
    ],
    'nextToken' => 'a95f3d9e7710c6ca8ba4f640b40bbc40',
]

UpgradeAccountPlan 

$result = $client->upgradeAccountPlan([/* ... */]);
$promise = $client->upgradeAccountPlanAsync([/* ... */]);

The account plan type for the Amazon Web Services account.

Parameter Syntax

$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'FREE|PAID', // REQUIRED
]);

Parameter Details

Members
accountPlanType
Required: Yes
Type: string

The target account plan type. This makes it explicit about the change and latest value of the accountPlanType.

Result Syntax

[
    'accountId' => '<string>',
    'accountPlanStatus' => 'NOT_STARTED|ACTIVE|EXPIRED',
    'accountPlanType' => 'FREE|PAID',
]

Result Details

Members
accountId
Required: Yes
Type: string

A unique identifier that identifies the account.

accountPlanStatus
Required: Yes
Type: string

This indicates the latest state of the account plan within its lifecycle.

accountPlanType
Required: Yes
Type: string

The type of plan for the account.

Errors

InternalServerException:

An unexpected error occurred during the processing of your request.

ValidationException:

The input fails to satisfy the constraints specified by an Amazon Web Services service.

AccessDeniedException:

You don't have sufficient access to perform this action.

ResourceNotFoundException:

This exception is thrown when the requested resource cannot be found.

ThrottlingException:

The request was denied due to request throttling.

Examples

Example 1: Upgrading an account plan to PAID 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'PAID',
]);

Result syntax:

[
    'accountId' => '111122223333',
    'accountPlanStatus' => 'NOT_STARTED',
    'accountPlanType' => 'PAID',
]
Example 2: Attempt to upgrade an account with insufficient permissions 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'PAID',
]);
Example 3: Attempt to downgrade an account from PAID to FREE 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'FREE',
]);
Example 4: Internal service error 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'PAID',
]);
Example 5: Attempt to upgrade a non-existent account plan 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'PAID',
]);
Example 6: Request rate exceeds limits 
$result = $client->upgradeAccountPlan([
    'accountPlanType' => 'PAID',
]);

Shapes

AccessDeniedException

Description

You don't have sufficient access to perform this action.

Members
message
Required: Yes
Type: string

ActivityReward

Description

The summary of the rewards granted as a result of activities completed.

Members
credit
Type: MonetaryAmount structure

The credits gained by activity rewards.

ActivitySummary

Description

The summary of activities.

Members
activityId
Required: Yes
Type: string

A unique identifier that identifies the activity.

reward
Required: Yes
Type: ActivityReward structure

The reward for the activity.

status
Required: Yes
Type: string

The current status of the activity.

title
Required: Yes
Type: string

The title of the activity.

DimensionValues

Description

Contains the specifications for the filters to use for your request.

Members
Key
Required: Yes
Type: string

The name of the dimension that you want to filter on.

MatchOptions
Required: Yes
Type: Array of strings

The match options that you can use to filter your results. You can specify only one of these values in the array.

Values
Required: Yes
Type: Array of strings

The metadata values you can specify to filter upon, so that the results all match at least one of the specified values.

Expression

Description

Use Expression to filter in the GetFreeTierUsage API operation.

You can use the following patterns:

  • Simple dimension values (Dimensions root operator)

  • Complex expressions with logical operators (AND, NOT, and OR root operators).

For simple dimension values, you can set the dimension name, values, and match type for the filters that you plan to use.

Example for simple dimension values

You can filter to match exactly for REGION==us-east-1 OR REGION==us-west-1.

The corresponding Expression appears like the following: { "Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] } }

As shown in the previous example, lists of dimension values are combined with OR when you apply the filter.

For complex expressions with logical operators, you can have nested expressions to use the logical operators and specify advanced filtering.

Example for complex expressions with logical operators

You can filter by ((REGION == us-east-1 OR REGION == us-west-1) OR (SERVICE CONTAINS AWSLambda)) AND (USAGE_TYPE !CONTAINS DataTransfer).

The corresponding Expression appears like the following: { "And": [ {"Or": [ {"Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] }}, {"Dimensions": { "Key": "SERVICE", "Values": ["AWSLambda"], "MatchOptions": ["CONTAINS"] } } ]}, {"Not": {"Dimensions": { "Key": "USAGE_TYPE", "Values": ["DataTransfer"], "MatchOptions": ["CONTAINS"] }}} ] }

In the following Contents, you must specify exactly one of the following root operators.

Members
And
Type: Array of Expression structures

Return results that match all Expressions that you specified in the array.

Dimensions
Type: DimensionValues structure

The specific dimension, values, and match type to filter objects with.

Not
Type: Expression structure

Return results that don’t match the Expression that you specified.

Or
Type: Array of Expression structures

Return results that match any of the Expressions that you specified. in the array.

FreeTierUsage

Description

Consists of a Amazon Web Services Free Tier offer’s metadata and your data usage for the offer.

Members
actualUsageAmount
Type: double

Describes the actual usage accrued month-to-day (MTD) that you've used so far.

description
Type: string

The description of the Free Tier offer.

forecastedUsageAmount
Type: double

Describes the forecasted usage by the month that you're expected to use.

freeTierType
Type: string

Describes the type of the Free Tier offer. For example, the offer can be "12 Months Free", "Always Free", and "Free Trial".

limit
Type: double

Describes the maximum usage allowed in Free Tier.

operation
Type: string

Describes usageType more granularly with the specific Amazon Web Services service API operation. For example, this can be the RunInstances API operation for Amazon Elastic Compute Cloud.

region
Type: string

Describes the Amazon Web Services Region for which this offer is applicable

service
Type: string

The name of the Amazon Web Services service providing the Free Tier offer. For example, this can be Amazon Elastic Compute Cloud.

unit
Type: string

Describes the unit of the usageType, such as Hrs.

usageType
Type: string

Describes the usage details of the offer. For example, this might be Global-BoxUsage:freetrial.

InternalServerException

Description

An unexpected error occurred during the processing of your request.

Members
message
Required: Yes
Type: string

MonetaryAmount

Description

The monetary amount of the credit.

Members
amount
Required: Yes
Type: double

The aggregated monetary amount of credits earned.

unit
Required: Yes
Type: string

The unit that the monetary amount is given in.

ResourceNotFoundException

Description

This exception is thrown when the requested resource cannot be found.

Members
message
Required: Yes
Type: string

ThrottlingException

Description

The request was denied due to request throttling.

Members
message
Required: Yes
Type: string

ValidationException

Description

The input fails to satisfy the constraints specified by an Amazon Web Services service.

Members
message
Required: Yes
Type: string