BrightshoalDocsOpen console
MenuCall analytics

API reference

Call analytics

Call volume and latency over a time range, per project or assistant.

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_idstring

    Only this project's calls (an org-wide key covers every project by default).

  • assistant_idarray of string

    Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Start of the window, ISO 8601 with an offset. Default: 30 days before to.

  • tostringISO 8601 timestamp

    End of the window. Default: now.

Returns

200 OK

Response attributes
  • callsintegerrequired

    Live calls with latency measurements in the window and filters. Test calls are not counted.

  • e2eAnalyticsPercentilesrequired

    2 attributes
    • p50number | nullrequired

    • p95number | nullrequired

  • stagesarray of objectrequired

    3 attributes
    • p50number | nullrequired

    • p95number | nullrequired

    • stagestringrequired

  • slowestarray of objectrequiredup to 10 items

    4 attributes
    • call_idstringrequired

    • e2e_p95numberrequired

    • assistant_idstringrequired

    • started_atstring | nullrequiredISO 8601 timestamp

  • 400 invalid_range: from or to is not a valid timestamp, or from is not before to
  • 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). Wait Retry-After seconds. 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).
GET /api/analytics/latency
curl "https://api.brightshoal.com/api/analytics/latency" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstringrequired

  • periodstring

    One of 7d 28d 90d

    Default "28d"

  • start_datestring

  • end_datestring

  • limitinteger1 to 50

    Default 50

Returns

200 OK

Response attributes
  • dataobjectrequired

    9 attributes
    • site_idstringrequired

    • periodstringrequired

    • windowobjectrequired

      3 attributes
      • start_datestringrequired

      • end_datestringrequired

      • timezonestringrequired

    • intervalobjectrequired

      2 attributes
      • fromstringrequired

      • tostringrequired

    • classification_versionstringrequired

    • ai_referral_visitsobjectrequired

      4 attributes
      • collected_daysintegerrequired-9007199254740991 to 9007199254740991

      • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • valuenumber | nullrequired

      • completebooleanrequired

    • by_assistantobject | nullrequired

      Sums to ai_referral_visits.value; null when it is null.

      One of 2 shapes

      Option 1

      • chatgptnumberrequired

      • perplexitynumberrequired

      • gemininumberrequired

      • claudenumberrequired

      • copilotnumberrequired

      • othernumberrequired

      Option 2

    • by_landing_pageobjectrequired

      6 attributes
      • collected_daysintegerrequired-9007199254740991 to 9007199254740991

      • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • completebooleanrequired

      • pagesarray of object | nullrequired

        One of 2 shapes

        Option 1

        • pathstringrequired

        • visitsnumberrequired

        • by_assistantobjectrequired

          6 attributes
          • chatgptnumberrequired

          • perplexitynumberrequired

          • gemininumberrequired

          • claudenumberrequired

          • copilotnumberrequired

          • othernumberrequired

        • tracked_questions_citing_pagearray of objectrequired

          Tracked questions whose AI answers in the window cite this page; not the prompts that sent visitors. Empty when none cites it.

          2 attributes
          • questionstringrequired

          • citing_answersintegerrequired-9007199254740991 to 9007199254740991

        Option 2

      • page_countintegerrequired-9007199254740991 to 9007199254740991

        Pages 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). Wait Retry-After seconds. 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).
