# competitorBrandItems

Query

Paginate Competitor Insights posts for a brand within a required `filter.takenAt` window. Posts for a given month become queryable on day 9 of the following month.

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

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `after` | `String` | No | `null` | Opaque cursor for fetching the next page of results. Cursors are positional: reuse one only with identical `brandId`, `filter` and `sorting` arguments. A malformed cursor, including one minted by an earlier release, is rejected with an `Invalid cursor` error. Pagination depth is capped at 10,000 posts per query; narrow the `takenAt` window to page beyond that. |
| `brandId` | `ID!` | Yes | — | Competitor Insights brand UUID. If the brand is not tracked by the current workspace, the query returns an empty connection. |
| `filter` | [`CompetitorBrandItemFilterInput!`](/api/v2/docs/types/competitor-brand-item-filter-input) | Yes | — | Filter criteria. A `takenAt` time window is required; unbounded queries are not supported. |
| `first` | `Int` | No | `20` | Number of posts to return (page size). |
| `sorting` | [`[CompetitorBrandItemSortingInput!]`](/api/v2/docs/types/competitor-brand-item-sorting-input) | No | `[{sortKey: TAKEN_AT, sortOrder: DESC}]` | Sort configuration. Currently accepts a list of at most one entry; multiple entries are rejected. The list shape exists for forward compatibility: a future release may honor compound sort additively without a breaking schema change. Defaults to `[{ sortKey: TAKEN_AT, sortOrder: DESC }]` when omitted. `EARNED_MEDIA_VALUE` ranks posts as a single ordering across the entire requested `takenAt` window. Ties are broken by the post identifier, ascending. |

## Returns

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

## Examples

### List a competitor brand's posts

Paginate a brand's posts within a required takenAt window.

```graphql
query CompetitorBrandItemsDefault($brandId: ID!, $filter: CompetitorBrandItemFilterInput!, $first: Int) {
  competitorBrandItems(brandId: $brandId, filter: $filter, first: $first) {
    totalCount
    edges {
      node {
        id
        provider
        type
        caption
        takenAt
        originalUrl
        currentEngagement {
          likes
          comments
          views
          earnedMediaValue
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

Variables:

```json
{
  "brandId": "28add94e-9994-54b2-9aaa-528e6606efe9",
  "filter": {
    "takenAt": {
      "from": "2024-08-01T00:00:00Z",
      "to": "2024-12-31T00:00:00Z"
    }
  },
  "first": 10
}
```

Response — HTTP 200:

```json
{
  "data": {
    "competitorBrandItems": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "45c2aca7-5351-5774-8196-b9346e58a099",
            "provider": "INSTAGRAM",
            "type": "REEL",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-30T00:00:00Z",
            "originalUrl": "https://instagram.com/p/docs-item-29",
            "currentEngagement": {
              "likes": "390",
              "comments": "39",
              "views": "0",
              "earnedMediaValue": "780"
            }
          }
        },
        {
          "node": {
            "id": "037514fd-8da6-5fc4-ab1f-57074132ad11",
            "provider": "YOUTUBE",
            "type": "POST",
            "caption": "Post #28 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-29T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-28",
            "currentEngagement": {
              "likes": "380",
              "comments": "38",
              "views": "0",
              "earnedMediaValue": "760"
            }
          }
        },
        {
          "node": {
            "id": "35e07388-1dc7-5548-b990-0fa5200dd19e",
            "provider": "TIKTOK",
            "type": "SHORT",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-28T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-27",
            "currentEngagement": {
              "likes": "370",
              "comments": "37",
              "views": "0",
              "earnedMediaValue": "740"
            }
          }
        },
        {
          "node": {
            "id": "e0d46669-65b0-5b97-ba72-7d6f6a8b3099",
            "provider": "INSTAGRAM",
            "type": "STORY",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-27T00:00:00Z",
            "originalUrl": null,
            "currentEngagement": {
              "likes": "360",
              "comments": "36",
              "views": "0",
              "earnedMediaValue": "720"
            }
          }
        },
        {
          "node": {
            "id": "bd465566-b4a2-508a-a66d-f0ad5b740aed",
            "provider": "YOUTUBE",
            "type": "REEL",
            "caption": "Reel #25 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-26T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-25",
            "currentEngagement": {
              "likes": "350",
              "comments": "35",
              "views": "0",
              "earnedMediaValue": "700"
            }
          }
        },
        {
          "node": {
            "id": "284c38ea-a14f-51a9-adc4-ec3a2779c5de",
            "provider": "TIKTOK",
            "type": "POST",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-25T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-24",
            "currentEngagement": {
              "likes": "340",
              "comments": "34",
              "views": "0",
              "earnedMediaValue": "680"
            }
          }
        },
        {
          "node": {
            "id": "f803ccf8-ebd1-5c7a-8ba4-fc18c1a4d914",
            "provider": "INSTAGRAM",
            "type": "SHORT",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-24T00:00:00Z",
            "originalUrl": null,
            "currentEngagement": {
              "likes": "330",
              "comments": "33",
              "views": "0",
              "earnedMediaValue": "660"
            }
          }
        },
        {
          "node": {
            "id": "dfdb3836-77f2-5dbc-8ea7-5110924d16c0",
            "provider": "YOUTUBE",
            "type": "STORY",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-23T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-22",
            "currentEngagement": {
              "likes": "320",
              "comments": "32",
              "views": "0",
              "earnedMediaValue": "640"
            }
          }
        },
        {
          "node": {
            "id": "4b328433-86dc-593d-918a-d435836c868d",
            "provider": "TIKTOK",
            "type": "REEL",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-22T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-21",
            "currentEngagement": {
              "likes": "310",
              "comments": "31",
              "views": "0",
              "earnedMediaValue": "620"
            }
          }
        },
        {
          "node": {
            "id": "90f4b06d-bdca-5b74-871a-7c879309c9b9",
            "provider": "INSTAGRAM",
            "type": "POST",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-21T00:00:00Z",
            "originalUrl": "https://instagram.com/p/docs-item-20",
            "currentEngagement": {
              "likes": "300",
              "comments": "30",
              "views": "0",
              "earnedMediaValue": "600"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "MTA="
      }
    }
  }
}
```