API

Overview

The API gives you read-only access to your project’s weekly prompt metrics, content item evaluations, and reporting-dashboard aggregates (the same LLM metrics and GA-based series the Reporting page uses). Use it to:

Pull brand mention and citation rates into your own dashboards
Track prompt and provider performance over time
Read prompt metadata (collections, sentiment) alongside visibility metrics
Export content quality scores (extractability, humanness, and related evaluation fields)
Automate exports that match Impact and Competitors reporting (see Reporting dashboard below)

Access and authentication

Generate your project token in Settings -> API.

One active token per project
Token is scoped to that project only
Regenerating immediately invalidates the previous token

Send it in the Authorization header:

Authorization: Bearer tp_your_token_here

Data freshness

Prompt metrics are updated weekly
Weekly windows are Sunday-based
If you do not pass week_start, endpoints that need a week return your latest available week

Base URL

https://<your-project-ref>.supabase.co/functions/v1

Most prompt metrics and content endpoints below are GET only (query parameters, no body). Reporting endpoints (/report, /ga-report) are GET only as well.

Endpoint index

Paths are relative to https://<your-project-ref>.supabase.co/functions/v1.

Doc title	Path	Methods	Auth
Report — LLM visibility & competitors	`/report`	GET	Project token or user JWT
GA report — Analytics time series	`/ga-report`	GET	Project token or user JWT
Summary	`/summary`	GET	Project token
Prompts list	`/prompts`	GET	Project token
Single prompt	`/prompt`	GET	Project token
Prompt timeseries	`/prompt-timeseries`	GET	Project token
Prompt providers	`/prompt-providers`	GET	Project token
Content items	`/content-items`	GET	Project token
Single content item	`/content-item`	GET	Project token

Reporting dashboard

Automation endpoints for the in-app Reporting page. Periods use 7 / 30 / 365 calendar days for week / month / year.

Authentication

Project API token (from Settings → API): Authorization: Bearer tp_...
- Do not pass project_id; the token is already scoped to one project.
Logged-in user (Supabase session JWT): Authorization: Bearer <access_token>
- You must pass project_id in the query string. The user must have access to that project.

Report — LLM visibility and competitor metrics (`GET /report`)

Full LLM-side reporting: weighted mention rate, citation rate, sentiment, competitor tables and weekly series, citation bucket breakdown, optional experiments. The web app uses this same endpoint (GET with start_date / end_date). Responses include a top-level meta object (resolved dates and filters). Query parameters

Parameter	Description
`project_id`	Required for user JWT; omit with API token
`start_date`, `end_date`	`YYYY-MM-DD` inclusive window; if both set, they define the range instead of `period`
`period`	`week` \| `month` \| `year` (default `month`; ignored when `start_date` and `end_date` are set)
`collections`	Comma-separated tag names (prompt collections), resolved to tag IDs server-side
`tag_ids`	Comma-separated tag UUIDs (optional; merged with resolved `collections`)
`intent` / `intents`	Comma-separated intent values
`llm_provider` / `provider_ids`	Comma-separated AI provider UUIDs
`location` / `locations`	Comma-separated location strings
`include_experiments`	`true` / `false` (default `true`)
`skip_competitors`	`true` / `false` (default `false`)
`page`, `page_size`	Pagination for the weekly `series` slice (defaults `0`, `50`, max `500`)
`company_id`	Optional; per-company mention/sentiment series
`target_type`, `target_id`	Optional experiment filter

Example: GET with project token

curl -s "https://<your-project-ref>.supabase.co/functions/v1/report?period=month&collections=Enterprise&intent=commercial" \
  -H "Authorization: Bearer tp_your_token_here" \
  -H "apikey: <your-anon-key>"

Example: GET with user JWT, explicit dates and filters

curl -s "https://<your-project-ref>.supabase.co/functions/v1/report?project_id=550e8400-e29b-41d4-a716-446655440000&start_date=2025-06-01&end_date=2025-12-01&collections=Enterprise,SMB&provider_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "apikey: <your-anon-key>"

Example response (truncated)

