List subscriptions

You can list the subscriptions in a Google Cloud project with the Google Cloud console, Google Cloud CLI, client library, or Pub/Sub API.

Before you begin

Learn about subscriptions .
Create one of the following subscriptions, pull , push , or BigQuery .

Required roles and permissions

To get the permissions that you need to list subscriptions and manage them, ask your administrator to grant you the Pub/Sub Editor ( roles/pubsub.editor ) IAM role on your topic or project. For more information about granting roles, see Manage access to projects, folders, and organizations .

This predefined role contains the permissions required to list subscriptions and manage them. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to list subscriptions and manage them:

Pull from a subscription: pubsub.subscriptions.consume
Create a subscription: pubsub.subscriptions.create
Delete a subscription: pubsub.subscriptions.delete
Get a subscription: pubsub.subscriptions.get
List a subscription: pubsub.subscriptions.list
Update a subscription: pubsub.subscriptions.update
Attach a subscription to a topic: pubsub.topics.attachSubscription
Get the IAM policy for a subscription: pubsub.subscriptions.getIamPolicy
Configure the IAM policy for a subscription: pubsub.subscriptions.setIamPolicy

You might also be able to get these permissions with custom roles or other predefined roles .

List a subscription

You can list the subscriptions in a Google Cloud project with the Google Cloud console, Google Cloud CLI, client library, or Pub/Sub API.

Console

To list the subscriptions in a project, go to the Subscriptionspage.

Go to Subscriptions

Your subscriptions are listed in the table on the page.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
To list the subscriptions in a Google Cloud project, run the gcloud pubsub subscriptions list command:
```
gcloud  
pubsub  
subscriptions  
list  
 [ 
--project = 
 PROJECT_ID 
 ] 
```

REST

To list subscriptions in a project, use the projects.subscriptions.list method:

Request:

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token .

GET https://pubsub.googleapis.com/v1/projects/ PROJECT_ID 
/subscriptions
Authorization: Bearer ACCESS_TOKEN

Where:

PROJECT_ID is your project ID.

Response:

