---
title: "Get brand matchups (v3)"
method: GET
path: "/api/v1/experience/brand-matchups-v3/{id}"
tags: ["experience"]
deprecated: true
---

# Get brand matchups (v3)

`GET /api/v1/experience/brand-matchups-v3/{id}`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/experience/brand-matchups-v3/{id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

> **Deprecated.**

Deprecated: no successor. The Brands map no longer reads a matchup: a competitor opens its record and why we won and lost (experience.competitor-reasons.get.v2). This version still answers one competitor's matchup from an Experience campaign's Brands map, under the same window and segments: the matched pairs cut by product (revenue line), each with its record of pairs won and lost, and the journeys that failed on the campaign's website while the same customer's goal passed on the competitor's, each with its two replays, over the pairs dated in the 30 UTC days ending with the map's results.asOf, its Experience dollars at each product's point (its AI-influenced market ÷ 100).

## Path parameters

- `id` string, uuid, required: The Experience campaign's id

## Query parameters

- `from` string, date-time: The window's start; with to, or neither for all time
- `to` string, date-time: The window's end; with from, or neither for all time
- `widenWhenEmpty` boolean: When no day of the window has one of the campaign's interactions in its 30 days, read all time instead (dateScope.widenedToAllTime says so). Otherwise such a window reports dateScope.outOfRange.
- `segments` string[]: Customer-level entries as axis:id (ids from experience_campaign_segments_get), ANDed across axes; empty reads the whole cohort. Every customer attribute narrows by its own buckets, a store by its customers. An agent entry names one of point11, dots, spark, muse, grok_bot and narrows every figure to that agent's visits (scopeAgent states it); one at most, and with none every agent's visits are read together.
- `agent` 'point11' | 'dots' | 'spark' | 'muse' | 'grok_bot': The segment scope's agent entry (the object form's {axis: agent}): every figure is of that agent's visits alone; absent reads every agent's
- `competitor` string, required: A competitor's website id, from experience_brand_maps_get_v4's competitors[].id

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- ExperienceBrandMatchupsGetV3Response
  - `datasetKey` string, nullable, required: Names what the matchup was read from, as experience.brand-maps.get's map.datasetKey does: equal while both describe the same window, website and segment scope. Null when the scope holds no interaction or website to read
  - `matchup` object, nullable, required: Null when the scope holds no interaction or website to read
    - `competitor` ExperienceCompetitorsItem, required
      - `id` string, required: The competitor's website id, as destinations[].id names it
      - `name` string, required
      - `matchedPairs` integer, required: Matched pairs: one visit to the campaign's website and the same customer's visit to the competitor's in the same cycle, on the same device. Against one competitor a pair is one journey of the campaign's website
      - `customers` integer, required: Distinct customers behind the matched pairs
      - `wins` integer, required: The matched pairs the campaign's website won: its journey passed and the competitor's failed, or both passed and its journey earned more stars
      - `losses` integer, required: The matched pairs the competitor won, by the same rule. The rest decide nothing (both failed, equal stars, a pass with no stars, or a failure blamed on the shopper), so wins plus losses can be fewer than matchedPairs, and the record can point the other way from gapPts
      - `ours` object, required: The campaign's own website over the matched pairs only, so it can differ from the website's own score
        - `experienceScore` number, nullable, required: The Experience Score of this side of the matched pairs, 0 to 100, valued as experience.campaign-analytics.get values a segment's; null when it has none to claim
        - `passRatePct` number, nullable, required: The site pass rate over this side of the matched pairs, 0 to 100
        - `averageStars` number, nullable, required: Mean stars over this side's rated journeys in the matched pairs
        - `judgedJourneys` integer, required: This side's journeys in the pass rate's denominator: all but the failures blamed on the shopper
      - `theirs` object, required
        - `experienceScore` number, nullable, required: The Experience Score of this side of the matched pairs, 0 to 100, valued as experience.campaign-analytics.get values a segment's; null when it has none to claim
        - `passRatePct` number, nullable, required: The site pass rate over this side of the matched pairs, 0 to 100
        - `averageStars` number, nullable, required: Mean stars over this side's rated journeys in the matched pairs
        - `judgedJourneys` integer, required: This side's journeys in the pass rate's denominator: all but the failures blamed on the shopper
      - `gapPts` number, nullable, required: Our score less theirs, in points; null unless both sides have a score
      - `experienceUsd` number, nullable, required: The match's Experience dollars, plus or minus: a competitor's across the business's products, its revenue lines (its parts of the lines added up, so their sign can differ from gapPts's), or a line's against one competitor; null without a worth or a gap to value
      - `valuedPairs` integer, required: The matched pairs experienceUsd stands on: a competitor's on the products (revenue lines) with a worth, which can be fewer than matchedPairs; a line's own. 0 without dollars
      - `valuedCustomers` integer, required: Distinct customers behind valuedPairs: the sample the dollars' precision reads, as customers is the gap's. 0 without dollars
      - `size` number, required: What the match weighs on the map, in sizedBy's unit
    - `sizedBy` 'usd' | 'journeys', required: The unit of every size: usd (the size of experienceUsd, whichever way it points) when any match has dollars, else matched pairs
    - `lines` object[], required: The match cut by the product (revenue line) of the website's own customers, most matched pairs first
      - `id` string, required
      - `label` string, required
      - `matchedPairs` integer, required: Matched pairs: one visit to the campaign's website and the same customer's visit to the competitor's in the same cycle, on the same device. Against one competitor a pair is one journey of the campaign's website
      - `customers` integer, required: Distinct customers behind the matched pairs
      - `wins` integer, required: The matched pairs the campaign's website won: its journey passed and the competitor's failed, or both passed and its journey earned more stars
      - `losses` integer, required: The matched pairs the competitor won, by the same rule. The rest decide nothing (both failed, equal stars, a pass with no stars, or a failure blamed on the shopper), so wins plus losses can be fewer than matchedPairs, and the record can point the other way from gapPts
      - `ours` object, required: The campaign's own website over the matched pairs only, so it can differ from the website's own score
        - `experienceScore` number, nullable, required: The Experience Score of this side of the matched pairs, 0 to 100, valued as experience.campaign-analytics.get values a segment's; null when it has none to claim
        - `passRatePct` number, nullable, required: The site pass rate over this side of the matched pairs, 0 to 100
        - `averageStars` number, nullable, required: Mean stars over this side's rated journeys in the matched pairs
        - `judgedJourneys` integer, required: This side's journeys in the pass rate's denominator: all but the failures blamed on the shopper
      - `theirs` object, required
        - `experienceScore` number, nullable, required: The Experience Score of this side of the matched pairs, 0 to 100, valued as experience.campaign-analytics.get values a segment's; null when it has none to claim
        - `passRatePct` number, nullable, required: The site pass rate over this side of the matched pairs, 0 to 100
        - `averageStars` number, nullable, required: Mean stars over this side's rated journeys in the matched pairs
        - `judgedJourneys` integer, required: This side's journeys in the pass rate's denominator: all but the failures blamed on the shopper
      - `gapPts` number, nullable, required: Our score less theirs, in points; null unless both sides have a score
      - `experienceUsd` number, nullable, required: The match's Experience dollars, plus or minus: a competitor's across the business's products, its revenue lines (its parts of the lines added up, so their sign can differ from gapPts's), or a line's against one competitor; null without a worth or a gap to value
      - `valuedPairs` integer, required: The matched pairs experienceUsd stands on: a competitor's on the products (revenue lines) with a worth, which can be fewer than matchedPairs; a line's own. 0 without dollars
      - `valuedCustomers` integer, required: Distinct customers behind valuedPairs: the sample the dollars' precision reads, as customers is the gap's. 0 without dollars
      - `size` number, required: What the match weighs on the map, in sizedBy's unit
    - `lostHereJourneys` integer, required: Journeys dated in the 30 days ending with results.asOf that failed on the campaign's website (not counting a failure blamed on the shopper) while the same customer's goal passed on the competitor's: never fewer than lostHere lists
    - `lostHere` object[], required: The first of those journeys by customer name, each with its two replays
      - `runId` string, uuid, required: The failed journey on the campaign's website
      - `competitorRunId` string, uuid, required: The passed journey on the competitor's
      - `customerName` string, required
      - `device` string, required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/36a84c7aca11?raw)