List topics

Every topic on your team, newest first.

GET /v1/topics

Requires a Full access API key.

Query parameters

Cursor-paginated:

Parameter	Type	Description
limit	number	How many to return. Default 20, min 1, max 100.
after	string	Return topics after this id. Cannot be combined with before.
before	string	Return topics before this id. Cannot be combined with after.

Example

curl

curl "https://api.sendgrail.com/v1/topics" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch('https://api.sendgrail.com/v1/topics', {
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

const { data, has_more } = await res.json();

Response

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "topic",
      "id": "7b2e6f90-3c11-4a5d-9b8e-1f0c4d6a2e59",
      "key": "product-updates",
      "name": "Product updates",
      "description": "New features and improvements, about once a month",
      "default_subscription": "opt_out",
      "visibility": "public",
      "created_at": "2026-07-14T19:44:32+00:00"
    },
    {
      "object": "topic",
      "id": "e4c8a1d6-72f3-4b09-85aa-6d1b3f9c0e42",
      "key": "billing-alerts",
      "name": "Billing alerts",
      "description": null,
      "default_subscription": "opt_out",
      "visibility": "private",
      "created_at": "2026-06-02T09:12:04+00:00"
    }
  ]
}

has_more tells you whether another page exists — there is no total, because a keyset paginator never counts the table. To walk every page, pass the last id you saw as after until has_more is false. See Pagination.

This returns all topics, private ones included. Visibility governs the public preference page a contact sees, not what your own API key can read.

To find out whether a particular contact is subscribed to any of these, ask the contact: GET /v1/contacts/{id}/topics. See Contact topics.