{
"subscriptions": [
{
  "name": "projects/ PROJECT_ID 
/topics/mysubscription1",
  "topic": "projects/ PROJECT_ID 
/topics/ TOPIC_ID 
",
  "pushConfig": {},
  "ackDeadlineSeconds": 10,
  "retainAckedMessages": true,
  "messageRetentionDuration": "604800s",
  "expirationPolicy": {}
},
{
  "name": "projects/ PROJECT_ID 
/topics/mysubscription2",
  "topic": "projects/ PROJECT_ID 
/topics/ TOPIC_ID 
",
  "pushConfig": {
    "pushEndpoint": "https:// PROJECT_ID 
.appspot.com/myhandler",
    "attributes": {
      "x-goog-version": "v1"
    }
  },
  "ackDeadlineSeconds": 10,
  "retainAckedMessages": true,
  "messageRetentionDuration": "604800s",
  "expirationPolicy": {}
}
]
}

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub C++ API reference documentation .

  namespace 
  
 pubsub_admin 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 pubsub_admin 
 ; 
 []( 
 pubsub_admin 
 :: 
 SubscriptionAdminClient 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 project_id 
 ) 
  
 { 
  
 int 
  
 count 
  
 = 
  
 0 
 ; 
  
 google 
 :: 
 pubsub 
 :: 
 v1 
 :: 
 ListSubscriptionsRequest 
  
 request 
 ; 
  
 request 
 . 
 set_project 
 ( 
 google 
 :: 
 cloud 
 :: 
 Project 
 ( 
 project_id 
 ). 
 FullName 
 ()); 
  
 for 
  
 ( 
 auto 
&  
 subscription 
  
 : 
  
 client 
 . 
 ListSubscriptions 
 ( 
 request 
 )) 
  
 { 
  
 if 
  
 ( 
 ! 
 subscription 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 subscription 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Subscription Name: " 
 << 
 subscription 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
  
 ++ 
 count 
 ; 
  
 } 
  
 if 
  
 ( 
 count 
  
 == 
  
 0 
 ) 
  
 { 
  
 std 
 :: 
 cout 
 << 
 "No subscriptions found in project " 
 << 
 project_id 
 << 
 " 
 \n 
 " 
 ; 
  
 } 
 }

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub C# API reference documentation .

  using 
  
  Google.Api.Gax.ResourceNames 
 
 ; 
 using 
  
  Google.Cloud.PubSub.V1 
 
 ; 
 using 
  
 System.Collections.Generic 
 ; 
 public 
  
 class 
  
 ListSubscriptionsSample 
 { 
  
 public 
  
 IEnumerable<Subscription> 
  
 ListSubscriptions 
 ( 
 string 
  
 projectId 
 ) 
  
 { 
  
  SubscriberServiceApiClient 
 
  
 subscriber 
  
 = 
  
  SubscriberServiceApiClient 
 
 . 
  Create 
 
 (); 
  
  ProjectName 
 
  
 projectName 
  
 = 
  
  ProjectName 
 
 . 
  FromProject 
 
 ( 
 projectId 
 ); 
  
 var 
  
 subscriptions 
  
 = 
  
 subscriber 
 . 
  ListSubscriptions 
 
 ( 
 projectName 
 ); 
  
 return 
  
 subscriptions 
 ; 
  
 } 
 }

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, see the migration guide to v2 . To see a list of v1 code samples, see the deprecated code samples .

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Go API reference documentation .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "cloud.google.com/go/pubsub/v2" 
  
 "cloud.google.com/go/pubsub/v2/apiv1/pubsubpb" 
  
 "google.golang.org/api/iterator" 
 ) 
 func 
  
 list 
 ( 
 projectID 
  
 string 
 ) 
  
 ([] 
 * 
 pubsubpb 
 . 
 Subscription 
 , 
  
 error 
 ) 
  
 { 
  
 // projectID := "my-project-id" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 pubsub 
 . 
 NewClient 
 ( 
 ctx 
 , 
  
 projectID 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "pubsub.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 var 
  
 subs 
  
 [] 
 * 
 pubsubpb 
 . 
 Subscription 
  
 req 
  
 := 
  
& pubsubpb 
 . 
 ListSubscriptionsRequest 
 { 
  
 Project 
 : 
  
 fmt 
 . 
 Sprintf 
 ( 
 "projects/%s" 
 , 
  
 projectID 
 ), 
  
 } 
  
 it 
  
 := 
  
 client 
 . 
 SubscriptionAdminClient 
 . 
 ListSubscriptions 
 ( 
 ctx 
 , 
  
 req 
 ) 
  
 for 
  
 { 
  
 s 
 , 
  
 err 
  
 := 
  
 it 
 . 
 Next 
 () 
  
 if 
  
 err 
  
 == 
  
 iterator 
 . 
 Done 
  
 { 
  
 break 
  
 } 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "Next: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 subs 
  
 = 
  
 append 
 ( 
 subs 
 , 
  
 s 
 ) 
  
 } 
  
 return 
  
 subs 
 , 
  
 nil 
 }

Java

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Java API reference documentation .

  import 
  
 com.google.cloud.pubsub.v1. SubscriptionAdminClient 
 
 ; 
 import 
  
 com.google.pubsub.v1. ProjectName 
 
 ; 
 import 
  
 com.google.pubsub.v1. Subscription 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 public 
  
 class 
 ListSubscriptionsInProjectExample 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 ... 
  
 args 
 ) 
  
 throws 
  
 Exception 
  
 { 
  
 // TODO(developer): Replace these variables before running the sample. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 listSubscriptionInProjectExample 
 ( 
 projectId 
 ); 
  
 } 
  
 public 
  
 static 
  
 void 
  
 listSubscriptionInProjectExample 
 ( 
 String 
  
 projectId 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 try 
  
 ( 
  SubscriptionAdminClient 
 
  
 subscriptionAdminClient 
  
 = 
  
  SubscriptionAdminClient 
 
 . 
 create 
 ()) 
  
 { 
  
  ProjectName 
 
  
 projectName 
  
 = 
  
  ProjectName 
 
 . 
 of 
 ( 
 projectId 
 ); 
  
 for 
  
 ( 
  Subscription 
 
  
 subscription 
  
 : 
  
 subscriptionAdminClient 
 . 
 listSubscriptions 
 ( 
 projectName 
 ). 
 iterateAll 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 subscription 
 . 
 getName 
 ()); 
  
 } 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Listed all the subscriptions in the project." 
 ); 
  
 } 
  
 } 
 }

