Reference

API Documentation

Base URL: https://api.prominenceai.io·Auth: Bearer token·Format: JSON·Rate limit: 60 req/min·Last updated: September 8, 2026

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

Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings > API Keys. Each key carries scopes (shown next to each endpoint below) that control which endpoints it can call. Monitor IDs are listed in Settings > Projects.

Core Endpoints

GET/api/v1/metricsmetrics:read

Metrics API

Returns brand visibility metrics across AI models over a given time window, including Share of Answer, Average Position, Share of Mentions, Citations, 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, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
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, pos, som, kpis, cit
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	Compute SOA counting only mentions within the top N positions of the answer. Does not reduce the number of entities returned

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,ai-overview&include_series=true"

Key Fields

share_of_answer.value: percentage of prompts where your brand appears in the response
avg_position: where in the response your brand typically appears (lower is better)
citations: how often your digital assets are used as grounding sources, with cited_count out of grounded_count
entity_kind: primary for your brand, competitor for tracked competitors
delta: change vs. the equivalent previous period
kpis.collection_dates: the weekly collections included in the window
per_model: same breakdown per individual AI model
no_answer_rate: percentage of queries where the engine returned no answer (queries_attempted vs. answers_returned), common on AI Overviews
series: week-by-week trend (requires include_series=true)

GET/api/v1/gspgsp:read

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, domain category filtering, 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: openai, google, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
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
domain_types	string	optional	Comma-separated domain categories: media_publishers, retail_commerce, ugc_communities, social_video, brand_websites, others
include_trend	boolean	optional	Include 12-week citation trend sparkline on domains; also on each URL when include_urls=true. Default: false

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/gsp?monitor_id=238&models=openai,google,ai-overview&per_page=50&include_series=true&include_urls=true&domain_types=media_publishers&include_trend=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
domain_type: category of the domain (media_publishers, ugc_communities, brand_websites, etc.)
delta: change in citations and pct_cited vs. the previous period
per_model: citations and pct_cited per model, useful for prioritizing GEO work
weekly_trend: 12-week citation sparkline (requires include_trend=true)
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

GET/api/v1/promptsprompts:read

Prompts API

Returns all tracked prompts with per-prompt metrics: SOA, position, delta comparisons, top cited brands, source prominence, and per-model breakdown. Ordered by primary-brand SOA, descending (most visible prompts first).

When to use:For prompt-level analysis: finding weak or missing prompts, understanding which competitors win each prompt, and identifying the sources cited when a prompt runs.

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: openai, google, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
segment_ids	string	optional	Comma-separated segment IDs to filter prompts
search	string	optional	Filter prompts by text
page	number	optional	Page number. Default: 1
per_page	number	optional	Results per page. Default: 20, max: 200
status	string	optional	Filter by visibility status: all, strong, medium, weak, missing, not_run. Default: all. missing = ran but the brand is absent; not_run = no successful runs in the window. Pass missing,not_run for the previous combined behaviour
is_active	boolean	optional	true = active prompts only, false = inactive only, omit for all. Default: true
source_mode	string	optional	Source type for prominence data: domains or urls. Default: domains
delta_mode	string	optional	Delta method: period (vs equal prior window) or snapshot (first vs last day in window). Default: period
include_source_prominence	boolean	optional	Include source prominence data per prompt. Default: true
include_prompt_gaps	boolean	optional	Include prompt_gaps data (every brand in the prompt with SOA, position, and SOM) per prompt. Default: true
include_per_model	boolean	optional	Include soa_per_model and models breakdown per prompt. Default: true
include_top_competitors	boolean	optional	Deprecated. Use include_prompt_gaps
include_share_of_mentions	boolean	optional	Deprecated. SOM is now returned per brand inside prompt_gaps

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/prompts?monitor_id=238&since=2026-04-01&until=2026-05-01&segment_ids=255&status=strong&models=openai&source_mode=domains&search=top"

Key Fields

status: visibility level of the prompt for your brand (strong, medium, weak, missing, not_run)
counts_by_status: how your full prompt set distributes across visibility levels
overall_soa / avg_position: per-prompt performance, each with a delta vs. the prior period
prompt_gaps: every brand in that prompt with SOA, position, and SOM, each with its delta
source_prominence: the domains or URLs cited when that prompt runs
soa_per_model: per-model SOA breakdown for the prompt (requires include_per_model=true)
filters: echoes the filters applied to the request

YouTube Endpoints

YouTube is one of the most influential grounding sources in AI search. These endpoints expose the full YouTube Explorer dataset programmatically: the videos and channels LLMs cite, and the aggregate metrics that show how much video shapes AI answers in your category.

GET/api/v1/youtube/videosyoutube:read

YouTube Videos API

Retrieves YouTube videos cited by LLMs for your monitor, sorted by citation count. Includes video metadata, citation deltas, and the prompts that triggered each citation.

