List subscriptions

Namespace: microsoft.graph

Retrieve the properties and relationships of webhook subscriptions, based on the app ID, the user, and the user's role with a tenant.

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

Permissions

This API supports the following permission scopes; to learn more, including how to choose permissions, see Permissions.

Supported resource	Delegated (work or school account)	Delegated (personal Microsoft account)	Application
callRecord (/communications/callRecords)	Not supported	Not supported	CallRecords.Read.All
channel (/teams/getAllChannels – all channels in an organization)	Not supported	Not supported	Channel.ReadBasic.All, ChannelSettings.Read.All
channel (/teams/{id}/channels)	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})	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
chatMessage (/teams/{id}/channels/{id}/messages)	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)	Chat.Read, Chat.ReadWrite, Subscription.Read.All	Not supported	Chat.Read.All
chatMessage (/chats/getAllMessages -- all chat messages in 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	Not supported	Chat.Read.All, Chat.ReadWrite.All
contact	Contacts.Read, Subscription.Read.All	Contacts.Read, Subscription.Read.All	Contacts.Read
conversationMember (/teams/{id}/channels/getAllMembers)	Not supported	Not supported	ChannelMember.Read.All
conversationMember (/chats/getAllMembers)	Not supported	Not supported	ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/chats/{id}/members)	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 (/teams/{id}/members)	TeamMember.Read.All, Subscription.Read.All	Not supported	TeamMember.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
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})	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

Note: Permissions marked with * use resource-specific consent.

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 for all users in the directory (work/school accounts). These scenarios do not 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 applies to both personal Microsoft accounts and work/school accounts.	Subscriptions created by this 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 applies to work/school accounts only.	Subscriptions created by this app for itself or for 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 may want 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 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 applies to work/school accounts only.	Subscriptions created by any app for any user in the directory.

HTTP request

GET /subscriptions

Optional query parameters

This method does not support the OData query parameters to help customize the response.

Request headers

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

Request body

Do not 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/v1.0/subscriptions

C#

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Subscriptions.GetAsync();

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')
	.get();

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

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

SubscriptionCollectionPage subscriptions = graphClient.subscriptions()
	.buildRequest()
	.get();

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

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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.ChangeNotifications

Get-MgSubscription

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

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$requestResult = $graphServiceClient->subscriptions()->get();

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

Response

The following is an example of 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/v1.0/$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.