# competitorBrands

Query

List Competitor Insights brands tracked by the current workspace, ordered newest first, with aggregate metrics over a `period`/`date` window (default month). The workspace's own-brand entry is returned as one additional pinned node on the first page (flagged `isOwnBrand`), in addition to up to `first` competitor brands, so self-vs-competitor Share of Voice is computable in-query; `totalCount` counts tracked competitor brands only. Pair with `competitorBrandItems(brandId:, filter:, …)` to paginate a brand's media items. If aggregate metrics are unavailable, roster data remains and the response includes a `SERVICE_UNAVAILABLE` error; match on `extensions.code` and retry later.

Available to agents as MCP tool `getCompetitorBrands` — see [Read tools](/api/v2/docs/mcp/read-tools#get-competitor-brands).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `after` | `String` | No | `null` | Cursor for fetching the next page of results. |
| `date` | [`DateWithZone`](/api/v2/docs/types/date-with-zone) | No | `null` | Anchor date (e.g. 2025-06-01) for the aggregation window. Defaults to today. |
| `first` | `Int` | No | `20` | Number of competitor brands to return (page size). The own-brand entry is additional. |
| `period` | [`CompetitorBrandStatsPeriod`](/api/v2/docs/types/competitor-brand-stats-period) | No | `MONTH` | Aggregation window for the metric fields (WEEK or MONTH). Defaults to MONTH. |

## Returns

A paginated connection of [`CompetitorBrand`](/api/v2/docs/types/competitor-brand) nodes. See [Pagination](/api/v2/docs/types/pagination) for the connection shape.

## Examples

### List competitor brands

Paginate the Competitor Insights brands tracked by the workspace. Page one also carries the workspace's own brand as one additional pinned entry (named "You", flagged `isOwnBrand`) so you can compute self-vs-competitor Share of Voice; `totalCount` counts tracked competitors only, so it reads one lower than the edge count on page one.

```graphql
query CompetitorBrandsDefault($first: Int, $after: String) {
  competitorBrands(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
        isOwnBrand
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

Variables:

```json
{
  "first": 10
}
```

Response — HTTP 200:

```json
{
  "data": {
    "competitorBrands": {
      "totalCount": 3,
      "edges": [
        {
          "node": {
            "id": "70540721-7435-504d-82c5-4280de442fce",
            "name": "You",
            "isOwnBrand": true
          }
        },
        {
          "node": {
            "id": "28add94e-9994-54b2-9aaa-528e6606efe9",
            "name": "Verdant Co.",
            "isOwnBrand": false
          }
        },
        {
          "node": {
            "id": "97eb8f2a-7cf3-596f-b283-08dde96550e0",
            "name": "Rootbound",
            "isOwnBrand": false
          }
        },
        {
          "node": {
            "id": "af8d50b8-978c-5ecf-ba4e-a9ebc2f4c65f",
            "name": "Fernly",
            "isOwnBrand": false
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9Db21wZXRpdG9yQnJhbmQvMjAyNC0xMi0zMVQyMzo1OTo1OC4wMDAwMDBafGFmOGQ1MGI4LTk3OGMtNWVjZi1iYTRlLWE5ZWJjMmY0YzY1Zg=="
      }
    }
  }
}
```