API Reference

API Reference v2

Programmatic access to all BrandWatch features. Build integrations, automate workflows, and pull rank data into your own dashboards.

https://api.brandwatch.app/v2

Authentication

All requests require a valid Bearer token. Generate API keys from your account settings under API Access.

Back to Docs →

API Request

API Explorer

All API requests must include a valid Bearer token in the Authorization header. Generate API keys from your account settings under API Access.

curl https://api.brandwatch.app/v2/brands \
  -H "Authorization: Bearer bwb_live_sk_••••••••" \
  -H "Content-Type: application/json"

Endpoints

All endpoints return JSON. Dates are in ISO 8601 format. Paginated endpoints return a cursor for continuation.

GET/brandsPOST/brandsGET/brands/{id}/reportsGET/brands/{id}/actionsPOST/scansGET/scans/{id}

GET/brands

Return a paginated list of all brand monitors in your account, including their scan interval, location, and last scan timestamp.

Response

[
  {
    "id": "brd_01j8k2x",
    "name": "Acme Corp",
    "interval": "weekly",
    "location": "New York, NY",
    "last_scan": "2026-03-06T14:22:00Z",
    "status": "active"
  }
]

POST/brands

Create a new brand monitor. Returns the created monitor object including the assigned ID.

Request Body

{
  "name": "Acme Corp",
  "interval": "weekly",
  "location": "New York, NY",
  "queries": ["acme corp plumber", "best plumber nyc"]
}

Response

{
  "id": "brd_01j8k2x",
  "name": "Acme Corp",
  "interval": "weekly",
  "status": "active",
  "created_at": "2026-03-07T09:00:00Z"
}

GET/brands/{id}/reports

Retrieve all rank reports for a specific brand monitor, ordered by scan date descending. Each report contains per-query position data.

Response

{
  "brand_id": "brd_01j8k2x",
  "reports": [
    {
      "scan_id": "scn_9xk2p",
      "scanned_at": "2026-03-06T14:22:00Z",
      "results": [
        { "query": "acme corp plumber", "position": 3, "url": "https://acme.com" }
      ]
    }
  ]
}

GET/brands/{id}/actions

Retrieve AI-recommended action items for a brand monitor, sorted by expected impact score. Each action includes effort level and supporting rationale.

Response

[
  {
    "id": "act_7mn3q",
    "title": "Improve meta description for /services",
    "impact": "high",
    "effort": "low",
    "rationale": "Page ranks #6 for 'acme corp plumber' but has no meta description."
  }
]

POST/scans

Trigger an immediate out-of-schedule scan for one or more brand monitors. Useful after publishing new content or making on-page changes.

Request Body

{
  "brand_ids": ["brd_01j8k2x"]
}

Response

{
  "scan_id": "scn_9xk2p",
  "status": "queued",
  "estimated_completion": "2026-03-07T09:03:00Z"
}

GET/scans/{id}

Check the status of a scan by ID. Returns queued, running, completed, or failed along with partial results if the scan is in progress.

Response

{
  "scan_id": "scn_9xk2p",
  "status": "completed",
  "completed_at": "2026-03-07T09:02:44Z",
  "brand_id": "brd_01j8k2x"
}

Rate Limits

Limits are enforced per API key on a rolling 60-second window. Exceeding the limit returns a 429 response with a Retry-After header.

Startup100 requests / min

Enterprise1,000 requests / min

Get early API access

Join the waitlist to get your API key and start pulling rank data into your own tools. Early adopters get priority API rate limits and a direct line to our engineering team.