# Brand mentions

Where your brand, domain or product is talked about on the web, and whether the tone is positive or negative.

## Brand mentions: plan and usage

`GET /brand-mentions` · scope `mentions:read`

The plan, how many phrases may be tracked, checks a month included and used, the checks your chosen schedules plan for, and the overall sentiment split.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/brand-mentions" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/brand-mentions", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "active": true,
    "plan": "Pro",
    "paid_until": "2026-10-31",
    "brands": {
      "used": 6,
      "limit": 10
    },
    "checks_this_month": {
      "used": 21,
      "limit": 60,
      "planned": 26
    },
    "sentiment": {
      "positive": 40,
      "neutral": 120,
      "negative": 12
    },
    "new_last_7_days": 9
  }
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## List tracked brands

`GET /brand-mentions/brands` · scope `mentions:read`



### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer | no | Items per page. Default: `50`. |
| `cursor` | query | string | no | next_cursor of the previous page. |

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/brand-mentions/brands" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/brand-mentions/brands", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": [
    {
      "id": 31,
      "phrase": "example brand",
      "frequency": "weekly",
      "mentions": 59,
      "positive": 15,
      "neutral": 34,
      "negative": 9,
      "visibility": 143,
      "new_since_last": 4,
      "total_known": 120,
      "last_check_at": "2026-09-22T03:00:00Z",
      "checks": 12,
      "hosted_site_id": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## One brand and its mentions

`GET /brand-mentions/brands/{brand_id}` · scope `mentions:read`

Reads what is stored - it never spends a check.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `brand_id` | path | integer | yes | The tracked brand id. |
| `tone` | query | string (one of: positive, neutral, negative) | no | Only mentions with this tone. |
| `limit` | query | integer | no | How many mentions to return. Default: `100`. |

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "id": 31,
    "phrase": "example brand",
    "frequency": "weekly",
    "mentions": [
      {
        "url": "https://news.example/post",
        "domain": "news.example",
        "title": "A review",
        "snippet": "the sentence the phrase appears in",
        "tone": "positive",
        "language": "en",
        "country": null,
        "domain_authority": 141,
        "spam_score": 4,
        "published_at": "2026-09-20T09:00:00Z",
        "first_seen_at": "2026-09-21T03:00:00Z"
      }
    ],
    "positive": 15,
    "neutral": 34,
    "negative": 9,
    "visibility": 143,
    "new_since_last": 4,
    "total_known": 120,
    "last_check_at": "2026-09-22T03:00:00Z",
    "checks": 12,
    "hosted_site_id": null,
    "history": [
      {
        "taken_at": "2026-09-22T03:00:00Z",
        "mentions": 59,
        "positive": 15,
        "negative": 9,
        "new_found": 4
      }
    ]
  }
}
```

Errors: `not_found`, `rate_limited`, `scope_missing`, `unauthorized`

## Every mention across all your brands

`GET /brand-mentions/mentions` · scope `mentions:read`

Newest first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `tone` | query | string (one of: positive, neutral, negative) | no | Only mentions with this tone. |
| `brand_id` | query | integer | no | Only mentions of this brand. |
| `search` | query | string | no | Part of a title, domain or snippet. |
| `limit` | query | integer | no | Items per page. Default: `50`. |
| `cursor` | query | string | no | next_cursor of the previous page. |

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/brand-mentions/mentions" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/brand-mentions/mentions", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/mentions", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": [
    {
      "url": "https://news.example/post",
      "domain": "news.example",
      "title": "A review",
      "snippet": "the sentence the phrase appears in",
      "tone": "positive",
      "language": "en",
      "country": null,
      "domain_authority": 141,
      "spam_score": 4,
      "published_at": "2026-09-20T09:00:00Z",
      "first_seen_at": "2026-09-21T03:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## Listen for a brand

`POST /brand-mentions/brands` · scope `mentions:write`

Refused when it would pass the plan's brand limit, or when the chosen schedule would plan more checks a month than the plan includes.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `phrase` | body | string | yes | A brand, domain, product or person to listen for. |
| `frequency` | body | string (one of: daily, weekly, monthly) | no | How often we listen. Daily uses ~30 checks a month, weekly ~4.3, monthly 1. Default: `weekly`. |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/brand-mentions/brands" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/brand-mentions/brands", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`201`

```json
{
  "data": {
    "id": 31,
    "phrase": "example brand",
    "frequency": "weekly",
    "mentions": 59,
    "positive": 15,
    "neutral": 34,
    "negative": 9,
    "visibility": 143,
    "new_since_last": 4,
    "total_known": 120,
    "last_check_at": "2026-09-22T03:00:00Z",
    "checks": 12,
    "hosted_site_id": null
  }
}
```

Errors: `payment_required`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Change how often we listen

`PATCH /brand-mentions/brands/{brand_id}` · scope `mentions:write`



### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `brand_id` | path | integer | yes | The tracked brand id. |
| `frequency` | body | string (one of: daily, weekly, monthly) | no | How often we listen. Daily uses ~30 checks a month, weekly ~4.3, monthly 1. Default: `weekly`. |

### Example

```bash
curl -s -X PATCH "https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.patch("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", {
  method: "PATCH",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "id": 31,
    "phrase": "example brand",
    "frequency": "weekly",
    "mentions": 59,
    "positive": 15,
    "neutral": 34,
    "negative": 9,
    "visibility": 143,
    "new_since_last": 4,
    "total_known": 120,
    "last_check_at": "2026-09-22T03:00:00Z",
    "checks": 12,
    "hosted_site_id": null
  }
}
```

Errors: `not_found`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Stop listening for a brand

`DELETE /brand-mentions/brands/{brand_id}` · scope `mentions:write`

Stops listening. Everything already found is kept.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `brand_id` | path | integer | yes | The tracked brand id. |

### Example

```bash
curl -s -X DELETE "https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.delete("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id", {
  method: "DELETE",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "deleted": true,
    "id": 31
  }
}
```

Errors: `not_found`, `rate_limited`, `scope_missing`, `unauthorized`

## Check a brand now

`POST /brand-mentions/brands/{brand_id}/check` · scope `mentions:write`

Uses one check of the monthly allowance, unless a recent shared snapshot of that phrase can be reused, in which case it costs nothing. At most once a day per brand.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `brand_id` | path | integer | yes | The tracked brand id. |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id/check" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id/check", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/brand-mentions/brands/brand_id/check", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "id": 31,
    "phrase": "example brand",
    "frequency": "weekly",
    "mentions": 59,
    "positive": 15,
    "neutral": 34,
    "negative": 9,
    "visibility": 143,
    "new_since_last": 4,
    "total_known": 120,
    "last_check_at": "2026-09-22T03:00:00Z",
    "checks": 12,
    "hosted_site_id": null
  }
}
```

Errors: `not_found`, `rate_limited`, `scope_missing`, `unauthorized`, `unavailable`