Payment models and licensing requirements for Microsoft Teams APIs
This article describes the payment models and licensing requirements for Microsoft Teams APIs in Microsoft Graph. For a high-level description of metered APIs and services in Microsoft Graph, see Overview of metered APIs and services in Microsoft Graph.
Some APIs provide the option to choose a licensing and payment model via the model query parameter; others only support one model or don't support a licensing and payment model.
The following table lists the APIs and change notification resources that currently support payment models.
APIs or change notification resources |
Payment models |
|---|---|
Change notification resources:
|
A, B |
Change notification resources:
|
B |
| Export APIs: | A, B |
PATCH APIs, when updating the policyViolation property: |
A |
| Teams meeting APIs: | No model parameter |
Note
To set up an active Azure subscription for your application for billing purposes, see Enable metered Microsoft 365 APIs and services. For more information, see Payment and billing updates.
Payment models
The following payment models are available:
model=Ais restricted to applications performing a security or compliance function, and requires a supported license.model=Bis restricted to applications that don't perform a security or compliance function. There are no licensing requirements formodel=B.Evaluation mode (default) enables access to APIs with limited usage per requesting application for evaluation purposes. Change notifications aren't sent if the limit is exceeded.
Note
To add or change a payment model for a subscribed resource of a change notification, you must create a new change notification subscription with the new payment model; updating an existing change notification does not work.
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.
The following APIs support the model=A parameter.
APIs or change notification resources |
Who needs a license | Seeded capacity | Price for additional use | Notes |
|---|---|---|---|---|
Change notification resources:
|
Message sender | (800 messages × supported licenses with DLP enabled) per month per app | $0.00075 per message | Seeded capacity is shared with conversationMember change notifications |
Change notification resources:
|
Any user in the tenant | (800 notifications × supported licenses with DLP enabled) per month per app | $0.00075 per notification | Seeded capacity is shared with chatMessage change notifications |
| APIs: | Named user | (1600 messages × supported licenses with DLP enabled) per month per app | $0.00075 per message | The named user is the user identified in the GET request URL. Requests that return an empty list are charged as one message. Seeded capacity is shared with channel export. |
| APIs: | Any team member | (1600 messages × supported licenses with DLP enabled) per month per app | $0.00075 per message | Requests that return an empty list are charged as one message. Seeded capacity is shared with chat export. |
APIs, when updating the policyViolation property: |
Message sender | (800 messages × supported licenses with DLP enabled) per month per app | $0.00075 per message |
Required licenses for model=A
The user needs 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's the responsibility of the tenant owner (not the app owner) to ensure that 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 under the Buy button.
You might qualify for one through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.
Note
The Microsoft Communications DLP service plan must be enabled before it can be licensed. You can manage licenses in the Microsoft Entra admin center or the Microsoft 365 admin center. You can also assign licenses to a group account by using Microsoft Graph Graph REST API and PowerShell SDK.
model=B requirements
model=B is restricted to applications that don't 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.
The following APIs support the model=B parameter.
APIs or change notification resources |
Seeded capacity | Price for use | Notes |
|---|---|---|---|
Change notification resources:
|
None | $0.00075 per message | |
Change notification resources:
|
None | $0.00075 per notification | |
Change notification resources:
|
None | $0.00075 per message | |
| APIs: | None | $0.00075 per message | Requests that return an empty list are charged as one message. |
| APIs: | None | $0.00075 per message | Requests that return an empty list are charged as one message. |
Evaluation mode (default) requirements
The following APIs support evaluation mode. The evaluation quota is enforced per app, per tenant, per month. The quota is reset at the beginning of each calendar month, and any unused amount doesn't get carried over to the next month.
APIs or change notification resources |
Evaluation quota | Price for additional use | Notes |
|---|---|---|---|
Change notification resources:
|
500 messages per month per tenant per app | N/A | |
Change notification resources:
|
500 messages per month per tenant per app | N/A | |
Change notification resources:
|
500 messages per month per app | N/A | |
| APIs: | 500 messages per month per tenant per app | N/A | Requests that return an empty list are charged as one message. |
| APIs: | 500 messages per month per tenant per app | N/A | Requests that return an empty list are charged as one message. |
APIs, when updating the policyViolation property: |
500 messages per month per tenant per app | N/A | |
| Teams meeting transcript APIs: | 600 minutes per month per tenant per app | N/A | |
| Teams meeting recording APIs: | 600 minutes per month per tenant per app | N/A |
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 compared against the app's usage in the tenant. Seeded capacity is per app per tenant—an app won't run out of seeded capacity if another app runs out. Seeded capacity is reset at the beginning of each calendar month, and any unused amount doesn't get carried over to the next month.
| Payment model | Use cases | Seeded capacity | License required | Azure subscription required |
|---|---|---|---|---|
model=A |
Security and Compliance | See model=A requirements |
Yes (Microsoft 365 E5 eligible license) | Yes |
model=B |
Backup and restore, migration, sentiment analysis, analytics and insights | None | No | Yes |
Seeded capacity isn't applicable for Teams meeting APIs. For details, see Payment requirements for Meeting APIs.
Payment requirements for meeting APIs
This section describes the payment requirements for Teams meeting transcript and recording APIs. These APIs don't support the model A and model B payment models and can be used by any application, regardless of the use case.
These APIs support an evaluation mode that apps can use without configuring Azure billing. The following table summarizes the evaluation mode behavior.
| Azure billing setup | Result |
|---|---|
| Not configured | Evaluation mode capacity is available for download. Beyond that, the API fails with error code 402 (Payment Required). |
| Configured | Unlimited meeting content is available for download and priced based on per minute of content, as described in the following table. Engineering RPS limits still apply. |
The following table lists the prices for using Teams meeting APIs, applicable to both beta and v1.0 endpoints.
| APIs | Seeded capacity | Price for use | Notes |
|---|---|---|---|
| Teams meeting recording APIs: | None | $0.003 per minute | The duration is rounded down to the nearest minute. |
| Teams meeting transcript APIs: | None | $0.0022 per minute | The duration is rounded down to the nearest minute. |
Payment and billing
If your applications are or will be using any of the aforementioned APIs or change notification resources, you must follow the steps described in Enable metered Microsoft 365 APIs and services to set up an active Azure subscription for billing purposes.
The organization that owns the app registration is responsible for the payment. The Azure subscription should also be active in the same tenant. For multitenant apps, the organization that registered the app might be different than the organization that runs the app.
Payment-related errors
If incorrect licensing is detected, the API call fails and data won't 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 won't generate a change notification.
API calls and change notifications used in evaluation mode in excess of the evaluation quota will fail.
| Error code | Scenario | Sample error message |
|---|---|---|
| 402 (Payment Required) | Missing an active Azure billing subscription | ...To call this API, the app must be associated with an Azure subscription, see https://aka.ms/teams-api-payment-requirements for details.... |
| 402 (Payment Required) | Passing model=A without a Microsoft E5 license or without DLP enabled |
...needs a valid license to access this API..., ...tenant needs a valid license to access this API... |
| 402 (Payment Required) | Calling Patch API passing model=B |
...query parameter 'model' does not support value 'B' for this API. Use billing model 'A'... |
| 402 (Payment Required) | Evaluation mode capacity exceeded |
...evaluation capacity for the month has exceeded. To continue beyond the evalution limits complete billing onboarding... |
Note
A successful API call does not mean that the required licensing is in place. Similarly, API success in evaluation model does not guarantee that the call is within seeded capacity.
View the costs billed for the metered Microsoft Teams APIs
This section describes how to monitor costs billed for the metered Microsoft Teams APIs.
A subscription owner, or anyone with appropriate RBAC (Roles Based Access Control) permissions, can use Cost Analysis to track metered API consumption, as follows:
- Sign in to the Azure portal at https://portal.azure.com.
- Go to Cost Management + Billing > Cost Management > Cost analysis.
- For the filter near the top, select Service name: Microsoft Graph Services.
- For the Group by dropdown menu near the right, select Meter.
This view offers a convenient way to observe API consumption per day over a period of time.
You can also use the pie charts near the bottom to further breakdown the costs for analysis, using the Resource and Meter filters.
For more information about cost management, see Cost Management + Billing documentation.
Monitor the number of messages billed for the metered Teams APIs
This section describes how to monitor the number of messages billed for the metered Teams APIs. Unlike with cost analysis, this allows you to analyze the usage of messages within the seeded capacity, not just those above the seeded capacity for billing, if applicable to the selected licensing models.
A subscription owner, or anyone with required RBAC (Roles Based Access Control) permissions, can set up a report, in CSV format, with the billing details for the entire subscription. You can export the report periodically (daily, weekly, monthly). For details, see Tutorial: Create and manage exported data.
Estimate the number of messages in your Teams
This section describes how to look up the number of messages in your Teams tenant. This can help you estimate the cost for using the metered APIs. If a message is retrieved through metered APIs multiple times, it's billed multiple times. Keep this in mind when you estimate the cost based on the number of messages in your Teams tenant. For example, if you called getAllMessages (without any filters) yesterday, and then call it again (without any filters) today, all messages from earlier than today will be billed twice. For this reason, when using metered APIs, we recommend that you use filters (for example, $top=10, $filter=lastModifiedDateTime gt 2019-03-17T07:13:28.000z) or change notifications to avoid retrieving the same message multiple times.
You can also call the getTeamsUserActivityUserDetail API, or you can use the Microsoft Teams Admin Center as follows:
Note: You must be either a Global Reader or Teams service admin to view the report in the Microsoft Teams Admin Center. For details, see Use Teams administrator roles to manage Teams.
- In the left pane, choose Analytics & reports > Usage reports.
- On the View reports tab, under Report, choose Teams user activity.
- Under Date range, select a range.
- Choose Run report.
Frequently asked questions
| Scenario | Details |
|---|---|
| Why was the number of messages billed higher than the number of messages in my Teams? | If your app is retrieving the same message multiple times, it is billed for multiple times. One way to avoid this is to use change notifications instead of export APIs. If you must use export APIs, make sure to use filters (for example, $filter=lastModifiedDateTime, $filter=from). |
| Did billing actually started on July 5? | Yes, we're onboarding partners in phases. For continued access, follow the instructions on Enable metered Microsoft 365 APIs and services to set up an active Azure subscription for billing purposes. |
| What should I expect after setting up an Azure subscription? | Billing is effective immediately. You can monitor the costs as described in the View the costs billed for the metered Microsoft Teams APIs section above. |
| Do I need to provide an Azure subscription if my application isn't calling metered APIs? | We recommend that you provide an Azure subscription because most scenarios use metered APIs. |
| What happens if no Azure subscription is provided? | * No payment-related errors occur if the application isn't calling metered APIs. * If no model parameter is passed, the evaluation model value is used by default. * If calling a metered API passing model=A, provide a Microsoft 365 E5 eligible license and Azure subscription. * If passing model=B when calling metered APIs, provide an active Azure subscription. |
| How do I create an Azure subscription? | The Azure subscription must be available in the same tenant where the app is registered. Customers with MCA or EA agreements can get a subscription from their existing account. Is also possible to create a PAYG subscription using a credit card or pay by check or wire transfer. For details, see Enable metered Microsoft 365 APIs and services and cost management and billing. |
| Who is responsible for the payment in the case of multitenant apps? | The organization that owns the app registration. |
| Is possible to differentiate billing from multitenant or single tenant app? | Yes, this information must be provided as part of Azure billing details. |
| Is there a charge when no message is returned using any model? | To discourage frequent polling, API requests that return an empty list of messages will be charged one message. In the case of evaluation model, the call counts toward the 500 messages per month per app allowed. |
| Where can I monitor the cost and billing? | A subscription owner, or anyone with appropriate RBAC (Roles Based Access Control) can use Azure Cost Analysis tool to track consumption per day or filter by meter, service name, resource ID among other parameters. For more details, please see View the costs billed for the metered Microsoft Teams APIs above. |
| Is there a volume discount? | Flat rates apply. |
| Are these APIs enrolled in Microsoft Azure Consumption Commitment (MACC) program? | Not at this time. |