Archive API docs

QUERY

competitorBrands

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.

Paginated · weighted cost MCP: getCompetitorBrands

Arguments

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 today.
first Int default: 20: Number of competitor brands to return (page size). The own-brand entry is additional.
period CompetitorBrandStatsPeriod default: MONTH: Aggregation window for the metric fields (WEEK or MONTH). Defaults to MONTH.

Returns

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

Open in explorer ↗

Values are sampled from a demo workspace — substitute your own token and workspace id.

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.

query.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
}

Headers

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

Request · cURL

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "query CompetitorBrandsDefault($first: Int, $after: String) {\n  competitorBrands(first: $first, after: $after) {\n    totalCount\n    edges {\n      node {\n        id\n        name\n        isOwnBrand\n      }\n    }\n    pageInfo {\n      hasNextPage\n      endCursor\n    }\n  }\n}",
  "variables": {
    "first": 10
  }
}'

Request · Node.js

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `query CompetitorBrandsDefault($first: Int, $after: String) {
  competitorBrands(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
        isOwnBrand
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}`,
    variables: {
      "first": 10
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

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

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "first" => 10 } }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

Request · Python

import json
import requests

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

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"first": 10}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK41 lines · expand

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