List subscriptions

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Retrieve a list of webhook subscriptions.

The content of the response depends on the context in which the app is calling; for details, see the scenarios in the Permissions section.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including taking caution before choosing more privileged permissions, search for the following permissions in Permissions.

Note

Some resources support change notifications in multiple scenarios, each of which may require different permissions. In those cases, use the resource path to differentiate the scenarios.

Supported resource	Delegated (work or school account)	Delegated (personal Microsoft account)	Application
callRecord	Not supported.	Not supported.	CallRecords.Read.All
callRecording communications/onlineMeetings/getAllRecordings Any recording becomes available in the tenant.	Not supported.	Not supported.	OnlineMeetingRecording.Read.All
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings Any recording becomes available for a specific meeting.	OnlineMeetingRecording.Read.All	Not supported.	OnlineMeetingRecording.Read.All
callRecording users/{userId}/onlineMeetings/getAllRecordings A call recording that becomes available in a meeting organized by a specific user.	OnlineMeetingRecording.Read.All	Not supported.	OnlineMeetingRecording.Read.All
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings A call recording that becomes available in a meeting where a particular Teams app is installed.	Not supported.	Not supported.	OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.Chat
callTranscript communications/onlineMeetings/getAllTranscripts Any transcript becomes available in the tenant.	Not supported.	Not supported.	OnlineMeetingTranscript.Read.All
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts Any transcript becomes available for a specific meeting.	OnlineMeetingTranscript.Read.All	Not supported.	OnlineMeetingTranscript.Read.All
callTranscript users/{userId}/onlineMeetings/getAllTranscripts A call transcript that becomes available in a meeting organized by a specific user.	OnlineMeetingTranscript.Read.All	Not supported.	OnlineMeetingTranscript.Read.All
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts A call transcript that becomes available in a meeting where a particular Teams app is installed.	Not supported.	Not supported.	OnlineMeetingTranscript.Read.All, OnlineMeetingTranscript.Read.Chat
channel /teams/getAllChannels All channels in an organization.	Not supported.	Not supported.	Channel.ReadBasic.All, ChannelSettings.Read.All
channel /teams/{id}/channels All channels in a particular team in an organization.	Channel.ReadBasic.All, ChannelSettings.Read.All, Subscription.Read.All	Not supported.	Channel.ReadBasic.All, ChannelSettings.Read.All
chat /chats All chats in an organization.	Not supported.	Not supported.	Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat /chats/{id} A particular chat.	Chat.ReadBasic, Chat.Read, Chat.ReadWrite, Subscription.Read.All	Not supported.	ChatSettings.Read.Chat, ChatSettings.ReadWrite.Chat, Chat.Manage.Chat, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chat /appCatalogs/teamsApps/{id}/installedToChats All chats in an organization where a particular Teams app is installed.	Not supported.	Not supported.	Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
chatMessage /teams/{id}/channels/{id}/messages All messages and replies in a particular channel.	ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All, Subscription.Read.All	Not supported.	ChannelMessage.Read.Group, ChannelMessage.Read.All
chatMessage /teams/getAllMessages All channel messages in organization.	Not supported.	Not supported.	ChannelMessage.Read.All
chatMessage /chats/{id}/messages All messages in a chat.	Chat.Read, Chat.ReadWrite, Subscription.Read.All	Not supported.	Chat.Read.All
chatMessage /chats/getAllMessages All chat messages in an organization.	Not supported.	Not supported.	Chat.Read.All
chatMessage /users/{id}/chats/getAllMessages Chat messages for all chats a particular user is part of.	Chat.Read, Chat.ReadWrite, Subscription.Read.All	Not supported.	Chat.Read.All, Chat.ReadWrite.All
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages Chat messages for all chats in an organization where a particular Teams app is installed.	Not supported.	Not supported.	Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
contact	Contacts.Read, Subscription.Read.All	Contacts.Read, Subscription.Read.All	Contacts.Read
conversationMember /chats/getAllMembers Members of all chats in an organization.	Not supported.	Not supported.	ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember /chats/{id}/members Members of a particular chat.	ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite, Subscription.Read.All	Not supported.	ChatMember.Read.Chat, Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember appCatalogs/teamsApps/{id}/installedToChats/getAllMembers Chat members for all chats in an organization where a particular Teams app is installed.	Not supported.	Not supported.	ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
conversationMember /teams/getAllMembers Members in all teams in an organization.	Not supported.	Not supported.	TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember /teams/{id}/members Members in a particular team.	TeamMember.Read.All, Subscription.Read.All	Not supported.	TeamMember.Read.All
conversationMember /teams/{id}/channels/getAllMembers Members in all private channels of a particular team.	Not supported.	Not supported.	ChannelMember.Read.All
conversationMember /teams/getAllChannels/getAllMembers	Not supported.	Not supported.	ChannelMember.Read.All
driveItem User's personal OneDrive.	Not supported.	Files.ReadWrite, Subscription.Read.All	Not supported.
driveItem OneDrive for Business.	Files.ReadWrite.All, Subscription.Read.All	Not supported.	Files.ReadWrite.All
event	Calendars.Read, Subscription.Read.All	Calendars.Read, Subscription.Read.All	Calendars.Read
group	Group.Read.All, Subscription.Read.All	Not supported.	Group.Read.All
group conversation	Group.Read.All, Subscription.Read.All	Not supported.	Not supported.
list	Sites.ReadWrite.All, Subscription.Read.All	Not supported.	Sites.ReadWrite.All
message	Mail.ReadBasic, Mail.Read, Subscription.Read.All	Mail.ReadBasic, Mail.Read, Subscription.Read.All	Mail.Read
online meeting	Not supported.	Not supported.	OnlineMeetings.Read.All, OnlineMeetings.ReadWrite.All
presence	Presence.Read.All, Subscription.Read.All	Not supported.	Not supported.
printer	Not supported.	Not supported.	Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition	Not supported.	Not supported.	PrintTaskDefinition.ReadWrite.All
security alert	SecurityEvents.ReadWrite.All, Subscription.Read.All	Not supported.	SecurityEvents.ReadWrite.All
team /teams All teams in an organization.	Not supported.	Not supported.	Team.ReadBasic.All, TeamSettings.Read.All
team /teams/{id} A particular team.	Team.ReadBasic.All, TeamSettings.Read.All, Subscription.Read.All	Not supported.	Team.ReadBasic.All, TeamSettings.Read.All
todoTask	Tasks.ReadWrite, Subscription.Read.All	Tasks.ReadWrite, Subscription.Read.All	Not supported.
user	User.Read.All, Subscription.Read.All	User.Read.All	User.Read.All
baseTask (deprecated)	Tasks.ReadWrite, Subscription.Read.All	Tasks.ReadWrite, Subscription.Read.All	Not supported.

