Brands

The Brands API manages the brands tracked inside a project: the primary brand and its competitors, along with their aliases. It also surfaces brands that AI models mentioned in your results and aggregated visibility metrics.

Using the SE Visible API, you can:

• list a project’s tracked brands (primary brand and competitors) with their aliases
• add competitor brands and manage their aliases
• see which brands AI models mentioned in a project’s results
• pull aggregated brand metrics such as visibility score, share of voice, sentiment, and brand’s average position in AI answers

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

List tracked brands

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

Returns all brands tracked in a project, including the primary brand and competitors. The primary brand has is_primary: true and is listed first. Each brand includes its domain and aliases.

Request parameters

Path parameters

Request example

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

Response parameters

If successful, the server returns a JSON array of tracked brands.

Response example

[
  {
    "id": 1,
    "title": "Nike",
    "domain": "https://nike.com",
    "is_primary": true,
    "aliases": [
      { "id": 2, "title": "Nike Running" },
      { "id": 3, "title": "Nike Basketball" }
    ]
  },
  {
    "id": 4,
    "title": "Adidas",
    "domain": "https://adidas.com",
    "is_primary": false,
    "aliases": [
      { "id": 5, "title": "Adidas Running" }
    ]
  }
]

Create competitor brand

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

Creates a new competitor brand with a domain and optional aliases.

Request parameters

Path parameters

Request body

Request example

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/brands' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Adidas",
    "domain": "https://adidas.com",
    "aliases": [
      { "title": "Adidas Running" }
    ]
  }'

Response parameters

If successful, the server returns the created brand as a tracked brand object.

Response example

{
  "id": 4,
  "title": "Adidas",
  "domain": "https://adidas.com",
  "is_primary": false,
  "aliases": [
    { "id": 5, "title": "Adidas Running" }
  ]
}

List mentioned brands

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

Returns all brands detected in the project’s AI check results. These are distinct from the brands you manually track, and are useful for discovering competitors to add.

Request parameters

Path parameters

Request example

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

Response parameters

If successful, the server returns a JSON array of mentioned brands.

Response example

[
  { "brand_id": 10, "brand": "Nike" },
  { "brand_id": 11, "brand": "Adidas" }
]

Get aggregated brand metrics

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

Returns aggregated brand metrics for dynamic table rendering. You choose how the data is grouped (dimensions[]) and which metrics to return (metrics[]).

Note:

• You pass 1 to 3 dimensions. The last dimension is always the pivot (it becomes columns); all preceding dimensions define the row grouping.
• With 1 dimension, the response is flat rows with one key per metric. With 2 or 3 dimensions, meta.columns.dynamic lists the pivot IDs and each row gains {pivotId}_{metric} keys, with null where there is no data.
• date_range[0] is the base period. Add date_range[1] to compare against a second period.

Request parameters

Path parameters

Query parameters

Request example

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/brands/metrics?dimensions[]=topic_id&dimensions[]=brand_id&metrics[]=visibility_score&date_range[0][from]=2026-05-01&date_range[0][to]=2026-05-31' \
  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a metrics object with pagination, column layout, and the data rows.

Response example

1D (single dimension)

{
  "meta": {
    "pagination": { "total": 145 },
    "columns": { "primary": "topic_id", "dynamic": [] }
  },
  "data": [
    { "topic_id": 5, "visibility_score": 9500 },
    { "topic_id": 7, "visibility_score": 4100 }
  ]
}

2D (second dimension pivoted)

{
  "meta": {
    "pagination": { "total": 145 },
    "columns": { "primary": "topic_id", "dynamic": [12, 15, 8] }
  },
  "data": [
    { "topic_id": 5, "12_visibility_score": 9500, "15_visibility_score": 8200, "8_visibility_score": 150 },
    { "topic_id": 7, "12_visibility_score": 4100, "15_visibility_score": 9800, "8_visibility_score": null }
  ]
}

Update brand

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

Updates a brand’s domain and/or syncs its aliases. When aliases is provided, it replaces all existing aliases (new ones are added, existing kept, absent ones removed). Pass an empty array to clear all aliases. Both body fields are optional.

Request parameters

Path parameters

Request body

Request example

curl -X PATCH 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/brands/4' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "https://new-domain.com",
    "aliases": [
      { "title": "Brand Alias 1" }
    ]
  }'

Response parameters

If successful, the server returns the updated brand as a tracked brand object (id, title, domain, is_primary, aliases).

Response example

{
  "id": 4,
  "title": "Adidas",
  "domain": "https://new-domain.com",
  "is_primary": false,
  "aliases": [
    { "id": 9, "title": "Brand Alias 1" }
  ]
}

Delete brand

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

Deletes a brand and all its aliases.

Note:

• The primary brand cannot be deleted. Attempting to do so returns 422 with the message “Cannot delete the primary brand”.

Request parameters

Path parameters

Request example

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

Response parameters

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

Add aliases to brand

POST https://api.seranking.com/v1/se-visible/projects/{project_id}/brands/{brand_id}/aliases

Adds one or more aliases to an existing brand. Works for both the primary brand and competitors.

Request parameters

Path parameters

Request body

The body is a JSON array of alias objects.

Request example

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/brands/4/aliases' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    { "title": "New Alias 1" }
  ]'

Response parameters

If successful, the server returns the brand as a tracked brand object with the updated aliases array (id, title, domain, is_primary, aliases).

Response example

{
  "id": 4,
  "title": "Adidas",
  "domain": "https://adidas.com",
  "is_primary": false,
  "aliases": [
    { "id": 5, "title": "Adidas Running" },
    { "id": 12, "title": "New Alias 1" }
  ]
}