Node.js

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Node.js API reference documentation .

  // 
  
 Imports 
  
 the 
  
 Google 
  
 Cloud 
  
 client 
  
 library 
 const 
  
 { 
 PubSub 
 } 
  
 = 
  
 require 
 ( 
 '@google-cloud/pubsub' 
 ); 
 // 
  
 Creates 
  
 a 
  
 client 
 ; 
  
 cache 
  
 this 
  
 for 
  
 further 
  
 use 
 const 
  
 pubSubClient 
  
 = 
  
 new 
  
 PubSub 
 (); 
 async 
  
 function 
  
 listSubscriptions 
 () 
  
 { 
  
 // 
  
 Lists 
  
 all 
  
 subscriptions 
  
 in 
  
 the 
  
 current 
  
 project 
  
 const 
  
 [ 
 subscriptions 
 ] 
  
 = 
  
 await 
  
 pubSubClient 
 . 
 getSubscriptions 
 (); 
  
 console 
 . 
 log 
 ( 
 'Subscriptions:' 
 ); 
  
 subscriptions 
 . 
 forEach 
 ( 
 subscription 
  
 = 
>  
 console 
 . 
 log 
 ( 
 subscription 
 . 
 name 
 )); 
 }

Node.ts

Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Node.js API reference documentation .

  // 
 Imports 
 the 
 Google 
 Cloud 
 client 
 library 
 import 
  
 { 
 PubSub 
 , 
 Subscription 
 } 
 from 
  
 '@google-cloud/pubsub' 
 ; 
 // 
 Creates 
 a 
 client 
 ; 
 cache 
 this 
 for 
 further 
 use 
 const 
 pubSubClient 
 = 
 new 
 PubSub 
 (); 
 async 
 function 
 listSubscriptions 
 () 
 { 
 // 
 Lists 
 all 
 subscriptions 
 in 
 the 
 current 
 project 
 const 
 [ 
 subscriptions 
 ] 
 = 
 await 
 pubSubClient 
 . 
 getSubscriptions 
 (); 
 console 
 . 
 log 
 ( 
 'Subscriptions:' 
 ); 
 subscriptions 
 . 
 forEach 
 (( 
 subscription 
 : 
 Subscription 
 ) 
 = 
> console 
 . 
 log 
 ( 
 subscription 
 . 
 name 
 ), 
 ); 
 }

PHP

Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub PHP API reference documentation .

  use Google\Cloud\PubSub\PubSubClient; 
 /** 
 * Lists all Pub/Sub subscriptions. 
 * 
 * @param string $projectId  The Google project ID. 
 */ 
 function list_subscriptions($projectId) 
 { 
 $pubsub = new PubSubClient([ 
 'projectId' => $projectId, 
 ]); 
 foreach ($pubsub->subscriptions() as $subscription) { 
 printf('Subscription: %s' . PHP_EOL, $subscription->name()); 
 } 
 }

Python

Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Python API reference documentation .

  from 
  
 google.cloud 
  
 import 
 pubsub_v1 
 # TODO(developer) 
 # project_id = "your-project-id" 
 subscriber 
 = 
 pubsub_v1 
 . 
  SubscriberClient 
 
 () 
 project_path 
 = 
 f 
 "projects/ 
 { 
 project_id 
 } 
 " 
 # Wrap the subscriber in a 'with' block to automatically call close() to 
 # close the underlying gRPC channel when done. 
 with 
 subscriber 
 : 
 for 
 subscription 
 in 
 subscriber 
 . 
 list_subscriptions 
 ( 
 request 
 = 
 { 
 "project" 
 : 
 project_path 
 } 
 ): 
 print 
 ( 
 subscription 
 . 
 name 
 )

Ruby

The following sample uses Ruby Pub/Sub client library v3. If you are still using the v2 library, see the migration guide to v3 . To see a list of Ruby v2 code samples, see the deprecated code samples .

Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries . For more information, see the Pub/Sub Ruby API reference documentation .

  pubsub 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  PubSub 
 
 . 
  new 
 
 subscription_admin 
  
 = 
  
 pubsub 
 . 
  subscription_admin 
 
 subscriptions 
  
 = 
  
 subscription_admin 
 . 
 list_subscriptions 
  
 \ 
  
 project 
 : 
  
 pubsub 
 . 
 project_path 
 puts 
  
 "Subscriptions:" 
 subscriptions 
 . 
 each 
  
 do 
  
 | 
 subscription 
 | 
  
 puts 
  
 subscription 
 . 
 name 
 end