This document describes how to list a Pub/Sub topic. To list a
topic you can use the Google Cloud console, the gcloud CLI, the client library,
or the Pub/Sub API.

## Before you begin

- Learn about [topics](https://docs.cloud.google.com/pubsub/docs/publish-message-overview.md.txt#about_topics) and the publish messages workflow.
- [Create a topic](https://docs.cloud.google.com/pubsub/docs/create-topic.md.txt).

### Required roles and permissions

<br />


To get the permissions that
you need to list topics 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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


This predefined role contains

the permissions required to list topics and manage them. To see the exact permissions that are
required, expand the **Required permissions** section:


#### Required permissions

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

- Create a topic: `pubsub.topics.create`
- Delete a topic: `pubsub.topics.delete`
- Detach a subscription from a topic: `pubsub.topics.detachSubscription`
- Get a topic: `pubsub.topics.get`
- List a topic: `pubsub.topics.list`
- Publish to a topic: `pubsub.topics.publish`
- Update a topic: `pubsub.topics.update`
- Get the IAM policy for a topic: `pubsub.topics.getIamPolicy`
- Configure the [IAM policy](https://docs.cloud.google.com/iam/docs/reference/rest/v1/Policy.md.txt) for a topic: `pubsub.topics.setIamPolicy`


You might also be able to get
these permissions
with [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or
other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#predefined).

You can configure access control at the project level and at the individual
resource level. You can create a subscription in one project and
attach it to a topic located in a different project.
Ensure that you have the required permissions for
each project.

## List a topic

### Console


- In the Google Cloud console, go to the Pub/Sub **Topics** page.

- [Go to Topics](https://console.cloud.google.com/cloudpubsub/topic)
- The **Topics** page lists all the available topics.
- By default, the console returns 50 topics. You can increase this value to return a maximum of 200 topics by using the **Rows per page** drop-down toggle. This toggle only appears in the console if you have more than 20 topics in a project.

<br />

### gcloud


1. In the Google Cloud console, activate Cloud Shell.

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)


   At the bottom of the Google Cloud console, a
   [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works.md.txt)
   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.
2. To list topics, use the
   [`gcloud pubsub topics list`](https://docs.cloud.google.com/sdk/gcloud/reference/pubsub/topics/list)
   command:

   ```bash
   gcloud pubsub topics list
   ```

By default, a maximum of 100 results are returned per query.
You can specify an alternative value of up to 1,000 using the page size parameter.
For example, using the Google Cloud CLI, specify [`--page-size=1000`](https://docs.cloud.google.com/sdk/gcloud/reference/pubsub/topics/list#LIST-COMMAND-FLAGS).

<br />

### REST


To list topics, use the
[`projects.topics.list`](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list.md.txt)
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`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token.md.txt).

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

Where:
- <var translate="no">PROJECT_ID</var> is your project ID.
- Response:

```restructuredtext
{
"topics": [
  {
    "name": "projects/PROJECT_ID/topics/mytopic1",
    ...
  },
  {
    "name": "projects/PROJECT_ID/topics/mytopic2",
    ...
  }
]
}
```

### C++


Before trying this sample, follow the C++ setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub C++ API reference documentation](https://googleapis.dev/cpp/google-cloud-pubsub/latest/).

```c++
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::TopicAdminClient client, std::string const& project_id) {
  int count = 0;
  for (auto& topic : client.ListTopics("projects/" + project_id)) {
    if (!topic) throw std::move(topic).status();
    std::cout << "Topic Name: " << topic->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No topics found in project " << project_id << "\n";
  }
}
```

<br />

### C#


Before trying this sample, follow the C# setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub C# API reference documentation](https://cloud.google.com/dotnet/docs/reference/Google.Cloud.PubSub.V1/latest).

```c#

using Google.Api.Gax.ResourceNames;
using Google.Cloud.PubSub.V1;
using System.Collections.Generic;

public class ListProjectTopicsSample
{
    public IEnumerable<Topic> ListProjectTopics(string projectId)
    {
        PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
        ProjectName projectName = ProjectName.FromProject(projectId);
        IEnumerable<Topic> topics = publisher.ListTopics(projectName);
        return topics;
    }
}
```

<br />

### 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](https://github.com/googleapis/google-cloud-go/blob/main/pubsub/MIGRATING.md).
To see a list of v1 code samples, see [the deprecated code samples](https://docs.cloud.google.com/pubsub/docs/samples.md.txt?language=golang&text=deprecated).

Before trying this sample, follow the Go setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Go API reference documentation](https://pkg.go.dev/cloud.google.com/go/pubsub/v2).

```go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/api/iterator"
)

func listTopics(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	req := &pubsubpb.ListTopicsRequest{
		Project: fmt.Sprintf("projects/%s", projectID),
	}
	it := client.TopicAdminClient.ListTopics(ctx, req)
	for {
		topic, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("error listing topics: %w", err)
		}
		fmt.Fprintf(w, "got topic: %s\n", topic)

	}
	return nil
}
```

<br />

### Java


Before trying this sample, follow the Java setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Java API reference documentation](https://cloud.google.com/java/docs/reference/google-cloud-pubsub/latest/overview).

```java

import com.google.cloud.pubsub.v1.TopicAdminClient;
import com.google.pubsub.v1.ProjectName;
import com.google.pubsub.v1.Topic;
import java.io.IOException;

public class ListTopicsExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";

    listTopicsExample(projectId);
  }

  public static void listTopicsExample(String projectId) throws IOException {
    try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
      ProjectName projectName = ProjectName.of(projectId);
      for (Topic topic : topicAdminClient.listTopics(projectName).iterateAll()) {
        System.out.println(topic.getName());
      }
      System.out.println("Listed all topics.");
    }
  }
}
```

<br />

### Node.js


Before trying this sample, follow the Node.js setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Node.js API reference documentation](https://googleapis.dev/nodejs/pubsub/latest).

    // 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 listAllTopics() {
      // Lists all topics in the current project
      const [topics] = await pubSubClient.getTopics();
      console.log('Topics:');
      topics.forEach(topic => console.log(topic.name));
    }

<br />

### Node.ts


Before trying this sample, follow the Node.js setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Node.js API reference documentation](https://googleapis.dev/nodejs/pubsub/latest).

    // Imports the Google Cloud client library
    import {PubSub, Topic} from '@google-cloud/pubsub';

    // Creates a client; cache this for further use
    const pubSubClient = new PubSub();

    async function listAllTopics() {
      // Lists all topics in the current project
      const [topics] = await pubSubClient.getTopics();
      console.log('Topics:');
      topics.forEach((topic: Topic) => console.log(topic.name));
    }

<br />

### PHP


Before trying this sample, follow the PHP setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub PHP API reference documentation](https://cloud.google.com/php/docs/reference/cloud-pubsub/latest).

```php
use Google\Cloud\PubSub\PubSubClient;

