Create, configure, and test usage plans with the API Gateway console

Before creating a usage plan, make sure that you've set up the desired API keys. For more information, see Set up API keys using the API Gateway console.

This section describes how to create and use a usage plan by using the API Gateway console.

Migrate your API to default usage plans (if needed)

If you started to use API Gateway after the usage plans feature was rolled out on August 11, 2016, you will automatically have usage plans enabled for you in all supported Regions.

If you started to use API Gateway before that date, you might need to migrate to default usage plans. You'll be prompted with the Enable Usage Plans option before using usage plans for the first time in the selected Region. When you enable this option, you have default usage plans created for every unique API stage that's associated with existing API keys. In the default usage plan, no throttle or quota limits are set initially, and the associations between the API keys and API stages are copied to the usage plans. The API behaves the same as before. However, you must use the UsagePlan apiStages property to associate specified API stage values (apiId and stage) with included API keys (via UsagePlanKey), instead of using the ApiKey stageKeys property.

To check whether you've already migrated to default usage plans, use the get-account CLI command. In the command output, the features list includes an entry of "UsagePlans" when usage plans are enabled.

You can also migrate your APIs to default usage plans by using the AWS CLI as follows:

To migrate to default usage plans using the AWS CLI

1. Call this CLI command: update-account.

2. For the cli-input-json parameter, use the following JSON:

   [
       {
           "op": "add",
           "path": "/features",
           "value": "UsagePlans"
       }
   ]

Create a usage plan

The following procedure describes how to create a usage plan.

Old REST API console

Note

We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.

To create a usage plan

1. In the Amazon API Gateway main navigation pane, choose Usage Plans, and then choose Create.

2. Under Create Usage Plan, do the following:

   1. For Name, enter a name for your plan (for example, Plan_A).

   2. For Description, enter a description for your plan.

   3. Select Enable throttling, and set Rate (for example, 100) and Burst (for example, 200).

   4. Choose Enable quota, and set specify a value (for example, 5000) for a selected time interval (for example, Month).

   5. Choose Next.

   

3. To add a stage to the plan, do the following in the Associated API Stages pane:

   1. Choose Add API Stage.

   2. Choose an API (for example, PetStore) from the API drop-down list.

   3. Choose a stage (for example, Stage_1) from the Stage drop-down list.

   4. Choose the checkmark icon to save.

   

4. To configure method throttling, do the following:

   1. Choose Configure Method Throttling.

   2. Choose Add Resource/Method.

   3. Choose the resource from the Resource drop-down menu.

   4. Choose the method from the Method drop-down menu.

   5. Set Rate (requests per second) (for example, 100) and Burst (for example, 200).

   6. Choose the checkmark icon to save.

   7. Choose Close.

5. To add a key to the plan, do the following in the API Keys tab:

   1. To use an existing key, choose Add API Key to Usage Plan.

   2. For Name, enter a name for the key you want to add (for example, MyFirstKey).

   3. Choose the checkmark icon to save.

   4. As needed, repeat the preceding steps to add other existing API keys to this usage plan.

   

   Note

   Alternatively, to create a new API key and add it to the usage plan, choose Create API Key and add to Usage Plan and follow the instructions.

   Note

   An API key can be associated with more than one usage plan. A usage plan can be associated with more than one stage. However, a given API key can only be associated with one usage plan for each stage of your API.

6. To finish creating the usage plan, choose Done.

7. If you want to add more API stages to the usage plan, choose Add API Stage to repeat the preceding steps.

New REST API console

To create a usage plan

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. In the API Gateway main navigation pane, choose Usage plans, and then choose Create usage plan.

   

3. For Name, enter a name.

4. (Optional) For Description, enter a description.

5. By default, usage plans enable throttling. Enter a Rate and a Burst for your usage plan. Choose Throttling to turn off throttling.

6. By default, usage plans enable a quota for a time period. For Requests, enter the total number of requests that a user can make in the time period of your usage plan. Choose Quota to turn off the quota.

7. Choose Create usage plan.

