---
title: "Get engine reports (v4)"
method: GET
path: "/api/v1/discovery/engine-reports-v4/{id}"
tags: ["discovery"]
---

# Get engine reports (v4)

`GET /api/v1/discovery/engine-reports-v4/{id}`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/discovery/engine-reports-v4/{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`)

Read a campaign's AI engine report: brand share, win rate, best topic, and win and loss drivers for each AI assistant measured, over the campaign's results window (`scope.window`): every value as of the window's as-of day, averaged over the conversations dated in the 30 days ending it, every trend one point per day (null for a day whose window holds no conversation the value counts), and every change the value minus its value 30 days before the as-of day (null without one).

## Path parameters

- `id` string, uuid, required: Discovery campaign id.

## Query parameters

- `dateRange` string, nullable: Result window: `all`, a preset id, or `yyyy-MM-dd..yyyy-MM-dd`. Omit for the campaign's default window.
- `brandPerspective` string, nullable: Read the results as this brand (one of the campaign's brands). Omit for your own.
- `segments` string[]: Narrows the read to these segments, ANDed: one `axis:id` per axis (any number of distinct `customer:` entries), in canonical axis order. Empty reads the whole dispatch.

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- DiscoveryEngineReportsGetV4Response
  - `scope` DiscoveryScope, required
    - `campaignId` string, required
    - `state` 'ready' | 'running' | 'failed' | 'out-of-range' | 'no-campaign', required: `ready` carries results; every other state carries none.
    - `failureReason` string, nullable, required
    - `perspective` object, nullable, required: The brand lens applied; null when the report honors no lens or carries no results.
      - `brand` string, required: The brand the results were read as.
      - `isOwnBrand` boolean, required: Whether that brand is the campaign's own.
    - `window` object, nullable, required: The results window; null unless `state` is `ready`.
      - `from` string, date, required: The first UTC day a trend plots: the range's, never before the first interaction.
      - `to` string, date, required: The last UTC day a trend plots: the range's end, never past today.
      - `asOf` string, date, required: The UTC day every single value is as of: its value is the average over the campaign's interactions dated in the 30 days ending with it. The range's end, or, when those 30 days hold none, the last day with an interaction.
      - `comparedTo` string, date, required: The day a change compares with: 30 days before asOf.
      - `interactionCount` integer, required: The interactions dated in the 30 days ending asOf, under the scope.
      - `customerCount` integer, required: The distinct customers of those interactions.
  - `report` object, nullable, required: Null unless `scope.state` is `ready`.
    - `brandScopes` DiscoveryBrandScopes, nullable
      - `options` object[], required
        - `id` string, required
        - `name` string, required
        - `relationshipType` 'target' | 'competitor' | 'partner' | 'hybrid' | 'influencer' | 'adjacent' | 'unrelated' | 'unknown', required
        - `isTarget` boolean, required
      - `segments` object[], required
        - `id` string, required
        - `name` string, required
        - `color` string, required
        - `markerColor` string
        - `barColor` string
        - `relationshipType` union
          - 'target' | 'competitor' | 'partner' | 'hybrid' | 'influencer' | 'adjacent' | 'unrelated' | 'unknown'
          - 'replacement_competitor' | 'decision_influencer'
        - `topCompetitor` string, nullable
        - `topBrands` string[]
        - `bestTopic` string, nullable
        - `isLeader` boolean
        - `parentId` string, nullable
        - `childIds` string[]
        - `geoRegion` string, nullable
        - `geoResolution` 'countries' | 'provinces' | 'postal', nullable
      - `includeZeroSegments` boolean, required
      - `metricsByBrandId` object, required
    - `segmentCountSeries` object[], required: Segments with a conversation in each day's window; null where it holds no conversation in scope.
      - `day` string, date, required: UTC day; the value is its trailing 30-day window's.
      - `value` number, nullable, required: Null where that window holds no interaction.
    - `segmentCountDelta` number, nullable, required: The segment count minus its count 30 days before the as-of day; null when that window holds no conversation in scope.
    - `conversationCount` number, required: The as-of window's conversations, narrowed like every other figure.
    - `revenueCoverage` object, required
      - `scope` 'locations': Location estimates may overlap markets.
      - `status` 'none' | 'partial' | 'complete', required
      - `includedLineCount` number, required
      - `totalLineCount` number, required
      - `coveredConversationCount` number, required
      - `totalConversationCount` number, required
      - `coveragePct` number, required
    - `segments` object[], required: The segments every figure was narrowed to, ANDed; empty is the whole campaign.
      - `axis` 'audience' | 'channel' | 'market' | 'age' | 'householdIncome' | 'education' | 'lifeStage' | 'areaType' | 'companySize' | 'buyerRole' | 'seniority' | 'occupation' | 'job' | 'triggerType' | 'intentStage' | 'language' | 'gender' | 'product' | 'engine' | 'competitor' | 'topic' | 'sentiment' | 'store' | 'customer', required: A pinned customer attribute (audience, channel, age, …); conversation evidence (`product` for the business's products, `engine`, `competitor`, `topic`, `sentiment`); or one `store` or `customer`.
      - `id` string, required: The member's id on that axis, as `discovery.segment-options.get` lists it.
    - `breaks` object[]: Days in the trends' span the campaign's conversations changed behavior version (its opening questions, customer replies or interview schedule), each with what changed; absent with none.
      - `day` string, date, required
      - `label` string, required
    - `engines` object[], required
      - `id` string, required
      - `name` string, required
      - `shortName` string, required
      - `color` string, required
      - `vsPortfolioPts` number, required: Brand win rate minus the campaign's all-up brand win rate, in points.
      - `bestTopic` string, nullable, required
      - `brandShare` number, required: Brand share (%).
      - `brandShareDelta` number, nullable, required: The value minus its value 30 days before the window's as-of day; null when that window holds none of the segment's conversations.
      - `winRate` number, required: Brand win rate (%).
      - `winRateDelta` number, nullable, required: The value minus its value 30 days before the window's as-of day; null when that window holds none of the segment's conversations.
      - `customers` integer, required: Distinct customers of the segment's as-of window conversations: the sample its share and win rate stand on.
      - `earlierCustomers` integer, required: Distinct customers of the segment's conversations in the window 30 days before, which its changes compare with; 0 when that window holds none.
      - `revenueInfluencedUsd` number, nullable: Target revenue influenced over the as-of window; absent under a competitor lens.
      - `revenueInfluenceableUsd` number, nullable
      - `prompts` number, required: The as-of window's conversations the engine answered.
      - `models` string[], required: The models those conversations recorded (Point11 ran each in the assistant's place), most conversations first.
    - `drivers` object[], required
      - `engineId` string, required
      - `kind` 'win' | 'loss', required
      - `label` string, required: The reason, as the model wrote it.
      - `count` number, required: Conversations of the as-of window citing the reason.
      - `customers` integer, required: Distinct customers of the as-of window's conversations its kind counts from (wins for a win reason, losses for a loss reason): the sample its count stands on.
      - `series` object[]: Its count in each day's window; null where the window holds none of its segment's conversations.
        - `day` string, date, required: UTC day; the value is its trailing 30-day window's.
        - `value` number, nullable, required: Null where that window holds no interaction.
    - `engineSeries` object, required: Keyed by engine id.

## 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/5241805fe425?raw)