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. Without query parameters, the full list is returned.

Request parameters

Path parameters

Query parameters

Note:

• Parameters are applied in this order: search_query, then offset, then limit.
• The response is a flat array with no pagination envelope. The response to a request without parameters is unchanged.
• An invalid search_query, limit, or offset returns 422.

Request example

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/brands/mentioned?search_query=nike&limit=100&offset=0' \

  -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.
• Every metric value is an object, not a plain number: { "values": [v0] } in single-period mode. Passing date_range[1] enables compare mode, which adds the second period and a delta object: { "values": [v0, v1], "delta": { "absolute": 12, "percentage": 40 } }. Deltas are returned only in compare mode.
• With 1 dimension, each row holds the dimension key plus one key per metric. With 2 or 3 dimensions, meta.columns.dynamic lists the pivot IDs, and each row gains one nested object per pivot ID — keyed by that ID — mapping each metric name to its value object. A pivot with no data for a metric is null.
• date_range[0] is the base period. Add date_range[1] to compare against a second period.
• aio_overlap and aio_presence are brand-agnostic: they are aggregated over all prompt results in the group, not only the responses that mention a tracked brand, so they stay constant across the brand pivot. Sorting by these metrics is not supported.

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.

Note: value ranges — sentiment_score is -100–100. visibility_score, share_of_voice, positive_pct, neutral_pct, negative_pct, aio_overlap, and aio_presence are 0–100.

Response example

1D (single dimension)

{

  "meta": {

    "pagination": { "total": 145 },

    "columns": { "primary": "topic_id", "dynamic": [] }

  },

  "data": [

    { "topic_id": 5, "visibility_score": { "values": [95] } },

    { "topic_id": 7, "visibility_score": { "values": [41] } }

  ]

}

1D in compare mode (two periods)

{

  "meta": {

    "pagination": { "total": 145 },

    "columns": { "primary": "brand_id", "dynamic": [] }

  },

  "data": [

    {

      "brand_id": 12,

      "total_mentions": {

        "values": [42, 30],

        "delta": { "absolute": 12, "percentage": 40 }

      }

    },

    {

      "brand_id": 15,

      "total_mentions": {

        "values": [27, 31],

        "delta": { "absolute": -4, "percentage": -12.9 }

      }

    }

  ]

}

2D (second dimension pivoted)

{

  "meta": {

    "pagination": { "total": 145 },

    "columns": { "primary": "topic_id", "dynamic": [12, 15, 8] }

  },

  "data": [

    {

      "topic_id": 5,

      "12": { "visibility_score": { "values": [95] } },

      "15": { "visibility_score": { "values": [82] } },

      "8": { "visibility_score": { "values": [15] } }

    },

    {

      "topic_id": 7,

      "12": { "visibility_score": { "values": [41] } },

      "15": { "visibility_score": { "values": [98] } },

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

  ]

}