Getting started

Welcome to the SE Visible API. SE Visible tracks how brands appear across AI engines (ChatGPT, Google Gemini, Perplexity, Google AI Mode, and Google AI Overview). With the API you create projects, manage the brands, topics, and prompts you track, and pull back visibility metrics, prompt results, and the sources that AI engines cite.

This guide covers authentication, the base URL, the resource model, how to make requests, pagination, filtering, and error handling.

Base URL

All endpoints are served from a single base URL:

https://api.seranking.com/v1/se-visible

Authentication

Every request must be authenticated with your SE Ranking API key. Authentication is identical to the Data API and Project API: you can send the key in an Authorization header or as an apikey query parameter.

Generate a key from the API Dashboard in your SE Ranking or SE Visible account.

Method 1: Authorization header (recommended)

Send the key in an Authorization header with the value Token YOUR_API_KEY.

curl -X GET 'https://api.seranking.com/v1/se-visible/subscription' \
  -H 'Authorization: Token YOUR_API_KEY'

Method 2: Query parameter

Pass the key as an apikey query parameter.

curl -X GET 'https://api.seranking.com/v1/se-visible/subscription?apikey=YOUR_API_KEY'

Note:

• The apikey parameter must always be sent as a GET parameter, even when other data is sent in the request body.
• Any data in the request body should be in JSON format, with the Content-Type: application/json header.

Resource model

SE Visible is organised around projects. Each project tracks one primary brand with a domain, country and language, across a set of AI models. Everything else hangs off the project:

Project (UUID)
├── Brands          primary brand + competitors, each with aliases
├── Topics          groupings of prompts (one default topic per project)
│   └── Prompts     the questions sent to AI models
│       └── Results one result per model run, with text, URLs, brands, sentiment
└── Sources         domains and URLs the AI models cite across the project

• Projects are identified by a UUID (for example 550e8400-e29b-41d4-a716-446655440000).
• Brands, topics, prompts, and results are identified by integer IDs, scoped to their project.
• A new project is processed asynchronously. Poll Get project details and read check.processed_percent and project.status (queued, processing, success, error) to track progress.

Making requests

• GET and DELETE requests take parameters in the query string (Note: DELETE requests for prompts require JSON body prompt_ids). Resource IDs are part of the path (for example /projects/{project_id}/brands).
• POST, PUT, and PATCH requests send their payload as a JSON body and require the Content-Type: application/json header. Resource IDs stay in the path.

Example POST request

curl -X POST 'https://api.seranking.com/v1/se-visible/projects' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "https://lavazza.com",
    "country_code": "US",
    "lang_code": "en",
    "brand_names": ["Lavazza"],
    "topics": ["Ground Coffee", "Espresso Machines"]
  }'

Pagination

List endpoints accept limit and offset and return a total count alongside the items array.

To page through results, increase offset by limit until offset reaches total.

Filtering and array parameters

Many list endpoints share a common set of filters: model_types, country_codes, topic_ids, sentiments, tracked_brand_ids, prompt_ids, and search_query. See the Reference for every accepted value.

Array filters repeat the parameter key, one entry per value:

?model_types=chatgpt&model_types=perplexity&topic_ids=10&topic_ids=12

The brand metrics endpoint uses the bracketed array form for dimensions[] and metrics[]:

?dimensions[]=topic_id&dimensions[]=brand_id&metrics[]=visibility_score

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:

# 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 and a delta (absolute and percentage).

Usage and limits

SE Visible usage is governed by your plan limits, not by per-request credits. Call Get subscription to read your plan and the max, used, and available counts for projects, prompts, and user seats.

Errors

The API uses standard HTTP status codes. Only 2xx responses indicate success. Error bodies are JSON.

Validation error example

{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain field is required."]
  }
}

Support

Questions or issues? Email us at [email protected].