---
title: "Per-partner analytics report"
method: GET
path: "/api/v1/analytics"
tags: ["Partners"]
---

# Per-partner analytics report

`GET /api/v1/analytics`

## Request

- Base URL: `https://www.upgradeagent.ai`
- URL: `https://www.upgradeagent.ai/api/v1/analytics`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://www.upgradeagent.ai/api/oauth/authorize`, token URL `https://www.upgradeagent.ai/api/oauth/token`, scopes: `mcp`)
  - HTTP bearer

The partner analytics product: what travelers and AI agents ask about one operator's upgrade program (by intent and route), the AI-check → bid → paid funnel by channel, the agent mix, AI visibility (share of answer per engine, who gets cited instead, what agents say, where answers are wrong), open content gaps/drift, and observed bid ranges. A partner-scoped token (the `partner` claim) is locked to its own operator and must NOT pass `partner`; an unscoped token must pass `partner`. Same object the MCP `partner_question_insights` tool returns in structuredContent.

## Query parameters

- `partner` string: Slug, IATA code, or operator name — required for unscoped tokens, rejected for partner-scoped tokens.
- `window` '7d' | '30d' | '90d': Report window.

## Response `200`

The report.

- PartnerAnalytics: Per-partner analytics report: demand, conversion, agent mix, AI visibility, content, observed pricing. Every section is empty-safe and carries a `note` when its source had nothing in the window. PII-free: question text is masked at capture.
  - `partner` object, required
    - `slug` string, required
    - `name` string, required
    - `code` string, required: IATA / operator code.
    - `vertical` string, required
  - `window` object, required
    - `key` '7d' | '30d' | '90d', required
    - `days` integer, required
    - `from` string, required
    - `to` string, required
  - `generatedAt` string, required
  - `headline` object, required
    - `questions` integer, required
    - `aiChecks` integer, required
    - `bids` integer, required
    - `paid` integer, required
    - `shareOfAnswer` number, nullable, required: Share of answer-engine answers that cited or mentioned Upgrade Agent for prompts about this partner; null when nothing was observed.
  - `demand` object, required
    - `total` integer, required: Questions about this partner in the window, excluding Upgrade Agent's own traffic and synthetic test rows.
    - `excluded` object, required
      - `internal` integer, required
      - `test` integer, required
    - `byIntent` Count[], required
      - `name` string, required
      - `count` integer, required
    - `byChannel` Count[], required
      - `name` string, required
      - `count` integer, required
    - `byRoute` object[], required
      - `route` string, required: e.g. YYZ–LHR
      - `origin` string, required
      - `destination` string, required
      - `count` integer, required
    - `withRoute` integer, required
    - `topQuestions` QuestionFreq[], required
      - `query` string, required: PII-masked question text.
      - `count` integer, required
      - `avgQuality` number, required: Mean judge quality 0–1.
    - `weakAnswers` QuestionFreq[], required
      - `query` string, required: PII-masked question text.
      - `count` integer, required
      - `avgQuality` number, required: Mean judge quality 0–1.
    - `trend` object, required
      - `bucket` 'day' | 'week', required
      - `points` object[], required
        - `start` string, required: ISO date
        - `questions` integer, required
        - `checks` integer, required
    - `note` string
  - `conversion` object, required
    - `steps` object[], required
      - `stage` 'checked' | 'eligible' | 'staged' | 'paid' | 'accepted', required
      - `label` string, required
      - `count` integer, required
      - `stepRate` number, required
    - `declined` integer, required
    - `cancelled` integer, required
    - `paidConversionRate` number, required: paid / eligible
    - `bidRate` number, required: staged / eligible
    - `byChannel` object[], required
      - `channel` 'web' | 'mcp' | 'rest' | 'mcp-partner' | 'widget' | 'other', required
      - `label` string, required
      - `checked` integer, required
      - `eligible` integer, required
      - `staged` integer, required
      - `paid` integer, required
      - `accepted` integer, required
    - `offersPresented` integer, required
    - `widgetRenders` integer, required
    - `note` string
  - `agents` object, required
    - `total` integer, required
    - `byTier` object, required
      - `verified` integer, required
      - `declared` integer, required
      - `unknown` integer, required
    - `blocked` integer, required
    - `families` object[], required
      - `agent` string, required
      - `tier` string, required
      - `requests` integer, required
      - `blocked` integer, required
    - `clients` Count[], required
      - `name` string, required
      - `count` integer, required
    - `blocks` object[], required
      - `reason` string, required
      - `count` integer, required
    - `note` string
  - `visibility` object, required
    - `observations` integer, required
    - `prompts` integer, required
    - `runs` integer, required
    - `shareOfAnswer` number, nullable, required
    - `cited` integer, required
    - `mentioned` integer, required
    - `namedRate` number, nullable, required: Share of answers that named the partner.
    - `byProvider` object[], required
      - `provider` string, required
      - `answered` integer, required
      - `cited` integer, required
      - `mentioned` integer, required
      - `share` number, required
      - `namedRate` number, required
    - `citedInstead` object[], required
      - `domain` string, required
      - `bucket` string, required
      - `count` integer, required
    - `trend` object[], required
      - `askedAt` string, required
      - `n` integer, required
      - `share` number, required
    - `whatAgentsSay` AgentExcerpt[], required
      - `provider` string, required
      - `prompt` string, required
      - `excerpt` string, required: PII-masked excerpt of the engine's answer.
      - `cited` boolean, required
      - `askedAt` string, required
    - `whereWrong` object, required
      - `community` object[], required
        - `claim` string, required
        - `reason` string, required
        - `canonical` string, nullable, required
        - `category` string, required
        - `url` string, required
        - `subreddit` string, required
        - `title` string, required
        - `createdAt` string, required
      - `forReview` object[], required
        - `provider` string, required
        - `prompt` string, required
        - `excerpt` string, required: PII-masked excerpt of the engine's answer.
        - `cited` boolean, required
        - `askedAt` string, required
        - `reason` string, required
      - `communityMentions` integer, required
    - `note` string
  - `content` object, required
    - `gaps` object[], required
      - `partner` string, nullable
      - `intent` string, required
      - `representativeQuery` string, required
      - `count` integer, required
      - `avgQuality` number, required
      - `poorCount` integer, required
      - `examples` string[], required
      - `score` number, required
      - `sources` string[]
      - `providers` string[]
    - `drift` object[], required
      - `id` integer, required
      - `partner` string, required
      - `canonicalQuestionId` string, required
      - `sourceUrl` string, nullable, required
      - `detectedAt` string, required
      - `reason` string, required
    - `publishedCanonical` integer, required
    - `note` string
  - `pricing` object, required
    - `bands` object[], required
      - `upgradeType` string, required
      - `label` string, required
      - `currency` string, required
      - `low` number, required
      - `typical` number, required
      - `high` number, required
      - `samples` integer, required
    - `byRoute` object[], required
      - `route` string, required
      - `upgradeType` string, required
      - `label` string, required
      - `currency` string, required
      - `low` number, required
      - `typical` number, required
      - `high` number, required
      - `samples` integer, required
    - `samples` integer, required
    - `observedFrom` string, nullable, required
    - `observedTo` string, nullable, required
    - `note` string
  - `notes` string[], required: Data-availability notes (a source unavailable in this window).

## Other responses

- `400`: `partner` missing for an unscoped token, or invalid window.
- `401`: Missing, invalid, expired, or revoked bearer token. The WWW-Authenticate challenge points at the OAuth protected-resource metadata.
- `403`: A partner-scoped token passed `partner`.
- `404`: Not a confirmed partner.
- `429`: Per-caller rate limit exceeded.

---

[API](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api.md) · [All operations](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/revisions/fbed715712c1?raw)