curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_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}/pages/{page_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}/pages/{page_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}/pages/{page_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}/pages/{page_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_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{
"ai_visits": 123,
"ai_visits_by_assistant": [
{
"assistant": "<string>",
"sessions": 123
}
],
"answers_link": {
"href": "<string>"
},
"change": {
"at": "2023-11-07T05:31:56Z",
"delta": 123,
"kind": "improved"
},
"changed_at": "2023-11-07T05:31:56Z",
"checks": [
{
"detail": "<string>",
"key": "<string>",
"short": true
}
],
"citation_evidence": "complete",
"citation_share_pct": 123,
"citations": 123,
"cited_in": "tracked",
"cited_on": [
{
"answers": [
{
"answer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"answered_at": "2023-11-07T05:31:56Z",
"cites_page": true,
"engine": "perplexity",
"mentioned": true,
"recommended": true,
"states": {
"icon_states": {
"mentioned": "yes",
"praised": "yes",
"recommended": "yes",
"understood": "yes"
},
"mentioned": true,
"praised": true,
"recommended": true,
"understood": 123
},
"strength": "<string>",
"strength_label": "<string>"
}
],
"intent": "<string>",
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"query_id": "<string>",
"text": "<string>"
}
],
"coverage": {
"end": "2023-12-25",
"start": "2023-12-25"
},
"crawled_at": "2023-11-07T05:31:56Z",
"crawler_bots": [
{
"bot": "<string>",
"category": "training",
"hits": 123,
"operator": "<string>"
}
],
"crawler_hits": 123,
"crawler_hits_days": 123,
"delivered_at": "2023-11-07T05:31:56Z",
"delivery_cited_at": "2023-11-07T05:31:56Z",
"engines_citing": 123,
"engines_read": 123,
"first_cited_at": "2023-11-07T05:31:56Z",
"funnel": {
"ai_visits": 123,
"blocked": 123,
"cited": 123,
"crawled": 123,
"crawler_bots": [
{
"bot": "<string>",
"category": "training",
"hits": 123,
"operator": "<string>"
}
],
"fetched_live": 123,
"not_found": 123,
"search_clicks": 123,
"search_engine_crawls": 123,
"search_impressions": 123,
"sources": [
"<string>"
],
"unverified": 123,
"window": {
"clamped": true,
"end": "2023-12-25",
"history_days": 123,
"start": "2023-12-25"
}
},
"funnel_series": [
{
"ai_visits": 123,
"cited": 123,
"crawled": 123,
"end": "2023-12-25",
"fetched_live": 123,
"search_clicks": 123,
"start": "2023-12-25"
}
],
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_cited_at": "2023-11-07T05:31:56Z",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"page_type": "<string>",
"page_type_decided_by": "model",
"page_type_source": "member",
"path": "<string>",
"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": 123,
"prompts_tracked": 123,
"read": true,
"reason": "<string>",
"rival_urls": [
"<string>"
],
"rubric": {
"pillars": [
{
"detail": "<string>",
"key": "eligible",
"status": "pass"
}
],
"priority": "ineligible",
"score": 123
},
"search": {
"clicks": 123,
"impressions": 123,
"pages_read": 123,
"position": 123,
"state": "ready",
"top_queries": [],
"top_queries_read": true,
"unavailable_reason": "<string>",
"window_end": "<string>",
"window_start": "<string>"
},
"search_clicks": 123,
"section": "<string>",
"takes": {
"has_more": false,
"items": [
{
"answer_read_id": "<string>",
"claim": "<string>",
"engine_id": "<string>",
"passage": "<string>",
"prompt_text": "<string>",
"prompt_uid": "<string>",
"read_at": "<string>",
"segment": {
"geo": "<string>",
"label": "<string>",
"persona_id": "<string>"
},
"states": {
"icon_states": {
"mentioned": "yes",
"praised": "yes",
"recommended": "yes",
"understood": "yes"
},
"mentioned": true,
"praised": true,
"recommended": true,
"understood": 123
}
}
],
"limit": 2,
"offset": 1,
"pending": 0,
"rejected": 0,
"total": 1,
"unavailable": 0
},
"title": "<string>",
"topic": "<string>",
"topic_source": "member",
"trend": [
{
"break_label": "<string>",
"breaks": [
{
"added": [],
"part": "engines",
"removed": [],
"value": "<string>"
}
],
"citations": 123,
"completed_at": "2023-11-07T05:31:56Z",
"key": {
"answer_pack_version": 123,
"engines": [
"<string>"
],
"markets": {},
"passes": 123,
"score_version": "<string>"
},
"prompts_changed": false,
"run_number": 123
}
],
"unavailable_scans": 0,
"unread_state": "blocked",
"url": "<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 Page
One of the brand’s own pages over the period: its citations and the prompts and answers that cite it, its weekly trend, the stored rubric with each pillar, AI crawler hits by bot and Visits from AI by assistant. The funnel joins search, crawl, citation and visit measurements on the newest pinned weekly scan’s 28-day window, independent of period. with_takes adds what AI took from the page: one take per prompt and engine, read from the evidence kept with each scan up to the pin.
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_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}/pages/{page_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}/pages/{page_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}/pages/{page_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}/pages/{page_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/pages/{page_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{
"ai_visits": 123,
"ai_visits_by_assistant": [
{
"assistant": "<string>",
"sessions": 123
}
],
"answers_link": {
"href": "<string>"
},
"change": {
"at": "2023-11-07T05:31:56Z",
"delta": 123,
"kind": "improved"
},
"changed_at": "2023-11-07T05:31:56Z",
"checks": [
{
"detail": "<string>",
"key": "<string>",
"short": true
}
],
"citation_evidence": "complete",
"citation_share_pct": 123,
"citations": 123,
"cited_in": "tracked",
"cited_on": [
{
"answers": [
{
"answer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"answered_at": "2023-11-07T05:31:56Z",
"cites_page": true,
"engine": "perplexity",
"mentioned": true,
"recommended": true,
"states": {
"icon_states": {
"mentioned": "yes",
"praised": "yes",
"recommended": "yes",
"understood": "yes"
},
"mentioned": true,
"praised": true,
"recommended": true,
"understood": 123
},
"strength": "<string>",
"strength_label": "<string>"
}
],
"intent": "<string>",
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"query_id": "<string>",
"text": "<string>"
}
],
"coverage": {
"end": "2023-12-25",
"start": "2023-12-25"
},
"crawled_at": "2023-11-07T05:31:56Z",
"crawler_bots": [
{
"bot": "<string>",
"category": "training",
"hits": 123,
"operator": "<string>"
}
],
"crawler_hits": 123,
"crawler_hits_days": 123,
"delivered_at": "2023-11-07T05:31:56Z",
"delivery_cited_at": "2023-11-07T05:31:56Z",
"engines_citing": 123,
"engines_read": 123,
"first_cited_at": "2023-11-07T05:31:56Z",
"funnel": {
"ai_visits": 123,
"blocked": 123,
"cited": 123,
"crawled": 123,
"crawler_bots": [
{
"bot": "<string>",
"category": "training",
"hits": 123,
"operator": "<string>"
}
],
"fetched_live": 123,
"not_found": 123,
"search_clicks": 123,
"search_engine_crawls": 123,
"search_impressions": 123,
"sources": [
"<string>"
],
"unverified": 123,
"window": {
"clamped": true,
"end": "2023-12-25",
"history_days": 123,
"start": "2023-12-25"
}
},
"funnel_series": [
{
"ai_visits": 123,
"cited": 123,
"crawled": 123,
"end": "2023-12-25",
"fetched_live": 123,
"search_clicks": 123,
"start": "2023-12-25"
}
],
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_cited_at": "2023-11-07T05:31:56Z",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"page_type": "<string>",
"page_type_decided_by": "model",
"page_type_source": "member",
"path": "<string>",
"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": 123,
"prompts_tracked": 123,
"read": true,
"reason": "<string>",
"rival_urls": [
"<string>"
],
"rubric": {
"pillars": [
{
"detail": "<string>",
"key": "eligible",
"status": "pass"
}
],
"priority": "ineligible",
"score": 123
},
"search": {
"clicks": 123,
"impressions": 123,
"pages_read": 123,
"position": 123,
"state": "ready",
"top_queries": [],
"top_queries_read": true,
"unavailable_reason": "<string>",
"window_end": "<string>",
"window_start": "<string>"
},
"search_clicks": 123,
"section": "<string>",
"takes": {
"has_more": false,
"items": [
{
"answer_read_id": "<string>",
"claim": "<string>",
"engine_id": "<string>",
"passage": "<string>",
"prompt_text": "<string>",
"prompt_uid": "<string>",
"read_at": "<string>",
"segment": {
"geo": "<string>",
"label": "<string>",
"persona_id": "<string>"
},
"states": {
"icon_states": {
"mentioned": "yes",
"praised": "yes",
"recommended": "yes",
"understood": "yes"
},
"mentioned": true,
"praised": true,
"recommended": true,
"understood": 123
}
}
],
"limit": 2,
"offset": 1,
"pending": 0,
"rejected": 0,
"total": 1,
"unavailable": 0
},
"title": "<string>",
"topic": "<string>",
"topic_source": "member",
"trend": [
{
"break_label": "<string>",
"breaks": [
{
"added": [],
"part": "engines",
"removed": [],
"value": "<string>"
}
],
"citations": 123,
"completed_at": "2023-11-07T05:31:56Z",
"key": {
"answer_pack_version": 123,
"engines": [
"<string>"
],
"markets": {},
"passes": 123,
"score_version": "<string>"
},
"prompts_changed": false,
"run_number": 123
}
],
"unavailable_scans": 0,
"unread_state": "blocked",
"url": "<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 1 <= x <= 100x >= 0Response
Successful Response
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
When the crawl last saw its content change.
Each check the latest content pass made of the page against rival pages.
Show child attributes
Show child attributes
complete, partial, unavailable This page's share of the citations the brand's own pages earn. Null where a weekly scan it covers could not keep all its citations.
Null where a weekly scan it covers could not keep all its citations.
tracked, elsewhere, search_only, never Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
When Heralded delivered the page, if it did.
The first weekly scan after the delivery that cited the page.
The engines citing the page. A floor unless citation_evidence is complete.
The first kept citation's time. A floor unless citation_evidence is complete.
Show child attributes
Show child attributes
The funnel on each weekly scan's 28-day window, oldest first, back as far as the plan's history reads. Empty without a weekly scan in that history.
Show child attributes
Show child attributes
The last kept citation's time. A floor unless citation_evidence is complete.
Normalized query and newest included scan.
Show child attributes
Show child attributes
model, model_url, rule member, heralded 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
Null where a weekly scan it covers could not keep all its citations.
Whether Heralded holds the page's text.
Why the latest content pass wants the page improved.
The rival pages those checks compared it with.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Search Console clicks over the bound property's 28-day read; null without a read returning the page.
What AI took from the page, read from the evidence frozen with each scan and pinned by as_of. Present with with_takes. Open an item's answer at answers/{answer_read_id}.
Show child attributes
Show child attributes
The tracked prompt the content pass matched it to.
member, heralded Citations in each weekly scan.
Show child attributes
Show child attributes
blocked, failed, not_tried