Get share of voice

curl --request GET \
  --url https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "project": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "domain": "<string>",
    "brandName": "<string>"
  },
  "brand": {
    "name": "<string>",
    "sov": 123,
    "rank": 123,
    "delta": 123
  },
  "competitors": [
    {
      "name": "<string>",
      "domain": "<string>",
      "sov": 123,
      "rank": 123,
      "delta": 123,
      "mentions": null,
      "citations": null,
      "previousSov": 123,
      "sovDelta": 123
    }
  ],
  "dateRange": {
    "from": "2023-11-07T05:31:56Z",
    "to": "2023-11-07T05:31:56Z"
  },
  "totalCompetitors": 123,
  "comparison": {
    "dateRange": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "brand": {
      "previousSov": 123,
      "sovDelta": 123,
      "previousRank": 123
    }
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

GET

api

mcp

projects

{projectId}

share-of-voice

Get share of voice

curl --request GET \
  --url https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "project": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "domain": "<string>",
    "brandName": "<string>"
  },
  "brand": {
    "name": "<string>",
    "sov": 123,
    "rank": 123,
    "delta": 123
  },
  "competitors": [
    {
      "name": "<string>",
      "domain": "<string>",
      "sov": 123,
      "rank": 123,
      "delta": 123,
      "mentions": null,
      "citations": null,
      "previousSov": 123,
      "sovDelta": 123
    }
  ],
  "dateRange": {
    "from": "2023-11-07T05:31:56Z",
    "to": "2023-11-07T05:31:56Z"
  },
  "totalCompetitors": 123,
  "comparison": {
    "dateRange": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z"
    },
    "brand": {
      "previousSov": 123,
      "sovDelta": 123,
      "previousRank": 123
    }
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "error": "<string>",
  "message": "<string>",
  "howToFix": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "requiresUpgrade": true,
  "retryable": true,
  "timeout": true,
  "quotaExceeded": true,
  "current": 123,
  "limit": 123,
  "bulkLimitExceeded": true,
  "requested": 123,
  "maxAllowed": 123,
  "details": {
    "formErrors": [
      "<string>"
    ],
    "fieldErrors": {}
  }
}

Authorizations

Authorization

string

header

required

A Searchable API key, created under Settings → Workspace → Integrations. Send as Authorization: Bearer sea_xxxxx. Every key carries one or more scopes (read, write, admin) and may optionally be bound to a single project — see Getting started.

Path Parameters

projectId

string<uuid>

required

The project id.

Query Parameters

days

integer

Lookback window in days. Default and maximum vary by endpoint — see the operation description.

Required range: x >= 1

platform

string

Comma-separated AI platform filter (e.g. chatgpt,claude,gemini). Accepted values and whether the param is required vary by endpoint — see the operation description.

topicId

string<uuid>

Restrict to a single topic id.

unbranded

enum<string>

Pass true to restrict every metric to non-branded prompts only.

Available options:

true

branded

enum<string>

Pass true to restrict every metric to branded prompts only.

Available options:

true

country

string

Comma-separated ISO 3166-1 country codes (e.g. US,GB) or country names.

locationId

string

Comma-separated tracked-location ids.

compare

enum<string>

Period comparison. previous_period re-runs the same metrics over the window immediately before the current one (same length); previous_year over the same window shifted back exactly 365 days. The response gains an additive comparison block: { mode, dateRange, previous, delta } — delta is current minus previous for every shared numeric metric (on /visibility/topics, per-topic deltas ride inline on each topic row instead). Invalid values return 400 invalid_argument.

Available options:

previous_period,

previous_year

from

string

Start of an absolute window (inclusive, UTC). Accepts YYYY-MM-DD or a full ISO timestamp. Requires to, and is mutually exclusive with days — sending both returns 400 invalid_argument. A range longer than the endpoint's maximum is rejected rather than clamped.

Example:

"2026-03-01"

string

End of an absolute window (inclusive, UTC). Accepts YYYY-MM-DD or a full ISO timestamp. Requires from.

Example:

"2026-03-31"

Response

Share of voice.

project

object

required

Show child attributes

brand

object

required

Show child attributes

competitors

object[]

required

Show child attributes

dateRange

object

required

The resolved lookback window for this response.

Show child attributes

totalCompetitors

integer

comparison

object

Present only when compare was passed. Per-competitor previous shares ride INLINE on each competitor row (previousSov/sovDelta, matched by entity display name — the share-of-voice entity identity).

Show child attributes

Get Started

Endpoints

Get share of voice

Authorizations

Path Parameters

Query Parameters

Response