Reference
This page lists every enum, shared filter convention, and error code used across the SE Visible API. Other pages link here instead of repeating values.
All endpoints are served from the base URL https://api.seranking.com/v1/se-visible.
AI models
Values accepted by model_type, model_types, and model.
| Value | Model |
|---|---|
chatgpt | ChatGPT |
google_gemini | Google Gemini |
perplexity | Perplexity |
google_ai_mode | Google AI Mode |
google_ai_overview | Google AI Overview |
Sentiment
Values returned by sentiment in results and accepted by the sentiments filter.
| Value | Meaning |
|---|---|
positive | Positive sentiment toward the brand. |
neutral | Neutral or factual mention. |
negative | Negative sentiment toward the brand. |
Project status
Values returned by status on a project. A new project is processed asynchronously, so poll the project until it reaches success or error.
| Value | Meaning |
|---|---|
queued | Waiting to be processed. |
processing | Generation in progress. |
success | Completed. |
error | Processing failed. |
Country codes
ISO 3166-1 alpha-2 codes accepted by country_code (project creation) and the country_codes filter.
US, UK, CA, FR, DE, NL, ES, AT, BE, AU, NZ, IT, JP, KR, SG, IN, AE, BR, MX, CH, DK, SE, NO, FI, IE, IS, LU, PT, HK, TH, MY, ID, PH, IL, AR, CL, CO, ZA, CZ, GR, TR, PL
Language codes
ISO 639-1 codes accepted by lang_code.
en, fr, de, nl, es, it, ja, ko, hi, ar, pt, da, sv, nb, fi, ga, is, lb, zh, th, ms, id, tl, he, af, cs, el, tr, pl
Source type
Values accepted by source_type on the Sources endpoint. The chosen value changes the shape of each Sources response row.
| Value | Meaning |
|---|---|
domain | Group cited sources by domain. Default. |
url | Return cited sources at the individual URL level. |
URL category types
Values accepted by the types filter, used to filter sources by the kind of page cited.
| Value |
|---|
file |
video |
social |
forum |
q&a |
documentation |
wiki |
news |
blog |
product |
job |
educational |
local |
app |
search |
homepage |
other |
Brand match mode
Values accepted by brand_match_mode, used together with the brand_ids filter on Sources.
| Value | Meaning |
|---|---|
any | Match sources mentioning any of the given brands. Default. |
all | Match only sources mentioning all of the given brands. |
Prompt list grouping
Values accepted by group_mode on List prompts or topics.
| Value | Meaning |
|---|---|
prompt | Return one row per prompt. Default. |
topic | Group prompts by topic. |
Brand metrics dimensions and metrics
The brand metrics endpoint takes dimensions[] (how rows are grouped) and metrics[] (which values to return). The last dimension is always the pivot.
Dimensions (dimensions[], 1 to 3, last is the pivot)
| Value |
|---|
topic_id |
brand_id |
prompt_id |
Metrics (metrics[], 1 to 5)
| Value |
|---|
visibility_score |
avg_position |
sentiment_score |
total_mentions |
rank |
total_response_count |
positive_pct |
neutral_pct |
negative_pct |
total_all_mentions |
unique_brands_count |
share_of_voice |
Sort fields
Prompt list (sort_field)
| Value |
|---|
visibility |
avg_position |
mentions |
sentiments |
Source (source_sort_field)
The accepted values depend on source_type.
For source_type=domain:
| Value |
|---|
ai_answers_count |
pages |
coverage |
prompts_count |
mention_rate |
my_brand_mentions_count |
competitors_count |
first_seen |
last_seen |
For source_type=url:
| Value |
|---|
ai_answers_count |
coverage |
prompts_count |
competitors_count |
my_brand_mentions |
gap_score |
first_seen |
last_seen |
last_check_date |
Sort order (sort_order)
| Value | Meaning |
|---|---|
asc | Ascending. |
desc | Descending. |
Date ranges and compare mode
Metrics, prompt results, and sources are filtered by a required date_range. It is a deep object with a base period at index 0 and an optional compare period at index 1. Each period has from and to in YYYY-MM-DD.
# Base period only
?date_range[0][from]=2026-05-01&date_range[0][to]=2026-05-31
# Base period vs compare period (compare mode)
?date_range[0][from]=2026-05-01&date_range[0][to]=2026-05-31&date_range[1][from]=2026-04-01&date_range[1][to]=2026-04-30
When a compare period is supplied, supported metrics return both period values plus a delta with absolute and percentage.
Array parameters
Most array filters repeat the parameter key, one entry per value:
?model_types=chatgpt&model_types=perplexity
The brand metrics endpoint uses the bracketed array form for dimensions[] and metrics[]:
?dimensions[]=topic_id&metrics[]=visibility_score
Note:
- When a URL contains brackets (
[]), pass--globoffto curl so it does not try to interpret them as glob patterns.
Pagination
List endpoints accept limit and offset and return a total count alongside the results.
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | Integer | 1000 | Maximum number of items to return. Some endpoints cap this lower; see each endpoint. |
| offset | Integer | 0 | Number of items to skip from the start of the list. |
To page through results, increase offset by limit until offset reaches total.
Error codes
The API uses standard HTTP status codes. Only 2xx responses indicate success. Error bodies are JSON. Endpoint-specific errors are described within each endpoint’s documentation.
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad request | { "message": "..." } |
| 401 | Unauthenticated (missing or invalid key) | { "message": "Unauthenticated.", "error_code": "unauthenticated" } |
| 403 | Forbidden (key valid, action not allowed) | { "message": "This action is unauthorized.", "error_code": "this_action_is_unauthorized" } |
| 404 | Resource not found | { "message": "..." } |
| 422 | Validation error | { "message": "...", "errors": { "field": ["..."] } } |
Authentication
Every request is authenticated with your SE Ranking API key, the same key used by the Data API and Project API. Send it one of two ways:
- Authorization header (recommended):
Authorization: Token YOUR_API_KEY - Query parameter:
?apikey=YOUR_API_KEY
