Skip to main content
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 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 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 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.