API

Projects

The Projects API creates and manages SE Visible projects. A project tracks one primary brand with a domain, a country and language, across a set of AI models. Everything else in SE Visible (brands, topics, prompts, results, and sources) hangs off a project.

Using the SE Visible API, you can:

list every project in your organisation with its domain, competitive brands, status, and tracked AI models
create a new project and have it processed asynchronously to generate prompts and collect data
read a project’s full details, including processing progress, topics, check dates, and tracked competitor brands
change how often a project is checked (daily or weekly)
delete a project (soft delete, can be restored)

All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.

List projects

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

Returns all projects belonging to the authenticated user’s organisation. Each project includes its domain, tracked brand names, status, and the AI models it runs against.

Request parameters

This endpoint takes no parameters.

Request example

Copy

curl -X GET 'https://api.seranking.com/v1/se-visible/projects' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a JSON array of project objects.

Parameter	Type	Description
id	String (UUID)	Project UUID.
domain	String (URL)	Target domain URL, including protocol.
brand_names	Array of String	Brand names tracked in the project.
created_at	String (datetime)	Project creation timestamp.
checked_at	String (datetime) or null	Most recent successful check completion timestamp. `null` if the project has not completed a check yet.
status	String	Project status: `queued`, `processing`, `success`, or `error`.
models	Array	AI models and country configurations used for this project. Deprecated: contains one entry per engine and location, so an engine repeats once per location and its `country_code` is the location’s, not the project’s. Use List project engines instead; this field will be removed.
models.model_type	String	AI model type: `chatgpt`, `google_gemini`, `google_ai_mode`, or `google_ai_overview`.
models.country_code	String	ISO 3166-1 alpha-2 country code for this model configuration.

Response example

Copy

[

  {

    "id": "550e8400-e29b-41d4-a716-446655440000",

    "domain": "https://lavazza.com",

    "brand_names": ["Lavazza"],

    "created_at": "2023-12-15 10:30:00",

    "checked_at": "2023-12-15 11:45:00",

    "status": "success",

    "models": [

      { "model_type": "chatgpt", "country_code": "US" }

    ]

  }

]

Create project

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

Creates a new project for tracking brand visibility across AI models.

Note:

A new project is queued and processed asynchronously to generate prompts and collect data. The response returns the project id immediately, before processing finishes.
Poll Get project details and read check.processed_percent (0 to 100) and project.status (queued, processing, success, error) to track progress.

Request parameters

Request body

Parameter	Type	Required	Description
domain	String (URL)	Yes	Target domain URL to analyze for brand visibility.
project_name	String or null	No	Name for the project, up to 255 characters. Defaults to `domain` when omitted or `null`.
country_code	String	Yes	ISO 3166-1 alpha-2 country code for project context. For example `US`, `UK`, `CA`, `FR`, `DE`. See the Reference for the full list.
lang_code	String	Yes	ISO 639-1 language code for project context. For example `en`, `fr`, `de`, `es`. See the Reference for the full list.
brand_names	Array of String	Yes	Brand names to track, including variations and aliases. At least one entry, each non-empty and up to 2000 characters.
topics	Array of String	Yes	Topics to track. 1 to 50 entries, each non-empty and up to 2000 characters.
competitors	Array of Object	No	Competitor brands to track from the start. Up to 50 entries.
competitors.brand	String	Yes	Competitor brand name, up to 255 characters. Must be sent together with `domain`.
competitors.domain	String	Yes	Competitor hostname without protocol, up to 255 characters. Must contain a dot, for example `illy.com`. Must be sent together with `brand`.
engines	Array of String	No	AI engines to enable for the project: `chatgpt`, `google_gemini`, `google_ai_mode`, `google_ai_overview`. At least one entry, values must be distinct. When omitted, all available engines are enabled. You can manage engines later with the project engines endpoints. Takes precedence over `models`.
models	Array of String	No	Deprecated: legacy alias for `engines`; use `engines` instead. At least one entry. When both are sent, `engines` wins. When both are omitted, all available engines are enabled.
tracking	Object	No	Tracking cadence for the new project. When omitted, the project is checked `daily` with 1 answer per prompt.
tracking.frequency	String	Yes, if `tracking` is sent	Check period: `daily` or `weekly`. The number of answers analyzed per prompt follows from it (`daily` → 1, `weekly` → 3) and cannot be set directly. You can change it later with Update tracking settings.

Request example

Copy

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",

    "project_name": "Lavazza",

    "country_code": "US",

    "lang_code": "en",

    "brand_names": ["Lavazza"],

    "topics": [

      "Ground Coffee",

      "Whole Bean Coffee",

      "Espresso Machines",

      "Coffee Makers",

      "Accessories"

    ],

    "competitors": [

      { "brand": "Illy", "domain": "illy.com" }

    ],

    "engines": ["chatgpt"],

    "tracking": { "frequency": "weekly" }

  }'

Response parameters

If successful, the server returns the UUID of the newly created project.

Parameter	Type	Description
id	String (UUID)	UUID of the newly created project.

Response example

Copy

{

  "id": "550e8400-e29b-41d4-a716-446655440000"

}

Get project details

GET https://api.seranking.com/v1/se-visible/projects/{project_id}

