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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

{
  "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/api/v1/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

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

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())

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

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

Errors: not_found, rate_limited, scope_missing, unauthorized

Check a brand now

POST/api/v1/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

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

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())

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

{
  "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