Get Sources
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/sources \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/sources"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.heralded.ai/v1/brands/{brand_id}/sources', 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://api.heralded.ai/v1/brands/{brand_id}/sources",
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://api.heralded.ai/v1/brands/{brand_id}/sources"
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://api.heralded.ai/v1/brands/{brand_id}/sources")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/sources")
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{
"cards": {
"answers": 0,
"citations": 0,
"citations_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"competitors_pages_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"competitors_pages_change_pts": 123,
"competitors_pages_share_pct": 123,
"sites": 0,
"sites_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"sites_naming_you": 0,
"your_pages_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"your_pages_change_pts": 123,
"your_pages_share_pct": 123
},
"citation_evidence": "complete",
"limit": 123,
"menus": {
"intents": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"prompts": [
{
"label": "<string>",
"value": "<string>"
}
],
"segments": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"source_types": [
{
"label": "<string>",
"value": "<string>"
}
],
"topics": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"types": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
]
},
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"mix": [
{
"citations": 123,
"key": "<string>",
"label": "<string>",
"owner": "third_party",
"share_pct": 123
}
],
"next_cursor": "<string>",
"offset": 123,
"pages_total": 123,
"period": {
"excluded_reports": 123,
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"preset": "1w",
"reports": 123
},
"sentence": "<string>",
"sites_total": 123,
"sources": [
{
"answers": 123,
"answers_share_pct": 123,
"authority": 123,
"change": {
"current": 123,
"delta": 123,
"direction": "up",
"label": "<string>",
"previous": 123
},
"citation_share_pct": 123,
"citations": 123,
"citations_naming_rivals": 123,
"citations_naming_you": 123,
"domain": "<string>",
"engines": [
"perplexity"
],
"group": "own",
"names_you": true,
"opportunity_score": 123,
"owner": "third_party",
"owner_label": "<string>",
"ownership": "own",
"priority": 123,
"priority_reason": "<string>",
"prompts": 123,
"read_pages_naming_you": 123,
"source_type": "industry_authority",
"source_type_label": "<string>"
}
],
"state": "ready",
"total": 123,
"unavailable_scans": 0,
"worth_pursuing": [
{
"action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"citations": 123,
"domain": "<string>",
"reason": "<string>",
"source_type": "industry_authority",
"source_type_label": "<string>",
"title": "<string>"
}
],
"worth_pursuing_total": 0
}{
"code": "invalid_cursor",
"detail": "The cursor is invalid or belongs to a different query.",
"instance": "example-request-id",
"status": 400,
"title": "Bad Request",
"type": "about:blank"
}{
"code": "invalid_token",
"detail": "The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.",
"instance": "example-request-id",
"status": 401,
"title": "Unauthorized",
"type": "about:blank"
}{
"code": "not_found",
"detail": "Nothing here that this API key can read.",
"instance": "example-request-id",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}{
"code": "workspace_archived",
"detail": "The API key's organization is archived.",
"instance": "example-request-id",
"status": 409,
"title": "Conflict",
"type": "about:blank"
}{
"code": "invalid_request",
"detail": "The request's parameters are invalid; `errors` names each one.",
"errors": [
{
"loc": [
"query",
"limit"
],
"msg": "Input should be less than or equal to 100",
"type": "less_than_equal"
}
],
"instance": "example-request-id",
"status": 422,
"title": "Unprocessable Content",
"type": "about:blank"
}{
"code": "rate_limited",
"detail": "This caller is past its requests for the minute. Retry after the seconds in Retry-After.",
"instance": "example-request-id",
"rate_limit": {
"limit": 120,
"remaining": 0,
"reset": 60,
"window": 60
},
"status": 429,
"title": "Too Many Requests",
"type": "about:blank"
}Visibility
Get Sources
The domains the engines cited over the selected period, daily answers included.
GET
/
v1
/
brands
/
{brand_id}
/
sources
Get Sources
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/sources \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/sources"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.heralded.ai/v1/brands/{brand_id}/sources', 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://api.heralded.ai/v1/brands/{brand_id}/sources",
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://api.heralded.ai/v1/brands/{brand_id}/sources"
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://api.heralded.ai/v1/brands/{brand_id}/sources")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/sources")
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{
"cards": {
"answers": 0,
"citations": 0,
"citations_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"competitors_pages_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"competitors_pages_change_pts": 123,
"competitors_pages_share_pct": 123,
"sites": 0,
"sites_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"sites_naming_you": 0,
"your_pages_change": {
"current": 123,
"delta": 123,
"direction": "unmeasured",
"label": "No comparable previous period",
"previous": 123
},
"your_pages_change_pts": 123,
"your_pages_share_pct": 123
},
"citation_evidence": "complete",
"limit": 123,
"menus": {
"intents": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"prompts": [
{
"label": "<string>",
"value": "<string>"
}
],
"segments": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"source_types": [
{
"label": "<string>",
"value": "<string>"
}
],
"topics": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"types": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
]
},
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"mix": [
{
"citations": 123,
"key": "<string>",
"label": "<string>",
"owner": "third_party",
"share_pct": 123
}
],
"next_cursor": "<string>",
"offset": 123,
"pages_total": 123,
"period": {
"excluded_reports": 123,
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"preset": "1w",
"reports": 123
},
"sentence": "<string>",
"sites_total": 123,
"sources": [
{
"answers": 123,
"answers_share_pct": 123,
"authority": 123,
"change": {
"current": 123,
"delta": 123,
"direction": "up",
"label": "<string>",
"previous": 123
},
"citation_share_pct": 123,
"citations": 123,
"citations_naming_rivals": 123,
"citations_naming_you": 123,
"domain": "<string>",
"engines": [
"perplexity"
],
"group": "own",
"names_you": true,
"opportunity_score": 123,
"owner": "third_party",
"owner_label": "<string>",
"ownership": "own",
"priority": 123,
"priority_reason": "<string>",
"prompts": 123,
"read_pages_naming_you": 123,
"source_type": "industry_authority",
"source_type_label": "<string>"
}
],
"state": "ready",
"total": 123,
"unavailable_scans": 0,
"worth_pursuing": [
{
"action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"citations": 123,
"domain": "<string>",
"reason": "<string>",
"source_type": "industry_authority",
"source_type_label": "<string>",
"title": "<string>"
}
],
"worth_pursuing_total": 0
}{
"code": "invalid_cursor",
"detail": "The cursor is invalid or belongs to a different query.",
"instance": "example-request-id",
"status": 400,
"title": "Bad Request",
"type": "about:blank"
}{
"code": "invalid_token",
"detail": "The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired.",
"instance": "example-request-id",
"status": 401,
"title": "Unauthorized",
"type": "about:blank"
}{
"code": "not_found",
"detail": "Nothing here that this API key can read.",
"instance": "example-request-id",
"status": 404,
"title": "Not Found",
"type": "about:blank"
}{
"code": "workspace_archived",
"detail": "The API key's organization is archived.",
"instance": "example-request-id",
"status": 409,
"title": "Conflict",
"type": "about:blank"
}{
"code": "invalid_request",
"detail": "The request's parameters are invalid; `errors` names each one.",
"errors": [
{
"loc": [
"query",
"limit"
],
"msg": "Input should be less than or equal to 100",
"type": "less_than_equal"
}
],
"instance": "example-request-id",
"status": 422,
"title": "Unprocessable Content",
"type": "about:blank"
}{
"code": "rate_limited",
"detail": "This caller is past its requests for the minute. Retry after the seconds in Retry-After.",
"instance": "example-request-id",
"rate_limit": {
"limit": 120,
"remaining": 0,
"reset": 60,
"window": 60
},
"status": 429,
"title": "Too Many Requests",
"type": "about:blank"
}Authorizations
An API key, sent as Authorization: Bearer hrld_....
Path Parameters
Query Parameters
Available options:
perplexity, gemini, openai, google_aio, ai_mode, copilot, claude Available options:
organic, brand_specific, competitor_comparison Available options:
educational, problem, comparison, transactional Include only scans up to this completed scan id.
Required range:
1 <= x <= 100Required range:
x >= 0Maximum string length:
4096Available options:
1w, 4w, 12w, all Available options:
third_party, competitor, yours Available options:
industry_authority, review, regulatory, media, educational, community, consulting, social, vendor, directory, unclassified Maximum string length:
300Maximum string length:
200Available options:
asc, desc Available options:
domain, citations, answers, change, priority Response
Successful Response
Show child attributes
Show child attributes
Available options:
complete, partial, unavailable The page's filter menus: the prompt set's four, every source type and every tracked prompt. None follows the filters, so choosing one hides no other.
Show child attributes
Show child attributes
Normalized query and newest included scan.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Pass as cursor with the same query to read the next page; null at the end.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
ready, awaiting_first_scan, unavailable Show child attributes
Show child attributes