---
title: List Audience Tags
protocol: rest
method: GET
endpoint: /v1/projects/{projectId}/audiences/tags
description: "List all unique audience tags across profiles"
---

# List Audience Tags

Retrieve all unique audience tags used across all profiles in a project. Useful for understanding which tags are available when creating or editing profiles.

<Endpoint method="GET" path="/v1/projects/{projectId}/audiences/tags" />

## Path Parameters

<ParamField path="projectId" type="string" required>
  The project ID.
</ParamField>

## Response

Returns an array of unique audience tags with usage counts.

### Tag Object

<ResponseField name="tag" type="string">
  The audience tag name.
</ResponseField>

<ResponseField name="profileCount" type="integer">
  Number of profiles that include this tag.
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Number of pages that require this tag (from the latest build).
</ResponseField>

## Example

<CodeGroup>
```bash cURL
curl https://api.syntext.dev/v1/projects/proj_abc123/audiences/tags \
  -H "Authorization: Bearer stx_abc12345_..."
```

```typescript SDK
import { Syntext } from '@syntext/sdk'

const client = new Syntext('stx_abc12345_...')

const tags = await client.audiences.listTags('proj_abc123')
```

```python Python
from syntext import Syntext

client = Syntext("stx_abc12345_...")

tags = client.audiences.list_tags("proj_abc123")
```
</CodeGroup>

### Response

```json
{
  "data": [
    {
      "tag": "otc",
      "profileCount": 3,
      "pageCount": 12
    },
    {
      "tag": "virtual-accounts",
      "profileCount": 2,
      "pageCount": 8
    },
    {
      "tag": "enterprise",
      "profileCount": 1,
      "pageCount": 5
    },
    {
      "tag": "beta",
      "profileCount": 1,
      "pageCount": 3
    },
    {
      "tag": "transfers",
      "profileCount": 2,
      "pageCount": 15
    }
  ]
}
```

## Use Cases

### Validate Tag Coverage

Before adding a new audience tag to a profile, check if any pages actually use it:

```typescript
const tags = await client.audiences.listTags('proj_abc123')
const betaTag = tags.find(t => t.tag === 'beta')

if (!betaTag || betaTag.pageCount === 0) {
  console.warn('No pages are tagged with "beta" - adding this to a profile will have no effect')
}
```

### Find Orphaned Tags

Identify tags that exist in page frontmatter but aren't assigned to any profile:

```typescript
const tags = await client.audiences.listTags('proj_abc123')
const orphanedTags = tags.filter(t => t.profileCount === 0 && t.pageCount > 0)

console.log('Pages gated but no profiles can access:', orphanedTags)
```