API reference
Call analytics
Call volume and latency over a time range, per project or assistant.
- GET
/api/analytics/latencyGet call latency - GET
/api/analytics/search/ai-visitsAI referral visits by assistant and landing page - GET
/api/analytics/search/goalsSearch goal progress - GET
/api/analytics/search/keywordsSearch keyword groups - GET
/api/analytics/search/monthlySearch results month by month - GET
/api/analytics/search/overviewSearch overview through capture - GET
/api/analytics/staffingLead arrivals and assistant handling by channel - GET
/api/analytics/volumeGet call volume
Get call latency
GET/api/analytics/latency
End-to-end response latency (p50 and p95, in milliseconds) and per-stage percentiles over the window, the number of calls measured (calls), and the slowest calls. Percentiles are null when there are no measured calls. The body is not wrapped in data.
Secret API key. How it works
Query parameters
project_idstringOnly this project's calls (an org-wide key covers every project by default).
assistant_idarray of stringOnly these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampStart of the window, ISO 8601 with an offset. Default: 30 days before
to.tostringISO 8601 timestampEnd of the window. Default: now.
Returns
200 OK
Response attributes
callsintegerrequiredLive calls with latency measurements in the window and filters. Test calls are not counted.
e2eAnalyticsPercentilesrequired2 attributes
p50number | nullrequiredp95number | nullrequired
stagesarray of objectrequired3 attributes
p50number | nullrequiredp95number | nullrequiredstagestringrequired
slowestarray of objectrequiredup to 10 items4 attributes
call_idstringrequirede2e_p95numberrequiredassistant_idstringrequiredstarted_atstring | nullrequiredISO 8601 timestamp
- 400
invalid_range:fromortois not a valid timestamp, orfromis not beforeto - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/latency" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"calls": 1,
"e2e": {
"p50": 1,
"p95": 1
},
"stages": [
{
"p50": 1,
"p95": 1,
"stage": "string"
}
],
"slowest": [
{
"call_id": "call_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"e2e_p95": 1,
"assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"started_at": "2026-10-28T09:30:00.000Z"
}
]
}AI referral visits by assistant and landing page
GET/api/analytics/search/ai-visits
AI referral visits (Analytics sessions whose source is an AI assistant host, classification ai-referrers-v1) for the overview's window: period, or start_date and end_date, the same rules as GET /analytics/search/overview. ai_referral_visits.value equals the overview's ai_referral_visits.value, and by_assistant (chatgpt, perplexity, gemini, claude, copilot, other) sums to it; both are null when no day was imported. by_landing_page reads an Analytics import split by landing page and source: pages lists up to limit (1 to 50, default 50) pages on the site's origin and included paths, most visits first; visits_outside_site_scope counts AI visits whose landing page is not set, on another origin or outside the included paths; pages is null without such an import or an imported day. Each page's tracked_questions_citing_page lists up to 10 of the site's tracked AI visibility questions whose valid AI answers sampled in the window cite that page, with how many answers did. These are the questions the site tracks, not the prompts that sent the visitors: assistants report no prompt. A page with visits and no citing question has an empty list. tracked_question_answers counts the valid AI answers read. Missing days stay gaps: compare collected_days with expected_days.
Secret API key. How it works
Query parameters
site_idstringrequiredperiodstringOne of
7d28d90dDefault
"28d"start_datestringend_datestringlimitinteger1 to 50Default
50
Returns
200 OK
Response attributes
dataobjectrequired9 attributes
site_idstringrequiredperiodstringrequiredwindowobjectrequired3 attributes
start_datestringrequiredend_datestringrequiredtimezonestringrequired
intervalobjectrequired2 attributes
fromstringrequiredtostringrequired
classification_versionstringrequiredai_referral_visitsobjectrequired4 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991valuenumber | nullrequiredcompletebooleanrequired
by_assistantobject | nullrequiredSums to ai_referral_visits.value; null when it is null.
One of 2 shapes
Option 1
chatgptnumberrequiredperplexitynumberrequiredgemininumberrequiredclaudenumberrequiredcopilotnumberrequiredothernumberrequired
Option 2
by_landing_pageobjectrequired6 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991completebooleanrequiredpagesarray of object | nullrequiredOne of 2 shapes
Option 1
pathstringrequiredvisitsnumberrequiredby_assistantobjectrequired6 attributes
chatgptnumberrequiredperplexitynumberrequiredgemininumberrequiredclaudenumberrequiredcopilotnumberrequiredothernumberrequired
tracked_questions_citing_pagearray of objectrequiredTracked questions whose AI answers in the window cite this page; not the prompts that sent visitors. Empty when none cites it.
2 attributes
questionstringrequiredciting_answersintegerrequired-9007199254740991 to 9007199254740991
Option 2
page_countintegerrequired-9007199254740991 to 9007199254740991Pages with AI visits before the limit.
visits_outside_site_scopenumber | nullrequired
tracked_question_answersintegerrequired-9007199254740991 to 9007199254740991
- 400 invalid_request: site_id missing, or an invalid window or limit
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Site not found in caller scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/search/ai-visits?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"site_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"period": "string",
"window": {
"start_date": "string",
"end_date": "string",
"timezone": "string"
},
"interval": {
"from": "+14155550123",
"to": "+14155550123"
},
"classification_version": "string",
"ai_referral_visits": {
"collected_days": 1,
"expected_days": 1,
"value": 1,
"complete": true
},
"by_assistant": {
"chatgpt": 1,
"perplexity": 1,
"gemini": 1,
"claude": 1,
"copilot": 1,
"other": 1
},
"by_landing_page": {
"collected_days": 1,
"expected_days": 1,
"complete": true,
"pages": [
{
"path": {},
"visits": {},
"by_assistant": {},
"tracked_questions_citing_page": {}
}
],
"page_count": 1,
"visits_outside_site_scope": 1
},
"tracked_question_answers": 1
}
}Search goal progress
GET/api/analytics/search/goals
The site's active goals (GET /search/sites/{id}/goals) with progress. current gives every metric's value, with or without a goal: clicks and leads from search for the last complete month, and money searches on page one (services queries at position 10 or better over the keyword window). Each goal adds current, percent (of target, whole number, may pass 100) and status: done once current reaches the target, on_track while current is at least the target times the share of time passed from the goal's creation to the end of its due date, else behind. Null current means unknown, and then percent and status are null.
Secret API key. How it works
Query parameters
site_idstringrequired
Returns
200 OK
Response attributes
dataobjectrequired5 attributes
site_idstringrequiredtimezonestringrequiredcurrentobjectrequired3 attributes
clicks_from_search_per_monthobjectrequired3 attributes
valuenumber | nullrequiredstart_datestringrequiredend_datestringrequired
leads_from_search_per_monthobjectrequired3 attributes
valuenumber | nullrequiredstart_datestringrequiredend_datestringrequired
money_searches_on_page_oneobjectrequired3 attributes
valuenumber | nullrequiredstart_datestringrequiredend_datestringrequired
sourcesobjectrequired1 attribute
queriesstring | nullrequired
goalsarray of objectrequired13 attributes
idstringrequiredsite_idstringrequiredmetricstringrequiredOne of
clicks_from_search_per_monthleads_from_search_per_monthmoney_searches_on_page_onetargetintegerrequired-9007199254740991 to 9007199254740991due_datestringrequiredlabelstring | nullrequiredversionintegerrequired-9007199254740991 to 9007199254740991archived_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredcurrentnumber | nullrequiredpercentinteger | nullrequiredstatusstring | nullrequired
- 400 invalid_request: site_id is missing
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Site not found in caller scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/search/goals?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"site_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"timezone": "string",
"current": {
"clicks_from_search_per_month": {
"value": 1,
"start_date": "string",
"end_date": "string"
},
"leads_from_search_per_month": {
"value": 1,
"start_date": "string",
"end_date": "string"
},
"money_searches_on_page_one": {
"value": 1,
"start_date": "string",
"end_date": "string"
}
},
"sources": {
"queries": "string"
},
"goals": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"site_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"metric": "clicks_from_search_per_month",
"target": 1,
"due_date": "string",
"label": "string",
"version": 1,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"current": 1,
"percent": 1,
"status": "on_track"
}
]
}
}Search keyword groups
GET/api/analytics/search/keywords
Query rows Google reported over the 28 days ending yesterday in the business time zone, each query's rows summed across days and pages. Groups, and a query may be in several: defend (average position 3 or better, at least one click), near_page_one (position 8 to 20 with at least 50 impressions), services (a commercial word such as cost, price, near me, book, hire, repair), places (a ZIP or postcode, or a place from the site's markets), dated (a year, a month name, deal or offer). counts are full group sizes; groups list up to 100 rows each, most impressions first. counts are null when no query import qualifies or no day was imported.
Secret API key. How it works
Query parameters
site_idstringrequired
Returns
200 OK
Response attributes
dataobjectrequired8 attributes
site_idstringrequiredwindowobjectrequired3 attributes
start_datestringrequiredend_datestringrequiredtimezonestringrequired
sourcestring | nullrequiredcoverageobjectrequired3 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991completebooleanrequired
query_scopestringrequiredthresholdsobjectrequired4 attributes
defend_max_positionnumberrequirednear_page_one_min_positionnumberrequirednear_page_one_max_positionnumberrequirednear_page_one_min_impressionsnumberrequired
countsobjectrequired5 attributes
defendinteger | nullrequirednear_page_oneinteger | nullrequiredservicesinteger | nullrequiredplacesinteger | nullrequireddatedinteger | nullrequired
groupsobjectrequired5 attributes
defendarray of objectrequired5 attributes
querystringrequiredpositionnumber | nullrequiredImpression-weighted average position over the window.
clicksnumberrequiredimpressionsnumberrequiredtop_pagestring | nullrequiredThe page with most clicks, then impressions: a path on the site, else a URL.
near_page_onearray of objectrequired5 attributes
querystringrequiredpositionnumber | nullrequiredImpression-weighted average position over the window.
clicksnumberrequiredimpressionsnumberrequiredtop_pagestring | nullrequiredThe page with most clicks, then impressions: a path on the site, else a URL.
servicesarray of objectrequired5 attributes
querystringrequiredpositionnumber | nullrequiredImpression-weighted average position over the window.
clicksnumberrequiredimpressionsnumberrequiredtop_pagestring | nullrequiredThe page with most clicks, then impressions: a path on the site, else a URL.
placesarray of objectrequired5 attributes
querystringrequiredpositionnumber | nullrequiredImpression-weighted average position over the window.
clicksnumberrequiredimpressionsnumberrequiredtop_pagestring | nullrequiredThe page with most clicks, then impressions: a path on the site, else a URL.
datedarray of objectrequired5 attributes
querystringrequiredpositionnumber | nullrequiredImpression-weighted average position over the window.
clicksnumberrequiredimpressionsnumberrequiredtop_pagestring | nullrequiredThe page with most clicks, then impressions: a path on the site, else a URL.
- 400 invalid_request: site_id is missing
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Site not found in caller scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/search/keywords?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"site_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"window": {
"start_date": "string",
"end_date": "string",
"timezone": "string"
},
"source": "string",
"coverage": {
"collected_days": 1,
"expected_days": 1,
"complete": true
},
"query_scope": "reported_by_google",
"thresholds": {
"defend_max_position": 1,
"near_page_one_min_position": 1,
"near_page_one_max_position": 1,
"near_page_one_min_impressions": 1
},
"counts": {
"defend": 1,
"near_page_one": 1,
"services": 1,
"places": 1,
"dated": 1
},
"groups": {
"defend": [
{
"query": "string",
"position": 1,
"clicks": 1,
"impressions": 1,
"top_page": "string"
}
],
"near_page_one": [
{
"query": "string",
"position": 1,
"clicks": 1,
"impressions": 1,
"top_page": "string"
}
],
"services": [
{
"query": "string",
"position": 1,
"clicks": 1,
"impressions": 1,
"top_page": "string"
}
],
"places": [
{
"query": "string",
"position": 1,
"clicks": 1,
"impressions": 1,
"top_page": "string"
}
],
"dated": [
{
"query": "string",
"position": 1,
"clicks": 1,
"impressions": 1,
"top_page": "string"
}
]
}
}
}Search results month by month
GET/api/analytics/search/monthly
The last 6 complete calendar months in the business time zone, newest first, each with the same month a year earlier (year_earlier) and the change against it. Clicks, impressions, ctr and position come from the one unfiltered property-totals Search Console import; queries_top_3 and queries_top_10 from the query rows Google reports (query_scope reported_by_google: anonymized searches are left out). A figure is null unless every day of its month was imported (coverage gives collected and expected days): a gap is never a zero. Months use the provider's reporting dates. countries lists up to 10 countries by clicks in the latest month against the year-earlier month, from an import split by country but not by query; country is the code Google reports (ISO 3166-1 alpha-3, lowercase). leads_recorded_from is the day the business joined Brightshoal.
Secret API key. How it works
Query parameters
site_idstringrequired
Returns
200 OK
Response attributes
dataobjectrequired7 attributes
site_idstringrequiredtimezonestringrequiredquery_scopestringrequiredleads_recorded_fromstringrequiredsourcesobjectrequired3 attributes
searchstring | nullrequiredqueriesstring | nullrequiredcountriesstring | nullrequired
monthsarray of objectrequired13 attributes
monthstringrequiredYYYY-MM
start_datestringrequiredend_datestringrequiredclicksnumber | nullrequiredNull unless every day of the month was imported.
impressionsnumber | nullrequiredNull unless every day of the month was imported.
ctrnumber | nullrequiredClicks divided by impressions, 0 to 1.
positionnumber | nullrequiredImpression-weighted average position from the property totals.
queries_top_3number | nullrequiredQueries Google reported with a month average position of 3 or better.
queries_top_10number | nullrequiredThe same, 10 or better.
leads_from_searchnumber | nullrequiredLeads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.
coverageobjectrequired2 attributes
searchobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
queriesobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
year_earlierobjectrequired11 attributes
monthstringrequiredYYYY-MM
start_datestringrequiredend_datestringrequiredclicksnumber | nullrequiredNull unless every day of the month was imported.
impressionsnumber | nullrequiredNull unless every day of the month was imported.
ctrnumber | nullrequiredClicks divided by impressions, 0 to 1.
positionnumber | nullrequiredImpression-weighted average position from the property totals.
queries_top_3number | nullrequiredQueries Google reported with a month average position of 3 or better.
queries_top_10number | nullrequiredThe same, 10 or better.
leads_from_searchnumber | nullrequiredLeads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.
coverageobjectrequired2 attributes
searchobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
queriesobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
changeobjectrequired7 attributes
clicks_pctnumber | nullrequiredWhole percent; null when either month is null or the year-earlier one is zero.
impressions_pctnumber | nullrequiredqueries_top_3_pctnumber | nullrequiredqueries_top_10_pctnumber | nullrequiredctr_pointsnumber | nullrequiredPercentage points, one decimal.
position_gainnumber | nullrequiredYear-earlier position minus this one, one decimal: positive means higher up.
leads_from_search_deltanumber | nullrequired
countriesobject | nullrequiredNull when no import is split by country.
One of 2 shapes
Option 1
monthstringrequiredyear_earlier_monthstringrequiredcoverageobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
year_earlier_coverageobjectrequired2 attributes
collected_daysintegerrequired-9007199254740991 to 9007199254740991expected_daysintegerrequired-9007199254740991 to 9007199254740991
itemsarray of object | nullrequiredNull unless every day of the month was imported.
One of 2 shapes
Option 1
countrystringrequiredclicksnumberrequiredyear_earlier_clicksnumber | nullrequiredchange_pctnumber | nullrequired
Option 2
Option 2
- 400 invalid_request: site_id is missing
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Site not found in caller scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/search/monthly?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"site_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"timezone": "string",
"query_scope": "reported_by_google",
"leads_recorded_from": "string",
"sources": {
"search": "string",
"queries": "string",
"countries": "string"
},
"months": [
{
"month": "string",
"start_date": "string",
"end_date": "string",
"clicks": 1,
"impressions": 1,
"ctr": 1,
"position": 1,
"queries_top_3": 1,
"queries_top_10": 1,
"leads_from_search": 1,
"coverage": {
"search": {
"collected_days": {},
"expected_days": {}
},
"queries": {
"collected_days": {},
"expected_days": {}
}
},
"year_earlier": {
"month": "string",
"start_date": "string",
"end_date": "string",
"clicks": 1,
"impressions": 1,
"ctr": 1,
"position": 1,
"queries_top_3": 1,
"queries_top_10": 1,
"leads_from_search": 1,
"coverage": {
"search": {},
"queries": {}
}
},
"change": {
"clicks_pct": 1,
"impressions_pct": 1,
"queries_top_3_pct": 1,
"queries_top_10_pct": 1,
"ctr_points": 1,
"position_gain": 1,
"leads_from_search_delta": 1
}
}
],
"countries": {
"month": "string",
"year_earlier_month": "string",
"coverage": {
"collected_days": 1,
"expected_days": 1
},
"year_earlier_coverage": {
"collected_days": 1,
"expected_days": 1
},
"items": [
{}
]
}
}
}Search overview through capture
GET/api/analytics/search/overview
Read-only owner-facade projection. Includes official search coverage, AI mention numerator/denominator and planned/failed/missing samples, ai_mention_rate.by_surface with those counts per surface present in the period points except serp (sorted by surface), classified referral sessions, real conversations, captured leads and verified interventions. Surfaces are separate populations and must not be added together; pooled AI fields remain for compatibility. Missing series remain null/incomplete; no sales attribution is inferred. Defaults to period whole UTC days ending yesterday inclusive. end_date overrides the inclusive end; start_date optionally overrides the start (requires end_date, maximum 90 days). window gives inclusive dates; interval gives equivalent half-open UTC timestamps. previous contains the immediately preceding equal-length window and all the same figures and coverage. coverage gives collected_days and expected_days for each measure. Search and referral days count complete/incomplete imported reports; AI collected days count distinct days with valid answers; AI expected days count scheduled UTC panel dates and materialised manual run dates, including missed weekly slots, rather than calendar days; owned event measures cover every queried day, including observed zero days. captured_leads_by_source splits captured_leads by where the visit came from, every key present and summing to captured_leads: google (organic), google_ads (a Google click id, or a paid utm_medium such as cpc from Google), bing (organic), ai_assistants, direct (no referrer and no UTM), other (any other referrer or ad platform) and not_recorded (no touch kept: no analytics consent, an older widget, or a form submission). It reads the visit's touch, else the visitor's first touch. captured_leads_by_page lists up to 50 pages, most leads first: {path, total, from_search}, where path is the touch's landing page, else the page the lead was captured on, as a path on the site's origin and scope (other origins, queries and fragments are dropped), and from_search counts google, bing and ai_assistants leads. analytics_key_events is null unless exactly one unfiltered Analytics import for the whole site reads landingPage by sessionDefaultChannelGroup with keyEvents (or conversions, its earlier name); otherwise {collected_days, expected_days, total, organic_search, by_page, complete}: key events summed over the imported rows, organic_search those GA4 groups as Organic Search, by_page up to 50 landing pages with key events, most first ({path, total, organic_search}; rows without a landing page count in the totals only). Figures are null until a day is collected; complete is false when a day is missing, thresholded, sampled or has an (other) row. Measurement only: these are not leads Brightshoal captured.
Secret API key. How it works
Query parameters
site_idstringrequiredperiodstringOne of
7d28d90dDefault
"28d"start_datestringend_datestring
Returns
200 Scoped overview with window, interval, per-measure coverage and previous figures in data envelope
Response attributes
dataobjectrequired2 attributes
ai_mention_rateobjectrequired1 attribute
by_surfacearray of objectrequiredOne entry per surface present in the period points except serp, sorted by surface. Surfaces are separate populations and must not be added together.
7 attributes
surfacestringrequiredOne of
consumermodel_apinumeratorintegerrequired-9007199254740991 to 9007199254740991denominatorintegerrequired-9007199254740991 to 9007199254740991valuenumber | nullrequiredNumerator divided by denominator, null when denominator is zero.
plannedintegerrequired-9007199254740991 to 9007199254740991failedintegerrequired-9007199254740991 to 9007199254740991missingintegerrequired-9007199254740991 to 9007199254740991
previousobjectrequired1 attribute
ai_mention_rateobjectrequired1 attribute
by_surfacearray of objectrequiredOne entry per surface present in the period points except serp, sorted by surface. Surfaces are separate populations and must not be added together.
7 attributes
surfacestringrequiredOne of
consumermodel_apinumeratorintegerrequired-9007199254740991 to 9007199254740991denominatorintegerrequired-9007199254740991 to 9007199254740991valuenumber | nullrequiredNumerator divided by denominator, null when denominator is zero.
plannedintegerrequired-9007199254740991 to 9007199254740991failedintegerrequired-9007199254740991 to 9007199254740991missingintegerrequired-9007199254740991 to 9007199254740991
- 400 invalid_request
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Site not found in caller scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/search/overview?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"ai_mention_rate": {
"by_surface": [
{
"surface": "consumer",
"numerator": 1,
"denominator": 1,
"value": 1,
"planned": 1,
"failed": 1,
"missing": 1
}
]
},
"previous": {
"ai_mention_rate": {
"by_surface": [
{
"surface": "consumer",
"numerator": {},
"denominator": {},
"value": {},
"planned": {},
"failed": {},
"missing": {}
}
]
}
}
}
}Lead arrivals and assistant handling by channel
GET/api/analytics/staffing
Viewer role. One project, resolved from project_id or the caller's scope. Half-open period [from,to), default 30 days, at most 400 days. Uses the project's business timezone, or UTC if unset; tz overrides it. Arrival cells are sparse (omitted cells are zero), weekday 0 is Sunday, hour 0 to 23. Real unmerged leads only. Handling counts chats by creation time: handled means ended with an assistant reply and no handoff or takeover; handed means requested a human or was taken over, including unanswered requests. Calls: handled means connected and completed without transfer; handed means a transfer was attempted or completed. Open chats without handoff, unanswered calls and failures are in neither count. No handling counts are invented for form-only channels.
Secret API key. How it works
Query parameters
project_idstringOnly this project's calls (an org-wide key covers every project by default).
assistant_idarray of stringOnly these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampStart of the window, ISO 8601 with an offset. Default: 30 days before
to.tostringISO 8601 timestampEnd of the window. Default: now.
tzstringchannelstringOptional lead channel, such as web_chat, whatsapp, phone_call or form.
Returns
200 Staffing aggregates
Response attributes
dataobjectrequired6 attributes
fromstringrequiredISO 8601 timestamptostringrequiredISO 8601 timestamptimezonestringrequiredlead_arrivalsarray of objectrequired3 attributes
weekdayintegerrequired0 to 6hourintegerrequired0 to 23countintegerrequired
lead_arrivals_by_channelarray of objectrequired4 attributes
channelstringrequiredweekdayintegerrequiredhourintegerrequiredcountintegerrequired
handling_by_channelarray of objectrequired3 attributes
channelstringrequiredhandled_by_assistantintegerrequiredhanded_to_personintegerrequired
- 400 Invalid range, timezone, channel or project selection
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Project outside scope
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/staffing" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"from": "2026-10-28T09:30:00.000Z",
"to": "2026-10-28T09:30:00.000Z",
"timezone": "string",
"lead_arrivals": [
{
"weekday": 1,
"hour": 1,
"count": 1
}
],
"lead_arrivals_by_channel": [
{
"channel": "string",
"weekday": 1,
"hour": 1,
"count": 1
}
],
"handling_by_channel": [
{
"channel": "string",
"handled_by_assistant": 1,
"handed_to_person": 1
}
]
}
}Get call volume
GET/api/analytics/volume
Call counts and minutes over the window: totals, by status, by call type, by why calls ended, and per day. The window defaults to the last 30 days. The body is not wrapped in data.
Secret API key. How it works
Query parameters
project_idstringOnly this project's calls (an org-wide key covers every project by default).
assistant_idarray of stringOnly these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.
fromstringISO 8601 timestampStart of the window, ISO 8601 with an offset. Default: 30 days before
to.tostringISO 8601 timestampEnd of the window. Default: now.
Returns
200 OK
Response attributes
total_callsintegerrequiredtotal_minutesnumberrequiredcompletedintegerrequiredfailedintegerrequiredby_statusarray of objectrequired2 attributes
countintegerrequiredstatusstringrequired
by_call_typearray of objectrequired2 attributes
countintegerrequiredcall_typestringrequired
by_canonical_ended_reasonarray of objectrequired2 attributes
countintegerrequiredended_reasonstringrequired
dailyarray of objectrequired3 attributes
datestringrequireddatecallsintegerrequiredminutesnumberrequired
- 400
invalid_range:fromortois not a valid timestamp, orfromis not beforeto - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/analytics/volume" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"total_calls": 1,
"total_minutes": 1,
"completed": 1,
"failed": 1,
"by_status": [
{
"count": 1,
"status": "string"
}
],
"by_call_type": [
{
"count": 1,
"call_type": "string"
}
],
"by_canonical_ended_reason": [
{
"count": 1,
"ended_reason": "string"
}
],
"daily": [
{
"date": "2026-10-28",
"calls": 1,
"minutes": 1
}
]
}