When to use:To know exactly which videos are shaping AI answers in your category: what they cover, who published them, and which prompts surface them.

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: openai, google, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
segment_ids	string	optional	Comma-separated segment IDs to filter
channel_ids	string	optional	Comma-separated YouTube channel IDs to filter videos by
include_prompt_info	boolean	optional	Include detailed prompt info per video. Default: true
include_tags	boolean	optional	Include YouTube tags for each video. Default: false
include_thumbnails	boolean	optional	Include thumbnail URLs for each video. Default: false
page	number	optional	Page number, 1-indexed. Default: 1
per_page	number	optional	Items per page. Default: 20, max: 200. The response carries a pagination block; total is the full unpaginated count

Example Request

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

Key Fields

citations: how many times LLMs cited that video as a grounding source
citations_delta: change vs. the previous period
prompts: the exact prompts (and models) that triggered each citation; prompts_count is the total
total_views / likes / comments: YouTube engagement metadata per video
tags / thumbnails: returned when include_tags=true and include_thumbnails=true
pagination: use total_pages to iterate; total is the full unpaginated count

GET/api/v1/youtube/channelsyoutube:read

YouTube Channels API

Retrieves YouTube channels cited by LLMs for your monitor, aggregated by channel. Returns channel metadata, total citations, citation deltas, and the top 3 cited videos per channel.

When to use:To identify the creators and publishers carrying the most grounding weight in your category, and to size them by audience for partnership or outreach decisions.

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: openai, google, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
segment_ids	string	optional	Comma-separated segment IDs to filter
size	string	optional	Filter by channel size: top, large, medium, small, micro
include_top_videos	boolean	optional	Include the top 3 most cited videos for each channel. Default: true
include_thumbnails	boolean	optional	Include thumbnail URLs for each channel. Default: false
page	number	optional	Page number, 1-indexed. Default: 1
per_page	number	optional	Items per page. Default: 20, max: 200. The response carries a pagination block; total is the full unpaginated count

Example Request

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

Key Fields

citations: total citations aggregated across all the channel's videos
subscribers / total_views / total_videos: audience and volume per channel
size: channel size bucket (top, large, medium, small, micro)
top_videos: the channel's 3 most cited videos (requires include_top_videos=true)
pagination: use total_pages to iterate; total is the full unpaginated count

GET/api/v1/youtube/metricsyoutube:read

YouTube Metrics API

Comprehensive YouTube metrics dashboard for a monitor. Returns YouTube weight/share, grounding freshness distribution, top cited channels, brand mentions, topic cloud, channel size distribution, and grounding trigger analysis.

When to use:For the aggregate view: how much YouTube matters in your category, how fresh the cited content is, and which topics and prompts activate video grounding.

Parameters

Parameter	Type	Required	Description
monitor_id	number	required	Your monitor ID (also accepted as brand_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: openai, google, ai-overview, google-ai-mode, perplexity, grok, copilot, anthropic, mistral, deepseek, meta
segment_ids	string	optional	Comma-separated segment IDs to filter
top_n	number	optional	Top N positions for tags. Default: 15, max: 50
include_series	boolean	optional	Include citation timelines per channel and YouTube weight series. Default: false

Example Request

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

Key Fields

youtube_weight: share of all grounding citations that come from YouTube, with delta
grounding_freshness: age distribution of the cited videos (evergreen vs. recent content)
channel_citations: top cited channels ranked by grounding weight
youtube_grounding_triggers: the prompts most likely to activate YouTube as a source
topic_cloud: themes dominating video-grounded responses in your category

Helper Endpoints

GET/api/v1/monitorsmonitors:read

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/modelsmetrics:read

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/segmentsmetrics:read

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/entitiesmetrics:read

List Entities

Returns the monitor's primary brand and all tracked competitors with their entity_id values, usable in entity_ids filters across the 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/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

Go prompt-level

/api/v1/prompts to find strong, weak, and missing prompts

Analyze grounding sources

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

Measure YouTube influence

/api/v1/youtube/metrics, /videos, and /channels for video grounding intelligence

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,pos&include_series=true&include_competitors=true"

Find weak and missing prompts in a segment

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/prompts?monitor_id=238&segment_ids=255&status=weak,missing&include_prompt_gaps=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"

Media publisher domains with 12-week trends

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/gsp?monitor_id=238&domain_types=media_publishers&include_trend=true&per_page=50"

Top cited YouTube channels for creator outreach

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.prominenceai.io/api/v1/youtube/channels?monitor_id=238&size=medium&include_top_videos=true"

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, Prompts, YouTube Videos, and YouTube Channels paginate with page and per_page (max 200 per page); use total_pages to iterate
Deprecated parameters are still accepted but may be removed in a future version: on /api/v1/prompts, use include_prompt_gaps instead of include_top_competitors and include_share_of_mentions
API keys carry scopes (metrics:read, gsp:read, prompts:read, youtube:read, monitors:read). A key can only call endpoints whose scope it includes; manage scopes in Settings > API Keys
Rate limit: 60 requests per minute per API key
Entities with is_synthetic: true are competitors tracked synthetically. They can be used in entity_ids filters with their negative ID