> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TARS Marketing analytics admin API

> Internal SuperAdmin contracts for the TARS Marketing mandate.

The TARS Marketing mandate reads its analytics from three internal REST
endpoints. They are available only to authenticated Scope3 SuperAdmins and are
not part of the customer-facing Buyer or Seller API.

The corresponding interface is `/tars/mandates/marketing`. It combines search
engine visibility, answer-engine visibility, website journeys, and the existing
canonical buyer-lead view. The standalone marketing admin remains available
until a later retirement slice.

## Authentication and errors

All three endpoints use the normal API session or bearer-token authentication
and require the `superAdmin` role.

* Invalid query parameters return `400`.
* A caller without SuperAdmin access receives `403`.
* An unavailable marketing database returns `503` without exposing connection
  details. The failure is logged and reported to Sentry.
* Journey responses can be `partial`: each unavailable tile has
  `{ "status": "unavailable", "data": null }`. Treat that state as unknown,
  not as a zero metric.

Dates use `YYYY-MM-DD`. Custom `from` and `to` values are inclusive, must be
provided together, and take precedence over `window`.

## SEO overview

`GET /api/v2/admin/marketing/seo`

| Parameter    | Default | Allowed values                            |
| ------------ | ------- | ----------------------------------------- |
| `window`     | `30`    | `7`, `14`, `28`, `30`, `90`, `180`, `365` |
| `from`, `to` | —       | Inclusive date pair                       |
| `limit`      | `25`    | Integer from `1` to `100`                 |

The response contains:

* `freshness`: latest loaded date, row count, and synchronization time;
* `window`: the effective and available date bounds;
* `kpis`: current and prior impressions, clicks, click-through rate, and
  average position;
* `trend`: daily performance;
* `topPages`, `topQueries`, and `pageQueries`;
* `opportunities`: page/query pairs with at least 10 impressions whose
  impression-weighted average position is between 4 and 10, ordered by
  impressions.

Query rows include rank tier, tier movement, zero-click and AI-query flags, and
an at-risk signal. The first contract intentionally excludes live metadata
health and the model-generated digest from the legacy dashboard.

## Answer-engine visibility

`GET /api/v2/admin/marketing/aeo`

| Parameter    | Default | Allowed values            |
| ------------ | ------- | ------------------------- |
| `window`     | `30`    | Integer from `1` to `365` |
| `from`, `to` | —       | Inclusive date pair       |
| `limit`      | `10`    | Integer from `1` to `25`  |

The response supplies its fetch time and effective range, source status,
prompt/run totals, current and prior primary-brand mention rates, share of
voice by brand, performance by model, and the most-used citation URLs.

## Website journeys

`GET /api/v2/admin/marketing/journeys`

| Parameter    | Default | Allowed values            |
| ------------ | ------- | ------------------------- |
| `window`     | `30`    | Integer from `1` to `365` |
| `from`, `to` | —       | Inclusive date pair       |
| `pathSteps`  | `4`     | Integer from `2` to `4`   |

The response supplies its fetch time and effective range, overall source
status, current/prior traffic and conversion KPIs, source breakdowns, homepage
and converting paths, preview/contact/storefront funnels, and storefront signup
attribution. Each tile reports its own availability.

## Data-source configuration

The API process owns all credentials. The browser never receives database or
PostHog keys.

* `MARKETING_DATABASE_URL`: isolated `scope3_marketing` connection. Use a role
  with `SELECT`-only grants; the pool also sets PostgreSQL sessions read-only.
* `MARKETING_DB_POOL_MAX`, `MARKETING_DB_IDLE_TIMEOUT_MS`,
  `MARKETING_DB_CONNECTION_TIMEOUT_MS`, `MARKETING_DB_STATEMENT_TIMEOUT_MS`:
  optional pool limits and timeouts.
* `POSTHOG_API_KEY` and `POSTHOG_MARKETING_PROJECT_ID`: marketing-site HogQL
  reads.
* `POSTHOG_API_KEY_INTERCHANGE` and `POSTHOG_INTERCHANGE_PROJECT_ID`:
  Interchange signup-attribution reads.

Missing PostHog keys degrade the affected journey tiles instead of fabricating
zero values. Marketing database access has no fallback to the application or
ledger databases.