Reference

API Documentation

Base URL: https://api.prominenceai.io·Auth: Bearer token·Format: JSON

All requests require an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Find your API key and monitor IDs in Settings > Projects.

Core Endpoints

GET/api/v1/metrics

Metrics API

Returns brand visibility metrics across AI models over a given time window, including Share of Answer, LLM Visibility Index, Share of Mentions, and prompt coverage KPIs.

When to use:Anytime you want to know how your brand is performing across models, overall or broken down by model, segment, or time period.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID
since	string	optional	Start date in ISO 8601 format. Default: 30 days ago
until	string	optional	End date in ISO 8601 format. Default: today
models	string	optional	Comma-separated model buckets: openai, google, perplexity, etc.
segment_ids	string	optional	Comma-separated segment IDs to filter by prompt category
entity_ids	string	optional	Comma-separated entity IDs to include
metrics	string	optional	Comma-separated metric types: soa, lvi, som, kpis
include_per_model	boolean	optional	Model-level breakdown. Default: true
include_series	boolean	optional	Weekly time series. Default: false
include_competitors	boolean	optional	Include competitor entities. Default: true
top_n	number	optional	Limit SOA results to top N positions

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics?monitor_id=238&since=2026-01-01&until=2026-01-31&models=openai,google&include_series=true"

Key Fields

share_of_answer.value: percentage of prompts where your brand appears in the response
delta: change vs. the equivalent previous period
by_model: same breakdown per individual AI model
series: week-by-week trend (requires include_series=true)

GET/api/v1/benchmark

Benchmark API

Compares your brand against competitors at the prompt level. Includes Venn overlap data showing where you share visibility, where you have exclusive presence, and where you are missing entirely.

When to use:For competitive analysis: understanding your share of the battle relative to specific rivals, across models or prompt segments.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID
entity_ids	string	optional	Comma-separated competitor entity IDs to compare
since	string	optional	Start date in ISO 8601 format. Default: 90 days ago
until	string	optional	End date in ISO 8601 format. Default: today
models	string	optional	Comma-separated model buckets to filter
segment_ids	string	optional	Comma-separated segment IDs to filter
include_prompts	boolean	optional	Prompt-level detail. Default: true
include_series	boolean	optional	Weekly time series. Default: false
include_overlap	boolean	optional	Venn overlap data. Default: true

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/benchmark?monitor_id=238&since=2026-01-01&until=2026-01-31&include_series=true"

Key Fields

shared_prompts: prompts where both brands appear (direct competition zone)
unique_prompts: prompts where only your brand appears (differentiation advantage)
missing_prompts: prompts where the competitor appears but you do not (visibility gap)
overlap: raw data for building a Venn diagram between entities
is_synthetic: true indicates a competitor tracked synthetically, without their own monitor

GET/api/v1/gsp

Grounding Source Prominence API

Shows which domains LLMs cite when generating responses about your brand, and how prominently each one appears. Supports pagination, sorting, per-model breakdown, and weekly trends.

When to use:To understand the source ecosystem behind your AI visibility: which publishers, directories, or sites carry the most weight as grounding references for your brand across each model.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID
since	string	optional	Start date in ISO 8601 format. Default: 30 days ago
until	string	optional	End date in ISO 8601 format. Default: today
models	string	optional	Comma-separated model buckets to filter
segment_ids	string	optional	Comma-separated segment IDs to filter
search	string	optional	Filter domains by partial name match
page	number	optional	Page number. Default: 1
per_page	number	optional	Results per page. Default: 20, max: 200
sort_by	string	optional	Sort field: citations, pct_cited, or domain
sort_order	string	optional	asc or desc. Default: desc
include_per_model	boolean	optional	Per-model breakdown. Default: true
include_series	boolean	optional	Weekly time series. Default: false
include_urls	boolean	optional	Per-URL breakdown under each domain. Default: false

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/gsp?monitor_id=238&models=openai,google&per_page=50&include_series=true&include_urls=true"

Key Fields

citations: total times that domain was cited across all prompt runs
pct_cited: percentage of prompts that included a citation from that domain
by_model: which models cite that domain most, useful for prioritizing GEO work
series: week-by-week presence of that domain (requires include_series=true)
Use total_pages to iterate through all domains when the result set spans multiple pages

Helper Endpoints

GET/api/v1/monitors

List Monitors

Returns all monitors available for your account with metadata, prompt counts, and run statistics. No parameters required.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/monitors"

GET/api/v1/metrics/models

List Models

Returns all supported model buckets and which ones have data for a specific monitor.

Parameters

Parameter	Type	Required	Description
monitor_id	number	optional	Filter to models with data for this monitor
since	string	optional	Start date in ISO 8601 format
until	string	optional	End date in ISO 8601 format

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics/models?monitor_id=238"

GET/api/v1/metrics/segments

List Segments

Returns available segments (prompt tags) for a monitor, usable as filters across all core endpoints.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics/segments?monitor_id=238"

GET/api/v1/metrics/entities

List Entities

Returns the monitor's primary brand and all tracked competitors with their entity_id values, needed for filtering the Benchmark API.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics/entities?monitor_id=238"

Getting Started

If you are querying the API for the first time, follow this sequence:

Get your monitor ID

Call /api/v1/monitors or find it in Settings > Projects

Check which models have data

/api/v1/metrics/models?monitor_id=YOUR_ID

Discover segments and entities

/api/v1/metrics/segments and /api/v1/metrics/entities

Pull your core metrics

/api/v1/metrics with whichever filters apply

Add competitive context

/api/v1/benchmark to compare against rivals

Analyze grounding sources

/api/v1/gsp to understand which domains drive your visibility

Common Use Cases

Automated monthly SOA report

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics?monitor_id=238&since=2026-01-01&until=2026-01-31&metrics=soa,lvi&include_series=true&include_competitors=true"

Point-in-time competitive benchmark

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/benchmark?monitor_id=238&entity_ids=238,-123456&since=2026-01-01&until=2026-01-31&include_overlap=true"

Top grounding sources for OpenAI only

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/gsp?monitor_id=238&models=openai&sort_by=pct_cited&per_page=100"

Filter metrics by prompt segment

# Step 1: get your segment IDs
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics/segments?monitor_id=238"

# Step 2: use them as a filter
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/metrics?monitor_id=238&segment_ids=12,34&since=2026-01-01"

Technical Notes

All dates use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS
delta fields represent absolute change vs. the equivalent prior period
SOA and pct_cited values are percentages expressed as 0-100, not 0-1 decimals
GSP pagination uses page and per_page (max 200 per page); use total_pages to iterate
Entities with is_synthetic: true are competitors tracked synthetically. They can be used in entity_ids filters with their negative ID