Get Keyword
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_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_searches_it": [
"<string>"
],
"best_rank": 123,
"clicks_showing_you": 123,
"figures": {
"heralded_score": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
},
"mentioned": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
},
"recommended": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
}
},
"google_label": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"period": {
"excluded_reports": 123,
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"preset": "1w",
"reports": 123
},
"prompts": [
{
"engines": [
"<string>"
],
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>"
}
],
"results": [
{
"click_share": 123,
"domain": "<string>",
"names_you": true,
"owner": "own",
"position": 123,
"read_state": "read",
"recommends_you": true,
"title": "<string>",
"url": "<string>"
}
],
"score": {
"answer_read_id": "<string>",
"answers": 123,
"band": "<string>",
"key": "<string>",
"label": "<string>",
"state": "measured",
"tooltip": "<string>",
"value": 123
},
"searches_mo": 123,
"segment": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"status": "active",
"tasks": [
{
"completed_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"delivered_at": "2023-11-07T05:31:56Z",
"detail": "<string>",
"evidence": {
"answers_link": {
"href": "<string>"
},
"prompts": [
{
"answer_count": 123,
"answers_link": {
"href": "<string>"
},
"named_count": 123,
"prompt_uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>"
}
]
},
"group": "new",
"holder": "you",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"member": "writer",
"not_seen_since_run": 123,
"note": {
"how_well_know": "<string>",
"short_form": "<string>",
"what_i_need_from_you": "<string>",
"what_ill_do": "<string>",
"whats_happening": "<string>",
"why_it_matters": "<string>"
},
"outcome": "verified_up",
"paid_off_at": "2023-11-07T05:31:56Z",
"placed_position": 123,
"preview": "<string>",
"stage": "observe",
"started_at": "2023-11-07T05:31:56Z",
"title": "<string>"
}
],
"text": "<string>",
"top10_naming_you": 123,
"topic": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"trend": {
"delta": 123,
"label": "<string>",
"state": "up"
}
}{
"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"
}Site
Get Keyword
One keyword: its figures over the period with their range, the top 10 of the latest check, the prompts that make AI search it and the tasks about your pages.
GET
/
v1
/
brands
/
{brand_id}
/
keywords
/
{keyword_id}
Get Keyword
curl --request GET \
--url https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_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}/keywords/{keyword_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heralded.ai/v1/brands/{brand_id}/keywords/{keyword_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_searches_it": [
"<string>"
],
"best_rank": 123,
"clicks_showing_you": 123,
"figures": {
"heralded_score": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
},
"mentioned": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
},
"recommended": {
"answers": 123,
"change": {
"baseline": {
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"reports": 123
},
"cells_unpaired": 123,
"delta": 123,
"direction": "up",
"high": 123,
"low": 123,
"real": true
},
"denominator": 123,
"high": 123,
"low": 123,
"numerator": 123,
"state": "measured",
"trend": [
{
"answers": 123,
"at": "2023-11-07T05:31:56Z",
"break_label": "<string>",
"high": 123,
"low": 123,
"state": "measured",
"value": 123
}
],
"value": 123
}
},
"google_label": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"meta": {
"data_as_of": {
"completed_at": "2023-11-07T05:31:56Z",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"query": {}
},
"period": {
"excluded_reports": 123,
"first_answer_at": "2023-11-07T05:31:56Z",
"last_answer_at": "2023-11-07T05:31:56Z",
"preset": "1w",
"reports": 123
},
"prompts": [
{
"engines": [
"<string>"
],
"prompt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>"
}
],
"results": [
{
"click_share": 123,
"domain": "<string>",
"names_you": true,
"owner": "own",
"position": 123,
"read_state": "read",
"recommends_you": true,
"title": "<string>",
"url": "<string>"
}
],
"score": {
"answer_read_id": "<string>",
"answers": 123,
"band": "<string>",
"key": "<string>",
"label": "<string>",
"state": "measured",
"tooltip": "<string>",
"value": 123
},
"searches_mo": 123,
"segment": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"status": "active",
"tasks": [
{
"completed_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"delivered_at": "2023-11-07T05:31:56Z",
"detail": "<string>",
"evidence": {
"answers_link": {
"href": "<string>"
},
"prompts": [
{
"answer_count": 123,
"answers_link": {
"href": "<string>"
},
"named_count": 123,
"prompt_uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>"
}
]
},
"group": "new",
"holder": "you",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "<string>",
"member": "writer",
"not_seen_since_run": 123,
"note": {
"how_well_know": "<string>",
"short_form": "<string>",
"what_i_need_from_you": "<string>",
"what_ill_do": "<string>",
"whats_happening": "<string>",
"why_it_matters": "<string>"
},
"outcome": "verified_up",
"paid_off_at": "2023-11-07T05:31:56Z",
"placed_position": 123,
"preview": "<string>",
"stage": "observe",
"started_at": "2023-11-07T05:31:56Z",
"title": "<string>"
}
],
"text": "<string>",
"top10_naming_you": 123,
"topic": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
},
"trend": {
"delta": 123,
"label": "<string>",
"state": "up"
}
}{
"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
Include only scans up to this completed scan id.
Available options:
1w, 4w, 12w, all Response
Successful Response
The AI engines whose background searches for the topic's prompts contain the keyword.
Your best position in the latest check's top 10; null when none of your pages is there and before a check read Google.
The share of clicks, in points, that land on a page showing you over the period: figures.mentioned. Null where the keyword is not measured.
The keyword's Search side over the period, with its range and trend: the unread results can only add to it. Null before a report froze a check.
Show child attributes
Show child attributes
The keyword's stable id.
Normalized query and newest included scan.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The topic's prompts in the segment, those the engines searched this keyword for first.
Show child attributes
Show child attributes
The ten results of the latest check Google answered, in order.
Show child attributes
Show child attributes
A score or figure from the figures read, with the band it is coloured by (#4259).
key is the engine or the figure measured. band is the Heralded Score's
band for the value, so a mark and a score read on one scale, and
"Not measured" where no value is served, which includes a group under the
minimum of answers. On a score, answers counts every answer the period
read under the filters, including those a figure's own denominator leaves
out.
Show child attributes
Show child attributes
Monthly Google searches in the segment's market now; null where the vendor had none.
Show child attributes
Show child attributes
Available options:
active, paused, archived Open tasks about your pages in the results.
Show child attributes
Show child attributes
How many of the latest check's ten results name you, yours included; null before a check read Google.
Show child attributes
Show child attributes
A score's change, as the Trend column and the pane state it.
Show child attributes
Show child attributes