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.

Payment models

The following payment models are available:

• model=A is restricted to applications performing a security or compliance function, and requires a supported license.

• model=B is restricted to applications that don't perform a security or compliance function. There are no licensing requirements for model=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.

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.

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.

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.

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.

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.

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.

The following table lists the prices for using Teams meeting APIs, applicable to both beta and v1.0 endpoints.

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.

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:

1. Sign in to the Azure portal at https://portal.azure.com.
2. Go to Cost Management + Billing > Cost Management > Cost analysis.
3. For the filter near the top, select Service name: Microsoft Graph Services.
4. 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.

1. In the left pane, choose Analytics & reports > Usage reports.
2. On the View reports tab, under Report, choose Teams user activity.
3. Under Date range, select a range.
4. Choose Run report.

Frequently asked questions