GET /api/analytics/search/ai-visits
curl "https://api.brightshoal.com/api/analytics/search/ai-visits?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
  • dataobjectrequired

    5 attributes
    • site_idstringrequired

    • timezonestringrequired

    • currentobjectrequired

      3 attributes
      • clicks_from_search_per_monthobjectrequired

        3 attributes
        • valuenumber | nullrequired

        • start_datestringrequired

        • end_datestringrequired

      • leads_from_search_per_monthobjectrequired

        3 attributes
        • valuenumber | nullrequired

        • start_datestringrequired

        • end_datestringrequired

      • money_searches_on_page_oneobjectrequired

        3 attributes
        • valuenumber | nullrequired

        • start_datestringrequired

        • end_datestringrequired

    • sourcesobjectrequired

      1 attribute
      • queriesstring | nullrequired

    • goalsarray of objectrequired

      13 attributes
      • idstringrequired

      • site_idstringrequired

      • metricstringrequired

        One of clicks_from_search_per_month leads_from_search_per_month money_searches_on_page_one

      • targetintegerrequired-9007199254740991 to 9007199254740991

      • due_datestringrequired

      • labelstring | nullrequired

      • versionintegerrequired-9007199254740991 to 9007199254740991

      • archived_atstring | nullrequired

      • created_atstringrequired

      • updated_atstringrequired

      • currentnumber | nullrequired

      • percentinteger | nullrequired

      • statusstring | 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). Wait Retry-After seconds. 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).
GET /api/analytics/search/goals
curl "https://api.brightshoal.com/api/analytics/search/goals?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
  • dataobjectrequired

    8 attributes
    • site_idstringrequired

    • windowobjectrequired

      3 attributes
      • start_datestringrequired

      • end_datestringrequired

      • timezonestringrequired

    • sourcestring | nullrequired

    • coverageobjectrequired

      3 attributes
      • collected_daysintegerrequired-9007199254740991 to 9007199254740991

      • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • completebooleanrequired

    • query_scopestringrequired

    • thresholdsobjectrequired

      4 attributes
      • defend_max_positionnumberrequired

      • near_page_one_min_positionnumberrequired

      • near_page_one_max_positionnumberrequired

      • near_page_one_min_impressionsnumberrequired

    • countsobjectrequired

      5 attributes
      • defendinteger | nullrequired

      • near_page_oneinteger | nullrequired

      • servicesinteger | nullrequired

      • placesinteger | nullrequired

      • datedinteger | nullrequired

    • groupsobjectrequired

      5 attributes
      • defendarray of objectrequired

        5 attributes
        • querystringrequired

        • positionnumber | nullrequired

          Impression-weighted average position over the window.

        • clicksnumberrequired

        • impressionsnumberrequired

        • top_pagestring | nullrequired

          The page with most clicks, then impressions: a path on the site, else a URL.

      • near_page_onearray of objectrequired

        5 attributes
        • querystringrequired

        • positionnumber | nullrequired

          Impression-weighted average position over the window.

        • clicksnumberrequired

        • impressionsnumberrequired

        • top_pagestring | nullrequired

          The page with most clicks, then impressions: a path on the site, else a URL.

      • servicesarray of objectrequired

        5 attributes
        • querystringrequired

        • positionnumber | nullrequired

          Impression-weighted average position over the window.

        • clicksnumberrequired

        • impressionsnumberrequired

        • top_pagestring | nullrequired

          The page with most clicks, then impressions: a path on the site, else a URL.

      • placesarray of objectrequired

        5 attributes
        • querystringrequired

        • positionnumber | nullrequired

          Impression-weighted average position over the window.

        • clicksnumberrequired

        • impressionsnumberrequired

        • top_pagestring | nullrequired

          The page with most clicks, then impressions: a path on the site, else a URL.

      • datedarray of objectrequired

        5 attributes
        • querystringrequired

        • positionnumber | nullrequired

          Impression-weighted average position over the window.

        • clicksnumberrequired

        • impressionsnumberrequired

        • top_pagestring | nullrequired

          The 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). Wait Retry-After seconds. 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).
