Licensing and payment requirements for Microsoft Teams APIs in Microsoft Graph

This article describes the licensing and payment requirements for Microsoft Teams APIs.

Some APIs provide the option to choose a licensing and payment model via the model query parameter; others only support one model or do not support a licensing and payment model. The following licensing models are available:

model=A requirements

model=A is restricted to applications performing a security or compliance function. For details, see the API Terms for Security & Compliance Applications section of the product terms for Microsoft Azure Services.

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications Message sender 800 messages per user per month per app $0.00075 per message Seeded capacity is shared with conversationMember change notifications
conversationMember change notifications Any user in the tenant 800 notifications per user per month per app $0.00075 per notification Seeded capacity is shared with chatMessage change notifications
Get messages across all chats for user Named user 1600 messages per user per month per app $0.00075 per message The named user is the user identified in the GET request URL. Minimum charge of 1 message per API request. Seeded capacity is shared with channel export.
Get messages across all channels Any team member 1600 messages per user per month per app $0.00075 per message Minimum charge of 1 message per API request. Seeded capacity is shared with chat export.
Updating a chatMessage's policyViolation Message sender 800 messages per user per month per app $0.00075 per message

model=B requirements

model=B is restricted to applications that do not perform a security or compliance function. For details, see the API Terms for Security & Compliance Applications section of the product terms for Microsoft Azure Services.

Note: model=B starting July 5, 2022, billing events for these APIs will reach general availability.

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications N/A None $0.00075 per message
conversationMember change notifications N/A None $0.00075 per notification
Get messages across all chats for user N/A None $0.00075 per message Minimum charge of 1 message per API request.
Get messages across all channels N/A None $0.00075 per message Minimum charge of 1 message per API request.

Evaluation mode (default) requirements

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications N/A 500 messages per month per app N/A
conversationMember change notifications N/A 500 messages per month per app N/A
Get messages across all chats for user N/A 500 messages per month per app N/A Minimum charge of 1 message per API request.
Get messages across all channels N/A 500 messages per month per app N/A Minimum charge of 1 message per API request.
Updating a chatMessage's policyViolation N/A 500 messages per month per app N/A

In evaluation mode, seeded capacity is shared across all APIs. When seeded capacity is exceeded, API calls with licensing and payment requirements will fail with a 402 error code, and subscriptions with licensing and payment requirements will not send change notifications.

Error type Status code Error message
E5 license requirement not met 402 (Payment Required) User '{userId}' needs a valid license to access this API., Tenant {tenantId} needs a valid license to access this API.
Model B is not supported for Patch API 402 (Payment Required) Query parameter 'model' does not support value 'B' for this API. Use billing model 'A'.
Evaluation capacity exceeded 402 (Payment Required) Evaluation mode capacity has been exceeded. Use a valid billing model.

Note: A successful API call does not mean that the proper licensing is in place. Not all license violations can be detected, and grace periods might be granted in some cases.

Required licenses for model=A

The user will need a license that supports the Microsoft Communications DLP service plan, such as one of these supported licenses. Which user needs the license varies by API; for details, see model=A requirements.

Guest users are exempt from these licensing requirements. Similarly, messages sent from outside the tenant (federated chat) are exempt. Consumption meters still apply.

It is the responsibility of the tenant owner (not the app owner) to ensure users are properly licensed. Admins can use the Information protection license report in Teams admin center to see which users don't have a supported license.

Many supported licenses offer free trials. Office 365 E5 for instance has a Free trial link underneath the Buy button.

You can get a free Microsoft 365 E5 developer sandbox subscription with 25 user licenses through the Microsoft 365 Developer Program.

Improper licensing and evaluation mode seeded capacity exceeded

In the event that improper licensing is detected, the API call will fail and data will not be returned. Specifically, for most APIs, attempting to GET messages for an unlicensed user will result in a 402 error code. For change notifications, messages sent by unlicensed users will not generate a change notification. Similarly, API calls and change notifications used in evaluation mode in excess of the seeded capacity will fail.

Note: A successful API call does not mean that the proper licensing is in place. Not all license violations can be detected, and grace periods might be granted in some cases. Similarly, API success in evaluation mode does not guarantee the call is within seeded capacity as grace periods may be granted in some cases.

Seeded capacity

Seeded capacity is the amount of capacity that an app can use before a consumption meter is charged. Capacity is pooled at the tenant level -- the seeded capacity for all users in the tenant is added up and compared against the app's usage in the tenant. Seeded capacity is per app per tenant -- apps won't run out of seeded capacity if another app runs out.

The seeded capacity differs by API, see model=A requirements and model=B requirements

Price for additional use

In the future, Microsoft will charge a fee for usage over the seeded capacity. You will also be able to associate an Azure subscription to your application registration. The organization that owns the app registration is responsible for the payment, which for multitenant apps may be different from the organization that runs the app.