Competitor Brands

Reminder: All queries on this page require the WORKSPACE-ID header. See Getting Started for setup.

Competitor Brands is Archive’s surface for tracking content posted about other brands — competitors, category leaders, anyone you want to benchmark against. The same configuration you set up in the Archive UI (Competitor Insights) drives this API surface.

This is what you see under the Competitor Insights section in the Archive UI. Learn more: Getting Started with Competitor Insights .

Read-only, minimal surface. The API exposes the list of competitor brands tracked on your workspace, a singular lookup, and the content captured for each brand. Adding, renaming, or removing brands stays in the Archive UI. Available on plans that include the Competitor Insights product.

List competitor brands


query ListCompetitorBrands {
  competitorBrands(first: 50) {
    totalCount
    nodes {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example response:


{
  "data": {
    "competitorBrands": {
      "totalCount": 5,
      "nodes": [
        { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Brand A" },
        { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "name": "Brand B" }
      ],
      "pageInfo": { "hasNextPage": false, "endCursor": "..." }
    }
  }
}

Available fields on CompetitorBrand:

Field	Type	Description
`id`	ID	Unique competitor brand identifier — use this anywhere a brand UUID is expected.
`name`	String	Competitor brand name as configured in the UI.

Other metadata (logo, category, date added, item totals, EMV totals) is not exposed. To get per-brand totals, query competitorBrandItems(brandId: ...) { totalCount } and aggregate client-side.

Using with AI:

“List all competitor brands tracked in this workspace.” “How many competitors are we tracking?”

Look up a single competitor brand


query GetCompetitorBrand($id: ID!) {
  competitorBrand(id: $id) {
    id
    name
  }
}

Returns null if the brand doesn’t exist or doesn’t belong to the requesting workspace.

Pull items captured for a brand


query CompetitorBrandItems($brandId: ID!, $from: ISO8601DateTime!, $to: ISO8601DateTime!) {
  competitorBrandItems(
    brandId: $brandId
    filter: { takenAt: { from: $from, to: $to } }
    first: 100
  ) {
    totalCount
    pageInfo { hasNextPage endCursor }
    nodes {
      id
      provider
      type
      takenAt
      caption
      originalUrl
      archivePublicUrl
      externalId
      hashtags
      mentions
      socialProfile {
        id
        accountName
        followers
        fullName
        provider
      }
      currentEngagement {
        likes
        comments
        views
        shares
        impressions
        earnedMediaValue
        linearViralityScore
      }
    }
  }
}

Required arguments:

brandId: ID! — top-level (singular). Get it from the competitorBrands query.
filter.takenAt: FilterDateRangeInput! — a { from, to } date range is required. Omitting it returns a validation error. Dates must be UTC ISO 8601 ending in Z.

Available fields on CompetitorBrandItem:

Field	Type	Description
`id`	ID	Unique item identifier
`provider`	Enum	Platform: `INSTAGRAM`, `TIKTOK`, `YOUTUBE`
`type`	Enum	Content format: `POST`, `REEL`, `STORY`, `SHORT`
`takenAt`	DateTime	Publication date (UTC)
`caption`	String	Post caption text
`originalUrl`	String	Link to the original post on the platform
`archivePublicUrl`	String	Shareable public Archive URL for this item
`externalId`	ID	Platform’s native ID (e.g. Instagram shortcode)
`hashtags`	String[]	Hashtags on the post
`mentions`	String[]	Mentions on the post — the competitor brand’s tracked handle typically appears here
`socialProfile`	Object	The social profile that posted this content (the creator, not the competitor brand)
`currentEngagement`	Object	Likes, comments, views, shares, impressions, EMV (in cents), linear virality score

Not exposed on CompetitorBrandItem (unlike the Item type used for your own UGC): mediaItemId, location, creator, customAttributes, transcriptions. If your workflow needs any of these, file a feature request via feedback.archive.com .

Using with AI:

“Pull the top 50 posts about Brand X over the last 30 days, sorted by EMV.” “How many posts mentioning Brand X were captured in May?” “For each creator that posted about Brand X this quarter, list their handle, follower count, and total impressions.”

Pull media files for competitor brand items

The mediaContents query accepts competitorBrandItemIds (alongside the existing itemIds) so you can fetch images and videos for competitor-brand content the same way you do for your own UGC. Pass exactly one of the two — itemIds for your workspace items or competitorBrandItemIds for competitor-brand items, not both.


query CompetitorBrandMedia($brandItemIds: [ID!]!) {
  mediaContents(competitorBrandItemIds: $brandItemIds) {
    ... on Image {
      id
      mediaItemId
      fileUrl
      thumbnailUrl
      width
      height
      deleted
    }
    ... on Video {
      id
      mediaItemId
      fileUrl
      thumbnailUrl
      width
      height
      deleted
      videoDuration
    }
  }
}

Always check deleted before using the URLs. mediaItemId groups carousel frames from the same post.

What’s not exposed

The competitor brands surface is intentionally minimal. The following are not available via the API and customers asking for them should be pointed to feedback.archive.com :

Mutations to add, rename, archive, or remove competitor brands — those stay in the Archive UI.
Per-brand metadata beyond id / name.
mediaItemId, location, creator, customAttributes, transcriptions on CompetitorBrandItem.
Filter by competitor brand name (only brandId is supported — discover IDs via the competitorBrands query first).