{
  "success": true,
  "meta": {
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "...",
    "period": "month",
    "start_date": "2025-01-23",
    "end_date": "2026-02-23",
    "filters": {
      "collections": ["Enterprise"],
      "tag_ids": ["..."],
      "intents": ["commercial"],
      "llm_provider_ids": [],
      "locations": []
    }
  },
  "series": [
    {
      "week_start": "2026-02-08",
      "weighted_mention_rate": 42.5,
      "citation_rate": 18.2,
      "weighted_sentiment": 3.1
    }
  ],
  "latestWeek": "2026-02-08",
  "competitorMention": [],
  "competitorShare": [],
  "competitorSentiment": [],
  "competitorCitation": [],
  "competitorShareSeries": [],
  "competitorMentionSeries": [],
  "competitorSentimentSeries": [],
  "competitorCitationSeries": [],
  "citations_breakdown": {
    "owned": 0,
    "social": 0,
    "earned": 0,
    "competitors": 0
  },
  "experiments": [],
  "pagination": { "page": 0, "pageSize": 50, "hasMore": false },
  "metadata": { "skipCompetitors": false, "processingTime": 120 }
}

Arrays such as competitorShare, competitorShareSeries, etc. are populated when data exists (same as the app). For errors, you may receive { "error": "..." } or { "success": false, "error": "..." } depending on the failure path.

GA report — Traffic and platform-filtered series (`GET /ga-report`)

Google Analytics for reporting: calls the existing fetch-google-analytics pipeline, then returns the full analytics payload plus filtered_daily — daily rows with traffic_raw and ai_sessions using the same platform rules as the Reporting UI (google-serps, google-ai-overview, chatgpt, etc.). Requires GA4 connected for the project. Query parameters

Parameter	Description
`project_id`	Required for user JWT; omit with API token
`start_date`, `end_date`	`YYYY-MM-DD`; both required together if you override `period`
`period`	`week` \| `month` \| `year` (default `month`)
`page_path`	Optional; restricts GA to one landing path (same as page filter in app)
`platforms`	Comma-separated UI platform ids (e.g. `chatgpt,google-serps`). Omit or empty = all traffic

Example: GET

curl -s "https://<your-project-ref>.supabase.co/functions/v1/ga-report?period=week&platforms=chatgpt,google-serps" \
  -H "Authorization: Bearer tp_your_token_here" \
  -H "apikey: <your-anon-key>"

Example response (truncated)

{
  "success": true,
  "meta": {
    "project_id": "...",
    "period": "week",
    "start_date": "2026-02-16",
    "end_date": "2026-02-23",
    "page_path": null,
    "platforms": ["chatgpt", "google-serps"]
  },
  "analytics": {
    "timeSeries": [
      {
        "date": "20260220",
        "totalSessions": 1200,
        "chatgptSessions": 80,
        "overallEngagementRate": 0.04
      }
    ],
    "summary": {
      "totalAiSessions": 200,
      "totalNonAiSessions": 1000,
      "totalRevenue": 0,
      "totalKeyEvents": 50
    }
  },
  "filtered_daily": [
    {
      "date": "2026-02-20",
      "traffic_raw": 1120,
      "ai_sessions": 80,
      "overall_engagement_rate": 0.04
    }
  ]
}

If GA is not connected or tokens are invalid, the status and body match fetch-google-analytics (e.g. 401 with authError: true).

Prompt metrics

Summary — Top-line metrics for one week (`GET /summary`)

Top-line metrics for one week. Query params

week_start (optional, YYYY-MM-DD, normalized to Sunday)
provider (optional, AI provider id)

Response

request_id
week_start
totals: prompt_count, search_count, mention_rate, first_mention_rate, citation_rate
citations: owned, earned, competitor
providers[]: each item has id, name, mention_rate, first_mention_rate, citation_rate

Example

curl -X GET "https://<your-project-ref>.supabase.co/functions/v1/summary" \
  -H "Authorization: Bearer tp_your_token_here"

Prompts — Paginated prompt metrics (`GET /prompts`)

Paginated prompt-level metrics for one week. Each row includes collections and average_sentiment from the prompt record. Query params

week_start (optional)
provider (optional)
query (optional, case-insensitive substring match on prompt text)
limit (optional, default 50, max 100)
cursor (optional, opaque pagination cursor from page.next_cursor)

Response

request_id
week_start
prompts[]: each object has:
- id, text, intent, search_volume_score, average_sentiment (nullable)
- collections[]: { id, name } (always present; empty array if none)
- mention_rate, first_mention_rate, citation_rate, rank
page: has_more, next_cursor (null when no next page)

Prompt — Single prompt detail (`GET /prompt`)

Detail for a single prompt for one week. Query params

id (required, prompt uuid)
week_start (optional)

Response

request_id
week_start
prompt: id, text, intent, search_volume_score, average_sentiment, collections[]
mention_rate, first_mention_rate, citation_rate, search_count (aggregate for that prompt in the week)
providers[]: id, name, mention_rate, first_mention_rate, citation_rate
top_citations[]: url, domain, citation_type, count

