Skip to main content
GET
/
api
/
v1
/
projects
/
{project}
/
brand-rankings
Brand Rankings
curl --request GET \
  --url https://app.surfacd.com/api/v1/projects/{project}/brand-rankings \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://app.surfacd.com/api/v1/projects/{project}/brand-rankings"

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

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

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.surfacd.com/api/v1/projects/{project}/brand-rankings', 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.surfacd.com/api/v1/projects/{project}/brand-rankings",
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.surfacd.com/api/v1/projects/{project}/brand-rankings"

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))

}
HttpResponse<String> response = Unirest.get("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")

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
{
  "data": [
    {
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "domain": "<string>",
      "mentions_count": 123,
      "total_responses": 123,
      "visibility_score": 123,
      "rank": 123,
      "ranking_date": "2023-12-25",
      "average_position": 123,
      "previous_rank": 123,
      "previous_visibility_score": 123,
      "previous_mentions_count": 123,
      "previous_average_position": 123
    }
  ],
  "meta": {
    "current_page": 123,
    "last_page": 123,
    "per_page": 123,
    "total": 123,
    "from": 123,
    "links": [
      {
        "url": "<string>",
        "label": "<string>",
        "active": true
      }
    ],
    "path": "<string>",
    "to": 123
  },
  "links": {
    "first": "<string>",
    "last": "<string>",
    "prev": "<string>",
    "next": "<string>"
  }
}
{
"message": "<string>",
"errors": {}
}

Authorizations

Authorization
string
header
required

Team API key created in Team Settings. Use it with URLs for the same team.

Path Parameters

project
string<uuid>
required

Project UUID.

Query Parameters

start_date
string<date>
required

Inclusive start of the reporting window. YYYY-MM-DD.

end_date
string<date>
required

Inclusive end of the reporting window. YYYY-MM-DD. Must be on or after start_date.

page
integer
Required range: x >= 1
per_page
integer
default:50
Required range: 1 <= x <= 100
brands
string<uuid>[]

Brand UUID filter. Pass a single brand UUID as brands[]=....

Maximum array length: 1
tags
string<uuid>[]

Tag UUID filters. Discover tag UUIDs with GET /api/v1/projects/{project}/tags.

services
string[]

AI platform provider filters such as chatgpt or perplexity. Discover providers with GET /api/v1/platforms.

countries
string[]

Country code filters such as US or GB. Discover codes with GET /api/v1/countries.

prompt
string<uuid>

Prompt UUID filter.

topics
string[]

Topic UUID filters. Use no_topic for prompts without a topic. Discover topic UUIDs with GET /api/v1/projects/{project}/topics.

Maximum string length: 255
competitors_only
boolean

When true, only the primary brand and marked competitors are included.

only_brand
boolean

When true and brands contains one brand UUID, only that brand's ranking is returned.

always_include_brand
boolean

When true and brands contains one brand UUID, the pinned brand is always included in the paginated result even if it would not otherwise appear on the current page.

Response

Paginated brand rankings.

data
object[]
required
meta
object
required