/**
 * Lists all Pub/Sub topics.
 *
 * @param string $projectId  The Google project ID.
 */
function list_topics($projectId)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    foreach ($pubsub->topics() as $topic) {
        printf('Topic: %s' . PHP_EOL, $topic->name());
    }
}
```

<br />

### Python


Before trying this sample, follow the Python setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Python API reference documentation](https://docs.cloud.google.com/python/docs/reference/pubsub/latest.md.txt).

```python
from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"

publisher = pubsub_v1.PublisherClient()
project_path = f"projects/{project_id}"

for topic in publisher.list_topics(request={"project": project_path}):
    print(topic)
```

<br />

### 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](https://github.com/googleapis/google-cloud-ruby/blob/main/google-cloud-pubsub/MIGRATION_GUIDE.md).
To see a list of Ruby v2 code samples, see [the deprecated code samples](https://docs.cloud.google.com/pubsub/docs/samples.md.txt?language=ruby&text=deprecated).

Before trying this sample, follow the Ruby setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Ruby API reference documentation](https://googleapis.dev/ruby/google-cloud-pubsub/latest/Google/Cloud/PubSub.html).

```ruby

pubsub = Google::Cloud::PubSub.new
topic_admin = pubsub.topic_admin

topics = topic_admin.list_topics project: pubsub.project_path

puts "Topics in project:"
topics.each do |topic|
  puts topic.name
end
```

<br />

### Rust


Before trying this sample, follow the Rust setup instructions in
[Quickstart: Using Client Libraries](https://docs.cloud.google.com/pubsub/docs/create-topic-client-libraries).
For more information, see the [Pub/Sub Rust API reference documentation](https://docs.rs/google-cloud-pubsub).

```rust
use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_pubsub::client::TopicAdmin;

pub async fn sample(client: &TopicAdmin, project: &str) -> anyhow::Result<()> {
    let mut topics = client
        .list_topics()
        .set_project(format!("projects/{}", project))
        .by_item();

    println!("listing topics");
    while let Some(topic) = topics.next().await.transpose()? {
        println!("{topic:?}");
    }
    println!("DONE");
    Ok(())
}
```

<br />

## What's next

- Choose the [type of subscription](https://docs.cloud.google.com/pubsub/docs/subscriber.md.txt) for your topic.

- Create a subscription for your topic: [pull](https://docs.cloud.google.com/pubsub/docs/create-subscription.md.txt), [push](https://docs.cloud.google.com/pubsub/docs/create-push-subscription.md.txt), or [BigQuery](https://docs.cloud.google.com/pubsub/docs/create-bigquery-subscription.md.txt).

- Create or modify a topic with [gcloud CLI](https://docs.cloud.google.com/sdk/gcloud/reference/pubsub/topics).

- Create or modify a topic with [REST APIs](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics.md.txt).