GET /api/analytics/search/keywords
curl "https://api.brightshoal.com/api/analytics/search/keywords?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
  • dataobjectrequired

    7 attributes
    • site_idstringrequired

    • timezonestringrequired

    • query_scopestringrequired

    • leads_recorded_fromstringrequired

    • sourcesobjectrequired

      3 attributes
      • searchstring | nullrequired

      • queriesstring | nullrequired

      • countriesstring | nullrequired

    • monthsarray of objectrequired

      13 attributes
      • monthstringrequired

        YYYY-MM

      • start_datestringrequired

      • end_datestringrequired

      • clicksnumber | nullrequired

        Null unless every day of the month was imported.

      • impressionsnumber | nullrequired

        Null unless every day of the month was imported.

      • ctrnumber | nullrequired

        Clicks divided by impressions, 0 to 1.

      • positionnumber | nullrequired

        Impression-weighted average position from the property totals.

      • queries_top_3number | nullrequired

        Queries Google reported with a month average position of 3 or better.

      • queries_top_10number | nullrequired

        The same, 10 or better.

      • leads_from_searchnumber | nullrequired

        Leads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.

      • coverageobjectrequired

        2 attributes
        • searchobjectrequired

          2 attributes
          • collected_daysintegerrequired-9007199254740991 to 9007199254740991

          • expected_daysintegerrequired-9007199254740991 to 9007199254740991

        • queriesobjectrequired

          2 attributes
          • collected_daysintegerrequired-9007199254740991 to 9007199254740991

          • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • year_earlierobjectrequired

        11 attributes
        • monthstringrequired

          YYYY-MM

        • start_datestringrequired

        • end_datestringrequired

        • clicksnumber | nullrequired

          Null unless every day of the month was imported.

        • impressionsnumber | nullrequired

          Null unless every day of the month was imported.

        • ctrnumber | nullrequired

          Clicks divided by impressions, 0 to 1.

        • positionnumber | nullrequired

          Impression-weighted average position from the property totals.

        • queries_top_3number | nullrequired

          Queries Google reported with a month average position of 3 or better.

        • queries_top_10number | nullrequired

          The same, 10 or better.

        • leads_from_searchnumber | nullrequired

          Leads from Google, Bing and AI assistants captured that month; null for a month that ended before leads_recorded_from.

        • coverageobjectrequired

          2 attributes
          • searchobjectrequired

            2 attributes
            • collected_daysintegerrequired-9007199254740991 to 9007199254740991

            • expected_daysintegerrequired-9007199254740991 to 9007199254740991

          • queriesobjectrequired

            2 attributes
            • collected_daysintegerrequired-9007199254740991 to 9007199254740991

            • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • changeobjectrequired

        7 attributes
        • clicks_pctnumber | nullrequired

          Whole percent; null when either month is null or the year-earlier one is zero.

        • impressions_pctnumber | nullrequired

        • queries_top_3_pctnumber | nullrequired

        • queries_top_10_pctnumber | nullrequired

        • ctr_pointsnumber | nullrequired

          Percentage points, one decimal.

        • position_gainnumber | nullrequired

          Year-earlier position minus this one, one decimal: positive means higher up.

        • leads_from_search_deltanumber | nullrequired

    • countriesobject | nullrequired

      Null when no import is split by country.

      One of 2 shapes

      Option 1

      • monthstringrequired

      • year_earlier_monthstringrequired

      • coverageobjectrequired

        2 attributes
        • collected_daysintegerrequired-9007199254740991 to 9007199254740991

        • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • year_earlier_coverageobjectrequired

        2 attributes
        • collected_daysintegerrequired-9007199254740991 to 9007199254740991

        • expected_daysintegerrequired-9007199254740991 to 9007199254740991

      • itemsarray of object | nullrequired

        Null unless every day of the month was imported.

        One of 2 shapes

        Option 1

        • countrystringrequired

        • clicksnumberrequired

        • year_earlier_clicksnumber | nullrequired

        • change_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). Wait Retry-After seconds. 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).
GET /api/analytics/search/monthly
curl "https://api.brightshoal.com/api/analytics/search/monthly?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstringrequired

  • periodstring

    One of 7d 28d 90d

    Default "28d"

  • start_datestring

  • end_datestring

Returns

200 Scoped overview with window, interval, per-measure coverage and previous figures in data envelope

