Archive API docs
esc
    Jump to
    Getting started Token, first query, response Explorer Run queries in the browser items The connection most integrations start with Changelog Additions and deprecations

    Narrow by kind with a prefix — q: queries, m: mutations, t: types, g: guides, f: fields and arguments.

    Jump to examples ↓
    Query

    competitorBrand

    Return a single Competitor Insights brand by ID for the current workspace, or null if no brand with that ID is tracked here. The workspace's own-brand entry also resolves, by its stable id. Pair with competitorBrandItems(brandId:, filter:, …) to paginate the 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.

    MCP: getCompetitorBrand

    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.

    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.
    id ID! required
    Competitor Insights brand ID. Also resolves the workspace's own-brand entry by its stable id.
    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.
    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.

    Returns

    Returns CompetitorBrand.

    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.
    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.
    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.
    reach Float
    Summed follower reach over the window. Null when unavailable or no data.