curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id}"
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/{topic_id}', 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/{topic_id}",
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/{topic_id}"
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/{topic_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id}")
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{
"action": "write",
"action_label": "<string>",
"ai_visits": 123,
"answers_link": {
"href": "<string>"
},
"citation_evidence": "complete",
"citations": 123,
"demand": 123,
"id": "<string>",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"open_action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"title": "<string>",
"url": "<string>"
},
"page_checks": {
"answers": "pass",
"read_at": "2023-11-07T05:31:56Z",
"readable": true,
"readable_reason": "<string>",
"substance": "pass",
"words": 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
},
"piece": {
"action_id": "<string>",
"piece_id": "<string>",
"stage": "<string>",
"stage_words": "<string>"
},
"prompts": [
{
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"score": {
"answer_read_id": "<string>",
"answers": 123,
"band": "<string>",
"key": "<string>",
"label": "<string>",
"state": "measured",
"tooltip": "<string>",
"value": 123
},
"text": "<string>",
"trend": {
"delta": 123,
"label": "<string>",
"state": "up"
}
}
],
"prompts_total": 123,
"question_total": 123,
"questions": [
{
"covered": true,
"label": "<string>",
"source": "synthetic"
}
],
"questions_answered": 123,
"search_clicks": 123,
"sources": [
{
"citations": 123,
"domain": "<string>",
"group": "<string>",
"group_label": "<string>",
"relation": "yours",
"relation_label": "<string>",
"title": "<string>",
"url": "<string>"
}
],
"status": "missing",
"status_label": "<string>",
"top_query": "<string>",
"topic": "<string>",
"unavailable_scans": 0,
"why": "<string>"
}{
"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 Topic
One topic: its page, the questions it expands into, its prompts and the pages they cite most. Take the id from topics, URL-encoded.
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id}"
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/{topic_id}', 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/{topic_id}",
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/{topic_id}"
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/{topic_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/topics/{topic_id}")
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{
"action": "write",
"action_label": "<string>",
"ai_visits": 123,
"answers_link": {
"href": "<string>"
},
"citation_evidence": "complete",
"citations": 123,
"demand": 123,
"id": "<string>",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"open_action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"path": "<string>",
"title": "<string>",
"url": "<string>"
},
"page_checks": {
"answers": "pass",
"read_at": "2023-11-07T05:31:56Z",
"readable": true,
"readable_reason": "<string>",
"substance": "pass",
"words": 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
},
"piece": {
"action_id": "<string>",
"piece_id": "<string>",
"stage": "<string>",
"stage_words": "<string>"
},
"prompts": [
{
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"score": {
"answer_read_id": "<string>",
"answers": 123,
"band": "<string>",
"key": "<string>",
"label": "<string>",
"state": "measured",
"tooltip": "<string>",
"value": 123
},
"text": "<string>",
"trend": {
"delta": 123,
"label": "<string>",
"state": "up"
}
}
],
"prompts_total": 123,
"question_total": 123,
"questions": [
{
"covered": true,
"label": "<string>",
"source": "synthetic"
}
],
"questions_answered": 123,
"search_clicks": 123,
"sources": [
{
"citations": 123,
"domain": "<string>",
"group": "<string>",
"group_label": "<string>",
"relation": "yours",
"relation_label": "<string>",
"title": "<string>",
"url": "<string>"
}
],
"status": "missing",
"status_label": "<string>",
"top_query": "<string>",
"topic": "<string>",
"unavailable_scans": 0,
"why": "<string>"
}{
"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_....
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.
1w, 4w, 12w, all Response
Successful Response
write, rewrite Show child attributes
Show child attributes
complete, partial, unavailable The page's citations in the period; null on a missing topic. Null where a weekly scan it covers could not keep all its citations.
The topic's key, which topics/{id} takes.
Normalized query and newest included scan.
Show child attributes
Show child attributes
The brand's page for it; null when missing.
Show child attributes
Show child attributes
Null on a missing topic.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The piece a Missing topic already has, in the words Studio uses.
piece_id is null while the order is still being placed: the brand's
first order is dispatched before its writing profile exists, and the
piece row is written once the worker has one.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The pages its prompts cite most.
Show child attributes
Show child attributes
missing, cited, falls_short, ranks_in_search, not_cited The page's top Search Console query.