Response attributes
  • dataobjectrequired

    2 attributes
    • ai_mention_rateobjectrequired

      1 attribute
      • by_surfacearray of objectrequired

        One 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
        • surfacestringrequired

          One of consumer model_api

        • numeratorintegerrequired-9007199254740991 to 9007199254740991

        • denominatorintegerrequired-9007199254740991 to 9007199254740991

        • valuenumber | nullrequired

          Numerator divided by denominator, null when denominator is zero.

        • plannedintegerrequired-9007199254740991 to 9007199254740991

        • failedintegerrequired-9007199254740991 to 9007199254740991

        • missingintegerrequired-9007199254740991 to 9007199254740991

    • previousobjectrequired

      1 attribute
      • ai_mention_rateobjectrequired

        1 attribute
        • by_surfacearray of objectrequired

          One 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
          • surfacestringrequired

            One of consumer model_api

          • numeratorintegerrequired-9007199254740991 to 9007199254740991

          • denominatorintegerrequired-9007199254740991 to 9007199254740991

          • valuenumber | nullrequired

            Numerator divided by denominator, null when denominator is zero.

          • plannedintegerrequired-9007199254740991 to 9007199254740991

          • failedintegerrequired-9007199254740991 to 9007199254740991

          • missingintegerrequired-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). Wait Retry-After seconds. 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).
GET /api/analytics/search/overview
curl "https://api.brightshoal.com/api/analytics/search/overview?site_id=id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project's calls (an org-wide key covers every project by default).

  • assistant_idarray of string

    Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Start of the window, ISO 8601 with an offset. Default: 30 days before to.

  • tostringISO 8601 timestamp

    End of the window. Default: now.

  • tzstring

  • channelstring

    Optional lead channel, such as web_chat, whatsapp, phone_call or form.

Returns

200 Staffing aggregates

Response attributes
  • dataobjectrequired

    6 attributes
    • fromstringrequiredISO 8601 timestamp

    • tostringrequiredISO 8601 timestamp

    • timezonestringrequired

    • lead_arrivalsarray of objectrequired

      3 attributes
      • weekdayintegerrequired0 to 6

      • hourintegerrequired0 to 23

      • countintegerrequired

    • lead_arrivals_by_channelarray of objectrequired

      4 attributes
      • channelstringrequired

      • weekdayintegerrequired

      • hourintegerrequired

      • countintegerrequired

    • handling_by_channelarray of objectrequired

      3 attributes
      • channelstringrequired

      • handled_by_assistantintegerrequired

      • handed_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). Wait Retry-After seconds. 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).
GET /api/analytics/staffing
curl "https://api.brightshoal.com/api/analytics/staffing" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Only this project's calls (an org-wide key covers every project by default).

  • assistant_idarray of string

    Only these assistants' calls. Repeat the parameter or comma-separate the values; a row matching any of them is kept.

  • fromstringISO 8601 timestamp

    Start of the window, ISO 8601 with an offset. Default: 30 days before to.

  • tostringISO 8601 timestamp

    End of the window. Default: now.

Returns

200 OK

Response attributes
  • total_callsintegerrequired

  • total_minutesnumberrequired

  • completedintegerrequired

  • failedintegerrequired

  • by_statusarray of objectrequired

    2 attributes
    • countintegerrequired

    • statusstringrequired

  • by_call_typearray of objectrequired

    2 attributes
    • countintegerrequired

    • call_typestringrequired

  • by_canonical_ended_reasonarray of objectrequired

    2 attributes
    • countintegerrequired

    • ended_reasonstringrequired

  • dailyarray of objectrequired

    3 attributes
    • datestringrequireddate

    • callsintegerrequired

    • minutesnumberrequired

  • 400 invalid_range: from or to is not a valid timestamp, or from is not before to
  • 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). Wait Retry-After seconds. 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).
GET /api/analytics/volume
curl "https://api.brightshoal.com/api/analytics/volume" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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
    }
  ]
}