Query

competitorBrands

List Competitor Insights brands tracked by the current workspace, newest first. Each brand carries aggregate metrics over a period/date window (default month). The first page also returns the workspace's own brand as one pinned node, flagged isOwnBrand. It comes in addition to up to first competitor brands, so one query gives self-vs-competitor Share of Voice. totalCount counts tracked competitor brands only. Pair with competitorBrandItems(brandId:, filter:, …) to paginate a brand's media items. When aggregate metrics are unavailable, the roster data still returns, with a SERVICE_UNAVAILABLE error. Match on extensions.code and retry later.

Paginated · weighted cost MCP: getCompetitorBrands

Arguments

Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.

after String default null: Cursor for fetching the next page of results.
date DateWithZone default null: Anchor date (e.g. 2025-06-01) for the aggregation window. Defaults to the latest month whose data is complete (for WEEK, the latest complete week). A date whose window ends after the latest selectable day is moved back to the latest complete window, not rejected.
first Int default 20: Number of competitor brands to return (page size). The own-brand entry is additional.
includeProvisionalDays Boolean default false: Requires postDate. Explicitly acknowledge that engagement figures may still grow and allow the window through the latest day Competitor Insights lets the workspace select, including Early-access days. Omitted, null or false uses the latest settled day. A workspace without Early access gains no additional days. Out-of-bounds windows are rejected, not shortened.
period CompetitorBrandStatsPeriod default MONTH: Aggregation window for the metric fields (WEEK or MONTH). Defaults to MONTH.
MONTH: Aggregate over the month containing the anchor date.
WEEK: Aggregate over the week containing the anchor date.
postDate FilterDateRangeInput default null: Inclusive post-date window in whole UTC days, an alternative to period and date. Both bounds are required. It must lie within Competitor Insights data through the latest settled UTC day (currently today minus 8 days) and span at most 3 months. Out-of-bounds windows are rejected, not shortened. The previous period covers as many whole months before it when it spans whole months. Otherwise it is the equal-length window before it. A previous period that starts before Competitor Insights data is cut to start on that date, so read its from. Passing period or date with it returns an INVALID_INPUT error.
from DateTime: Inclusive lower bound (ISO 8601). Omit for no lower bound.
to DateTime: Inclusive upper bound (ISO 8601). Omit for no upper bound.

Returns

A paginated connection of CompetitorBrand nodes. See Pagination for the connection shape.