Errors

404 if the prompt does not exist or is not in this project

Prompt timeseries — Trend across weeks (`GET /prompt-timeseries`)

Trend data across weeks. Query params

from_week_start (optional)
to_week_start (optional)
provider (optional)
id (optional, filter to one prompt)

Limits

At most 52 weeks per request

Response

request_id
series[]: each point has week_start, mention_rate, first_mention_rate, citation_rate, prompt_count, search_count

Prompt providers — One week by AI provider (`GET /prompt-providers`)

One-week breakdown by AI provider. Query params

week_start (optional)

Response

request_id
week_start
providers[]: id, name, prompt_count, search_count, mention_rate, first_mention_rate, citation_rate, owned_citations, earned_citations, competitor_citations

Content

Content items — List with latest evaluation (`GET /content-items`)

All content items in the project, paginated, with the latest evaluation per item (by created_at). Query params

limit (optional, default 50, max 100)
cursor (optional)

Response

request_id
content_items[]: id, title, url, created_at, updated_at, evaluation
evaluation is null if there is no row in executing_contentitemevaluation, otherwise an object with:
- score, content_quality, audience_alignment, seo_optimization, engagement_potential, eeat, extractability, humanness_score, prompt_focus, created_at, updated_at
- llm_justifications only if present on the stored evaluation

Content item — Single item (`GET /content-item`)

Single content item with the same evaluation rules as the list. Query params

id (required, content item uuid)

Response

request_id
content_item: same shape as one element of content_items[]

Errors

404 if the item does not exist or is not in this project

Rate and timeout limits

Prompt list and content list are capped at 100 rows per request
Timeseries is capped at 52 weeks
Requests may return 429 if rate or time budgets are exceeded

Errors

Common status codes:

400 invalid input
401 missing or invalid token
404 not found (prompt or content item)
405 method not allowed
429 rate or timeout guardrail
500 unexpected server error

Example body:

{
  "error": {
    "code": "invalid_request",
    "message": "id is required"
  },
  "request_id": "..."
}

Quick example

curl -X GET "https://<your-project-ref>.supabase.co/functions/v1/summary" \
  -H "Authorization: Bearer tp_your_token_here"

Getting started

Product

Reference

Overview

Access and authentication

Data freshness

Base URL

Endpoint index

Reporting dashboard

Authentication

Report — LLM visibility and competitor metrics (`GET /report`)

GA report — Traffic and platform-filtered series (`GET /ga-report`)

Prompt metrics

Summary — Top-line metrics for one week (`GET /summary`)

Prompts — Paginated prompt metrics (`GET /prompts`)

Prompt — Single prompt detail (`GET /prompt`)

Prompt timeseries — Trend across weeks (`GET /prompt-timeseries`)

Prompt providers — One week by AI provider (`GET /prompt-providers`)

Content

Content items — List with latest evaluation (`GET /content-items`)

Content item — Single item (`GET /content-item`)

Rate and timeout limits

Errors

Quick example

Getting started

Product

Reference

​Overview

​Access and authentication

​Data freshness

​Base URL

​Endpoint index

​Reporting dashboard

​Authentication

​Report — LLM visibility and competitor metrics (GET /report)

​GA report — Traffic and platform-filtered series (GET /ga-report)

​Prompt metrics

​Summary — Top-line metrics for one week (GET /summary)

​Prompts — Paginated prompt metrics (GET /prompts)

​Prompt — Single prompt detail (GET /prompt)

​Prompt timeseries — Trend across weeks (GET /prompt-timeseries)

​Prompt providers — One week by AI provider (GET /prompt-providers)

​Content

​Content items — List with latest evaluation (GET /content-items)

​Content item — Single item (GET /content-item)

​Rate and timeout limits

​Errors

​Quick example

Overview

Access and authentication

Data freshness

Base URL

Endpoint index

Reporting dashboard

Authentication

Report — LLM visibility and competitor metrics (`GET /report`)

GA report — Traffic and platform-filtered series (`GET /ga-report`)

Prompt metrics

Summary — Top-line metrics for one week (`GET /summary`)

Prompts — Paginated prompt metrics (`GET /prompts`)

Prompt — Single prompt detail (`GET /prompt`)

Prompt timeseries — Trend across weeks (`GET /prompt-timeseries`)

Prompt providers — One week by AI provider (`GET /prompt-providers`)

Content

Content items — List with latest evaluation (`GET /content-items`)

Content item — Single item (`GET /content-item`)

Rate and timeout limits

Errors

Quick example