Note

The following permissions use resource-specific consent:

• OnlineMeetingRecording.Read.Chat
• OnlineMeetingTranscript.Read.Chat
• ChatSettings.Read.Chat
• ChatSettings.ReadWrite.Chat
• Chat.Manage.Chat
• ChannelMessage.Read.Group
• ChatMember.Read.Chat

Response results are based on the context of the calling app. The following sections describe the common scenarios.

Basic scenarios

Most commonly, an application wants to retrieve subscriptions that it originally created for the currently signed-in user or all users in the directory (work/school accounts). These scenarios don't require any special permissions beyond the ones the app used originally to create its subscriptions.

Context of the calling app	Response contains
App is calling on behalf of the signed-in user (delegated permission). -and- App has the original permission required to create the subscription. Note: This scenario applies to both personal Microsoft accounts and work/school accounts.	Subscriptions created by the app for the signed-in user only.
App is calling on behalf of itself (application permission). -and- App has the original permission required to create the subscription. Note: This scenario only applies to work/school accounts.	Subscriptions created by the app for itself or any user in the directory.

Advanced scenarios

In some cases, an app wants to retrieve subscriptions created by other apps. For example, a user wants to see all subscriptions created by any app on their behalf. Or, an administrator who wants to see all subscriptions from all apps in their directory. For such scenarios, a delegated permission Subscription.Read.All is required.

Context of the calling app	Response contains
App is calling on behalf of the signed-in user (delegated permission). The user is a non-admin. -and- App has the permission Subscription.Read.All Note: This scenario applies to both personal Microsoft accounts and work/school accounts.	Subscriptions created by any app for the signed-in user only.
App is calling on behalf of the signed-in user (delegated permission). The user is an admin. -and- App has the permission Subscription.Read.All Note: This scenario only applies to work/school accounts.	Subscriptions created by any app for any user in the directory.

HTTP request

GET /subscriptions

Optional query parameters

This method doesn't support the OData query parameters to help customize the response.

Request headers

Name	Type	Description
Authorization	string	Bearer {token}. Required.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and a list of subscription objects in the response body.

Example

Request

HTTP

GET https://graph.microsoft.com/beta/subscriptions

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.GetAsync();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta subscriptions list

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



subscriptions, err := graphClient.Subscriptions().Get(context.Background(), nil)

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

SubscriptionCollectionResponse result = graphClient.subscriptions().get();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let subscriptions = await client.api('/subscriptions')
	.version('beta')
	.get();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->subscriptions()->get()->wait();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Beta.ChangeNotifications

Get-MgBetaSubscription

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.subscriptions.get()

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

The following example shows the response.

Note: The response shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions",
  "value": [
    {
      "id": "0fc0d6db-0073-42e5-a186-853da75fb308",
      "resource": "Users",
      "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
      "changeType": "updated,deleted",
      "clientState": null,
      "notificationUrl": "https://webhookappexample.azurewebsites.net/api/notifications",
      "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
      "expirationDateTime": "2018-03-12T05:00:00Z",
      "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
      "latestSupportedTlsVersion": "v1_2",
      "encryptionCertificate": "",
      "encryptionCertificateId": "",
      "includeResourceData": false,
      "notificationContentType": "application/json"
    }
  ]
}

Note: the clientState property value is not returned for security purposes.

When a request returns multiple pages of data, the response includes an @odata.nextLink property to help you manage the results. To learn more, see Paging Microsoft Graph data in your app.