curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/audit \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/audit"
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}/audit', 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}/audit",
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}/audit"
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}/audit")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/audit")
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{
"checks_failing": 123,
"checks_unmeasured": 123,
"citations_scan": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"crawled_at": "2023-11-07T05:31:56Z",
"crawler_hits_available": true,
"crawler_hits_days": 123,
"groups": [
{
"checks": [
{
"action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"failing_pages": [
"<string>"
],
"failing_pages_offset": 0,
"failing_pages_total": 123,
"id": "<string>",
"label": "<string>",
"measured": "<string>",
"met": true,
"pages_in_scope": 123,
"target": "<string>"
}
],
"failing": 123,
"name": "<string>",
"passing": 123,
"unmeasured": 123
}
],
"limit": 123,
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"next_crawl_at": "2023-11-07T05:31:56Z",
"next_cursor": "<string>",
"offset": 123,
"page_types": [
"<string>"
],
"pages": [
{
"citations": 123,
"crawler_hits": 123,
"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"
}
},
"gates": [
{
"key": "<string>",
"status": "pass"
}
],
"page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page_type": "<string>",
"path": "<string>",
"read_at": "2023-11-07T05:31:56Z",
"status": "readable",
"status_word": "<string>",
"title": "<string>",
"url": "<string>"
}
],
"readiness": {
"pages_blocked": 123,
"pages_checked": 123,
"pages_readable": 123,
"pages_unmeasured": 123
},
"sentence": "<string>",
"state": "ready",
"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 Audit
The latest crawl’s readiness, site checks by group and pages.
Audit has no period. Page citations count the last weekly scan, named in citations_scan. AI crawls use the same frozen 28-day window as page reads, ending two days before that weekly scan started.
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/audit \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/audit"
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}/audit', 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}/audit",
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}/audit"
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}/audit")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/audit")
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{
"checks_failing": 123,
"checks_unmeasured": 123,
"citations_scan": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"crawled_at": "2023-11-07T05:31:56Z",
"crawler_hits_available": true,
"crawler_hits_days": 123,
"groups": [
{
"checks": [
{
"action_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"failing_pages": [
"<string>"
],
"failing_pages_offset": 0,
"failing_pages_total": 123,
"id": "<string>",
"label": "<string>",
"measured": "<string>",
"met": true,
"pages_in_scope": 123,
"target": "<string>"
}
],
"failing": 123,
"name": "<string>",
"passing": 123,
"unmeasured": 123
}
],
"limit": 123,
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"next_crawl_at": "2023-11-07T05:31:56Z",
"next_cursor": "<string>",
"offset": 123,
"page_types": [
"<string>"
],
"pages": [
{
"citations": 123,
"crawler_hits": 123,
"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"
}
},
"gates": [
{
"key": "<string>",
"status": "pass"
}
],
"page_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page_type": "<string>",
"path": "<string>",
"read_at": "2023-11-07T05:31:56Z",
"status": "readable",
"status_word": "<string>",
"title": "<string>",
"url": "<string>"
}
],
"readiness": {
"pages_blocked": 123,
"pages_checked": 123,
"pages_readable": 123,
"pages_unmeasured": 123
},
"sentence": "<string>",
"state": "ready",
"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
Include only scans up to this completed scan id.
1 <= x <= 100x >= 04096readable, blocked_robots, noindex, does_not_load, needs_javascript, not_read cited, not_cited product, solution, pricing, blog_post, customer_story, press, documentation, resource, comparison, legal, other 200citations, page, status, crawls, read asc, desc 2001 <= x <= 100x >= 0Response
Successful Response
The latest crawl's site checks and pages. Audit has no period.
The last weekly scan, whose answers the pages' citations count.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Normalized query and newest included scan.
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
The pages the readiness checks cover: every audited page and the homepage.
Show child attributes
Show child attributes
ready, awaiting_first_crawl