Returns detailed information about a single project: its metadata, check processing progress, the topics being tracked, available historical check dates, the next scheduled check, the competitor brands attached to it, and its tracking settings.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.

Request example

Copy

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a project details object.

Parameter	Type	Description
project	Object	Project metadata. Same shape as a list item (`id`, `domain`, `brand_names`, `created_at`, `checked_at`, `status`, `models`), plus `country_code`.
project.country_code	String	Country code the project was created for (`UK` for Great Britain).
project.models.model_type	String	AI model type: `chatgpt`, `google_gemini`, `google_ai_mode`, or `google_ai_overview`.
project.models.country_code	String	ISO 3166-1 alpha-2 country code for this model configuration.
country_code	String	Country code the project was created for (`UK` for Great Britain).
check.processed_percent	Integer	Percentage of check processing completion, 0 to 100.
topics	Array	Topics being tracked in this project.
topics.id	Integer	Topic ID.
topics.title	String	Topic title.
topics.is_default	Boolean	`true` for the project’s default topic.
topics.prompts_count	Integer	Number of prompts in this topic.
check_dates	Array of String	Start dates of successful and currently processing checks, sorted ascending, oldest first (`YYYY-MM-DD`).
next_check_date	String (datetime) or null	Next scheduled check date. `null` if no check is scheduled.
tracked_brands	Array	Non-primary brands explicitly attached to the project for competitor tracking.
tracked_brands.brand_id	Integer	Brand ID.
tracked_brands.brand_name	String	Brand name.
tracked_brands.domain	String (URL) or null	Brand domain URL, including protocol. `null` if no domain is set.
has_unparsed_prompts	Boolean	Whether the project has prompts that have not yet been parsed.
tracking	Object	Tracking settings of the project.
tracking.frequency	String	How often the project is checked: `daily` (every day) or `weekly` (once a week, on the weekday the project was created).
tracking.answers_per_prompt	Integer	How many AI answers are analyzed per prompt on each run, 1 to 5. Follows from `frequency` (`daily` → 1, `weekly` → 3) and cannot be set directly.

Response example

Copy

{

  "project": {

    "id": "550e8400-e29b-41d4-a716-446655440000",

    "domain": "https://lavazza.com",

    "brand_names": ["Lavazza"],

    "created_at": "2023-12-15 10:30:00",

    "checked_at": "2023-12-15 11:45:00",

    "status": "success",

    "models": [

      { "model_type": "chatgpt", "country_code": "US" },

      { "model_type": "google_ai_mode", "country_code": "US" }

    ],

    "country_code": "US"

  },

  "country_code": "US",

  "check": {

    "processed_percent": 75

  },

  "topics": [

    { "id": 1, "title": "Default", "is_default": true, "prompts_count": 0 },

    { "id": 2, "title": "Ground Coffee", "is_default": false, "prompts_count": 10 },

    { "id": 3, "title": "Whole Bean Coffee", "is_default": false, "prompts_count": 8 }

  ],

  "check_dates": ["2023-12-13", "2023-12-14", "2023-12-15"],

  "next_check_date": "2023-12-22 10:00:00",

  "tracked_brands": [

    {

      "brand_id": 10,

      "brand_name": "Illy",

      "domain": "https://illy.com"

    },

    {

      "brand_id": 11,

      "brand_name": "Nespresso",

      "domain": null

    }

  ],

  "has_unparsed_prompts": false,

  "tracking": {

    "frequency": "weekly",

    "answers_per_prompt": 3

  }

}

Update tracking settings

PATCH https://api.seranking.com/v1/se-visible/projects/{project_id}/settings/tracking

Changes how often a project is checked.

Note:

The number of answers analyzed per prompt follows from the period and cannot be set: daily analyzes 1 answer per prompt on each run, weekly analyzes 3.
Weekly checks run on the weekday the project was created. You cannot pick a different weekday.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.

Request body

Parameter	Type	Required	Description
frequency	String	Yes	Check period for the project: `daily` or `weekly`.

Request example

Copy

curl -X PATCH 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/settings/tracking' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "frequency": "daily"

  }'

Response parameters

If successful, the server returns the updated tracking settings.

Parameter	Type	Description
frequency	String	How often the project is checked: `daily` (every day) or `weekly` (once a week, on the weekday the project was created).
answers_per_prompt	Integer	How many AI answers are analyzed per prompt on each run, 1 to 5. Follows from `frequency` (`daily` → 1, `weekly` → 3).

Response example

Copy

{

  "frequency": "daily",

  "answers_per_prompt": 1

}

Delete a project

DELETE https://api.seranking.com/v1/se-visible/projects/{project_id}

Soft-deletes a project from your organisation. The project is removed from active use but can be restored if needed.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.

Request example

Copy

curl -X DELETE 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns 204 No Content with an empty body.

Projects

List projects

Request parameters

Request example

Response parameters

Response example

Create project

Request parameters

Request example

Response parameters

Response example

Get project details

Request parameters

Request example

Response parameters

Response example

Update tracking settings

Request parameters

Request example

Response parameters

Response example

Delete a project

Request parameters

Request example

Response parameters

Learn how SE Ranking’s API can boost your SEO!

Request a free demo to see our tools and integrations in action