curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/topics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/topics"
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}/topics', 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}/topics",
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}/topics"
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}/topics")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/topics")
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{
"ai_visits_connected": true,
"cards": {
"ai_visits": 123,
"cited": 123,
"cited_change": {
"baseline": "<string>",
"delta": 123,
"direction": "up",
"label": "<string>"
},
"covered": 123,
"covered_change": {
"baseline": "<string>",
"delta": 123,
"direction": "up",
"label": "<string>"
},
"missing": 123,
"missing_new": 123,
"total": 123
},
"cited": 123,
"covered": 123,
"limit": 123,
"menus": {
"intents": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"segments": [
{
"count": 123,
"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": {}
},
"missing": 123,
"next_cursor": "<string>",
"not_read_line": "<string>",
"offset": 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
},
"search_connected": true,
"sentence": "<string>",
"state": "ready",
"statuses": [
{
"count": 123,
"label": "<string>",
"value": "missing"
}
],
"topics": [
{
"action": "write",
"action_label": "<string>",
"ai_visits": 123,
"citations": 123,
"demand": 123,
"id": "<string>",
"open_action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"title": "<string>",
"url": "<string>"
},
"piece": {
"action_id": "<string>",
"piece_id": "<string>",
"stage": "<string>",
"stage_words": "<string>"
},
"search_clicks": 123,
"status": "missing",
"status_label": "<string>",
"topic": "<string>",
"why": "<string>"
}
],
"total": 123
}{
"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"
}Get Topics
The topics buyers ask about from the latest scan’s content pass in the period, each with the brand’s page for it and its status, most demand first.
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/topics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/topics"
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}/topics', 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}/topics",
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}/topics"
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}/topics")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/topics")
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{
"ai_visits_connected": true,
"cards": {
"ai_visits": 123,
"cited": 123,
"cited_change": {
"baseline": "<string>",
"delta": 123,
"direction": "up",
"label": "<string>"
},
"covered": 123,
"covered_change": {
"baseline": "<string>",
"delta": 123,
"direction": "up",
"label": "<string>"
},
"missing": 123,
"missing_new": 123,
"total": 123
},
"cited": 123,
"covered": 123,
"limit": 123,
"menus": {
"intents": [
{
"count": 123,
"label": "<string>",
"value": "<string>"
}
],
"segments": [
{
"count": 123,
"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": {}
},
"missing": 123,
"next_cursor": "<string>",
"not_read_line": "<string>",
"offset": 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
},
"search_connected": true,
"sentence": "<string>",
"state": "ready",
"statuses": [
{
"count": 123,
"label": "<string>",
"value": "missing"
}
],
"topics": [
{
"action": "write",
"action_label": "<string>",
"ai_visits": 123,
"citations": 123,
"demand": 123,
"id": "<string>",
"open_action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"title": "<string>",
"url": "<string>"
},
"piece": {
"action_id": "<string>",
"piece_id": "<string>",
"stage": "<string>",
"stage_words": "<string>"
},
"search_clicks": 123,
"status": "missing",
"status_label": "<string>",
"topic": "<string>",
"why": "<string>"
}
],
"total": 123
}{
"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
perplexity, gemini, openai, google_aio, ai_mode, copilot, claude organic, brand_specific, competitor_comparison educational, problem, comparison, transactional Include only scans up to this completed scan id.
1 <= x <= 100x >= 040961w, 4w, 12w, all missing, cited, falls_short, ranks_in_search, not_cited 200topic, status, demand, citations, search_clicks, ai_visits, rank asc, desc 4096Response
Successful Response
Topics buyers ask about from the latest scan's content pass in the period.
Show child attributes
Show child attributes
Topics whose page is cited. Null where a weekly scan it covers could not keep all its citations.
What the toolbar's four menus offer, counted over every tracked prompt rather than over the page (PR-4). A menu built from one page of ten would hide the segment the eleventh row is in.
Show child attributes
Show child attributes
Normalized query and newest included scan.
Show child attributes
Show child attributes
Null when the read saw too little of the site.
Pass as cursor with the same query to read the next page; null at the end.
Show child attributes
Show child attributes
ready, awaiting_first_scan, not_measured Show child attributes
Show child attributes
Show child attributes
Show child attributes