edges [CompetitorBrandEdge!]!: List of edges with cursors.
cursor String!: Cursor for this node.
node CompetitorBrand!: The competitor brand.
displayName String!: Name the Archive app shows for the brand. Same as name for competitor brands. For the own-brand entry it is the name of the brand linked as the workspace's own brand, or "You" when no brand is linked.
earnedMediaValue Float: Estimated earned media value (USD) over the window. Null when unavailable or no data.
engagementsTotal Float: Total engagements (likes + comments + shares, …) over the window. Null when unavailable or no data.
id ID!: Unique identifier for the brand in Archive's system. For the workspace's own-brand entry this is a stable, workspace-scoped id (the same across requests).
impressions Float: Merged view/play impressions over the window. Null when unavailable or no data.
influencersCount Int: Distinct influencers counted over the window. Null when unavailable or no data.
isOwnBrand Boolean!: True for the workspace's own-brand entry, false for tracked competitor brands. Use this to compute self-vs-competitor Share of Voice.
name String!: Brand name. The workspace's own-brand entry is named "You".
ownMetricsHasData Boolean: For the own-brand entry only: true when ownMetricsStatus is AVAILABLE and the window has own-brand data, false when it is AVAILABLE but the window has no own-brand data (every metric field is then null: treat it as missing, not zero). Null for competitor brands and when ownMetricsStatus is UNAVAILABLE.
ownMetricsStatus CompetitorBrandOwnMetricsStatus: For the own-brand entry only (null for competitors): AVAILABLE when metrics were computed (null metric fields then mean no data in the window, distinct from zero), UNAVAILABLE when they could not be computed. The accompanying error code says whether to retry.
AVAILABLE: Own-brand metrics were computed. Null metric fields mean no data in this window (distinct from zero).
UNAVAILABLE: Own-brand metrics could not be computed. The accompanying error explains whether to retry; metric fields are null.
postsCount Int: Number of posts counted over the window. Null when unavailable or no data.
previousPeriod CompetitorBrandPeriodStats: The same metrics over the window before the requested one, for period-over-period change. Null when metrics are unavailable or that window lies entirely before Competitor Insights data. A window that starts earlier is cut to start on that date, so read its from.
earnedMediaValue Float: Estimated earned media value (USD) over the window. Null when unavailable or no data.
engagementsTotal Float: Total engagements (likes + comments + shares, …) over the window. Null when unavailable or no data.
from DateTime!: Start of the window (inclusive, UTC).
impressions Float: Merged view/play impressions over the window. Null when unavailable or no data.
influencersCount Int: Distinct influencers counted over the window. Null when unavailable or no data.
postsCount Int: Number of posts counted over the window. Null when unavailable or no data.
provenance [CompetitorBrandMetricProvenance!]: Captured and estimated parts of each metric total over the window. Null when unavailable, when there is no data, or when the own-brand entry has no breakdown.
capturedValue Float!: Part of the total that Archive captured from posts.
contributions [CompetitorBrandEstimationContribution!]!: Estimated amounts in the total, one per estimation method. Empty when the total is all captured.
count Int!: Number of posts or Stories the method estimated.
estimatedValue Float!: Amount this method adds to the total.
estimationMethod CompetitorBrandEstimationMethod! Continue in CompetitorBrandEstimationMethod →: Method that produced this estimated amount.
median Float: Median value the estimate starts from. Null for methods that use no median.
multiplier Float!: Fixed factor the method applies.
displayedTotal Float!: Total as the metric field reports it, estimates included.
metric CompetitorBrandProvenanceMetric!: Metric this entry describes.
EARNED_MEDIA_VALUE: The earnedMediaValue total.
ENGAGEMENTS_TOTAL: The engagementsTotal total.
IMPRESSIONS: The impressions total.
POSTS_COUNT: The postsCount total.
REACH: The reach total.
reach Float: Summed follower reach over the window. Null when unavailable or no data.
to DateTime!: End of the window (inclusive, UTC): the last second of its last day.
provenance [CompetitorBrandMetricProvenance!]: Captured and estimated parts of each metric total over the window. Totals can include estimates for posts Archive could not measure. Null when unavailable, when there is no data, or when the own-brand entry has no breakdown.
capturedValue Float!: Part of the total that Archive captured from posts.
contributions [CompetitorBrandEstimationContribution!]!: Estimated amounts in the total, one per estimation method. Empty when the total is all captured.
count Int!: Number of posts or Stories the method estimated.
estimatedValue Float!: Amount this method adds to the total.
estimationMethod CompetitorBrandEstimationMethod!: Method that produced this estimated amount.
IGM1_POST_MULTIPLIER: Estimates Instagram mention posts and Reels missed for brands without a connected account.
STORY_MEDIAN_MULTIPLIER: Adds the median value of captured Stories, times a fixed factor, for each Story without metrics.
median Float: Median value the estimate starts from. Null for methods that use no median.
multiplier Float!: Fixed factor the method applies.
displayedTotal Float!: Total as the metric field reports it, estimates included.
metric CompetitorBrandProvenanceMetric!: Metric this entry describes.
EARNED_MEDIA_VALUE: The earnedMediaValue total.
ENGAGEMENTS_TOTAL: The engagementsTotal total.
IMPRESSIONS: The impressions total.
POSTS_COUNT: The postsCount total.
REACH: The reach total.
reach Float: Summed follower reach over the window. Null when unavailable or no data.
nodes [CompetitorBrand!]!: List of competitor brands.
displayName String!: Name the Archive app shows for the brand. Same as name for competitor brands. For the own-brand entry it is the name of the brand linked as the workspace's own brand, or "You" when no brand is linked.
earnedMediaValue Float: Estimated earned media value (USD) over the window. Null when unavailable or no data.
engagementsTotal Float: Total engagements (likes + comments + shares, …) over the window. Null when unavailable or no data.
id ID!: Unique identifier for the brand in Archive's system. For the workspace's own-brand entry this is a stable, workspace-scoped id (the same across requests).
impressions Float: Merged view/play impressions over the window. Null when unavailable or no data.
influencersCount Int: Distinct influencers counted over the window. Null when unavailable or no data.
isOwnBrand Boolean!: True for the workspace's own-brand entry, false for tracked competitor brands. Use this to compute self-vs-competitor Share of Voice.
name String!: Brand name. The workspace's own-brand entry is named "You".
ownMetricsHasData Boolean: For the own-brand entry only: true when ownMetricsStatus is AVAILABLE and the window has own-brand data, false when it is AVAILABLE but the window has no own-brand data (every metric field is then null: treat it as missing, not zero). Null for competitor brands and when ownMetricsStatus is UNAVAILABLE.
ownMetricsStatus CompetitorBrandOwnMetricsStatus: For the own-brand entry only (null for competitors): AVAILABLE when metrics were computed (null metric fields then mean no data in the window, distinct from zero), UNAVAILABLE when they could not be computed. The accompanying error code says whether to retry.
AVAILABLE: Own-brand metrics were computed. Null metric fields mean no data in this window (distinct from zero).
UNAVAILABLE: Own-brand metrics could not be computed. The accompanying error explains whether to retry; metric fields are null.
postsCount Int: Number of posts counted over the window. Null when unavailable or no data.
previousPeriod CompetitorBrandPeriodStats: The same metrics over the window before the requested one, for period-over-period change. Null when metrics are unavailable or that window lies entirely before Competitor Insights data. A window that starts earlier is cut to start on that date, so read its from.
earnedMediaValue Float: Estimated earned media value (USD) over the window. Null when unavailable or no data.
engagementsTotal Float: Total engagements (likes + comments + shares, …) over the window. Null when unavailable or no data.
from DateTime!: Start of the window (inclusive, UTC).
impressions Float: Merged view/play impressions over the window. Null when unavailable or no data.
influencersCount Int: Distinct influencers counted over the window. Null when unavailable or no data.
postsCount Int: Number of posts counted over the window. Null when unavailable or no data.
provenance [CompetitorBrandMetricProvenance!]: Captured and estimated parts of each metric total over the window. Null when unavailable, when there is no data, or when the own-brand entry has no breakdown.
capturedValue Float!: Part of the total that Archive captured from posts.
contributions [CompetitorBrandEstimationContribution!]!: Estimated amounts in the total, one per estimation method. Empty when the total is all captured.
count Int!: Number of posts or Stories the method estimated.
estimatedValue Float!: Amount this method adds to the total.
estimationMethod CompetitorBrandEstimationMethod!: Method that produced this estimated amount.
IGM1_POST_MULTIPLIER: Estimates Instagram mention posts and Reels missed for brands without a connected account.
STORY_MEDIAN_MULTIPLIER: Adds the median value of captured Stories, times a fixed factor, for each Story without metrics.
median Float: Median value the estimate starts from. Null for methods that use no median.
multiplier Float!: Fixed factor the method applies.
displayedTotal Float!: Total as the metric field reports it, estimates included.
metric CompetitorBrandProvenanceMetric!: Metric this entry describes.
EARNED_MEDIA_VALUE: The earnedMediaValue total.
ENGAGEMENTS_TOTAL: The engagementsTotal total.
IMPRESSIONS: The impressions total.
POSTS_COUNT: The postsCount total.
REACH: The reach total.
reach Float: Summed follower reach over the window. Null when unavailable or no data.
to DateTime!: End of the window (inclusive, UTC): the last second of its last day.
provenance [CompetitorBrandMetricProvenance!]: Captured and estimated parts of each metric total over the window. Totals can include estimates for posts Archive could not measure. Null when unavailable, when there is no data, or when the own-brand entry has no breakdown.
capturedValue Float!: Part of the total that Archive captured from posts.
contributions [CompetitorBrandEstimationContribution!]!: Estimated amounts in the total, one per estimation method. Empty when the total is all captured.
count Int!: Number of posts or Stories the method estimated.
estimatedValue Float!: Amount this method adds to the total.
estimationMethod CompetitorBrandEstimationMethod!: Method that produced this estimated amount.
IGM1_POST_MULTIPLIER: Estimates Instagram mention posts and Reels missed for brands without a connected account.
STORY_MEDIAN_MULTIPLIER: Adds the median value of captured Stories, times a fixed factor, for each Story without metrics.
median Float: Median value the estimate starts from. Null for methods that use no median.
multiplier Float!: Fixed factor the method applies.
displayedTotal Float!: Total as the metric field reports it, estimates included.
metric CompetitorBrandProvenanceMetric!: Metric this entry describes.
EARNED_MEDIA_VALUE: The earnedMediaValue total.
ENGAGEMENTS_TOTAL: The engagementsTotal total.
IMPRESSIONS: The impressions total.
POSTS_COUNT: The postsCount total.
REACH: The reach total.
reach Float: Summed follower reach over the window. Null when unavailable or no data.
pageInfo PageInfo!: Pagination information.
endCursor String: Cursor for the last node in this page.
hasNextPage Boolean!: Whether there are more results after this page.
hasPreviousPage Boolean!: Whether there are results before this page.
startCursor String: Cursor for the first node in this page.
totalCount Int: Total number of competitor brands tracked by the workspace. The pinned own-brand entry (isOwnBrand: true) is not counted, so the first page returns totalCount + 1 nodes when every competitor fits on it.

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

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