To add a stage to the usage plan

1. Select your usage plan.

2. Under the Associated stages tab, choose Add stage.

   

3. For API, select an API.

4. For Stage, select a stage.

5. (Optional) To turn on method-level throttling, do the following:

   1. Choose Method-level throttling, and then choose Add method.

   2. For Resource, select a resource from your API.

   3. For Method, select a method from your API.

   4. Enter a Rate and a Burst for your usage plan.

6. Choose Add to usage plan.

To add a key to the usage plan

1. Under the Associated API keys tab, choose Add API key.

   

2. 1. To associate an existing key to your usage plan, select Add existing key, and then select your existing key from the dropdown menu.

   2. To create a new API key, select Create and add new key, and then create a new key. For more information on how to create a new key, see Create an API key.

3. Choose Add API key.

Test a usage plan

To test the usage plan, you can use an AWS SDK, AWS CLI, or a REST API client like Postman. For an example of using Postman to test the usage plan, see Test usage plans.

Maintain a usage plan

Maintaining a usage plan involves monitoring the used and remaining quotas over a given time period and, if needed, extending the remaining quotas by a specified amount. The following procedures describe how to monitor quotas.

Old REST API console

Note

We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.

To monitor used and remaining quotas

1. In the API Gateway main navigation pane, choose Usage Plans.

2. Choose a usage plan from the list of usage plans.

3. From within the specified plan, choose API Keys.

4. Choose an API key, and then choose Usage to view Subscriber's Traffic from the plan you're monitoring.

5. Optionally, choose Export, choose a From date and a To date, choose JSON or CSV for the exported data format, and then choose Export.

   The following example shows an exported file.

   {
     "thisPeriod": {
       "px1KW6...qBazOJH": [
         [
           0,
           5000
         ],
         [
           0,
           5000
         ],
         [
           0,
           10
         ]
       ]
     },
     "startDate": "2016-08-01",
     "endDate": "2016-08-03"
   }

   The usage data in the example shows the daily usage data for an API client, as identified by the API key (px1KW6...qBazOJH), between August 1, 2016 and August 3, 2016. Each daily usage data shows used and remaining quotas. In this example, the subscriber hasn't used any allotted quotas yet, and the API owner or administrator has reduced the remaining quota from 5000 to 10 on the third day.

New REST API console

To monitor used and remaining quotas

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. In the API Gateway main navigation pane, choose Usage plans.

3. Select a usage plan.

4. Choose the Associated API keys tab to see the number of request remaining for the time period for each key.

5. (Optional) Choose Export usage data, and then choose a From date and a To date. Then choose JSON or CSV for the exported data format, and then choose Export.

   The following example shows an exported file.

   {
     "thisPeriod": {
       "px1KW6...qBazOJH": [
         [
           0,
           5000
         ],
         [
           0,
           5000
         ],
         [
           0,
           10
         ]
       ]
     },
     "startDate": "2016-08-01",
     "endDate": "2016-08-03"
   }

   The usage data in the example shows the daily usage data for an API client, as identified by the API key (px1KW6...qBazOJH), between August 1, 2016 and August 3, 2016. Each daily usage data shows used and remaining quotas. In this example, the subscriber hasn't used any allotted quotas yet, and the API owner or administrator has reduced the remaining quota from 5000 to 10 on the third day.

The following procedures describe how to modify quotas.

Old REST API console

Note

We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.

To extend the remaining quotas

1. Repeat steps 1–3 of the previous procedure.

2. In the usage plan pane, choose Extension from the usage plan window.

3. Enter a number for the Remaining request quotas.

4. Choose Save.

New REST API console

To extend the remaining quotas

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. In the API Gateway main navigation pane, choose Usage plans.

3. Select a usage plan.

4. Choose the Associated API keys tab to see the number of request remaining for the time period for each key.

5. Select an API key, and then choose Grant usage extension.

6. Enter a number for the Remaining requests quota. You can increase the renaming requests or decrease the remaining requests for the time period of your usage plan.

7. Choose Update quota.