Insights

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

What happened, and what moved

GET /insights/digest

Scope: insights:read. Operation id: getDigest.

The window's totals against the equally long window before it, with every metric ranked by how much it actually changed. Defaults to the last seven days. Reads the day rollups, so the cost is one row per day whatever the traffic. missingDays names any day not folded yet, so partial figures are visible rather than quietly low.

Parameters

Name	In	Type	Meaning
`from`	query	string
`to`	query	string

Example request

curl "https://api.showpilot.com/v1/insights/digest" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The digest.

Digest

Field	Type	Always	Meaning
`range`	object	yes
`comparedWith`	object	yes
`days`	integer	yes
`totals`	DigestTotals	yes
`previousTotals`	DigestTotals	yes
`metrics`	array of object	yes	Every metric, largest absolute change first.
`missingDays`	array of string	yes	Days in the range with no folded row yet.

DigestTotals

Field	Type	Always	Meaning
`visitors`	integer	yes
`conversations`	integer	yes
`meetings`	integer	yes
`formsSubmitted`	integer	yes
`escalated`	integer	yes	Conversations the agent handed to a person.
`tourPlays`	integer	yes
`tourCompletions`	integer	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

What visitors asked that the agent could not answer

GET /insights/knowledge-gaps

Scope: insights:read. Operation id: listKnowledgeGaps.

Each question in the visitor's own words, why the agent stalled, and whether a human has since answered it. Deliberately NOT clustered — your own model groups them better than a pattern would, and normalized collapses exact repeats without one. Questions are transcript content: masked unless the key holds conversations:transcripts.

Parameters

Name	In	Type	Meaning
`from`	query	string
`to`	query	string
`status`	query	`open` · `answered` · `dismissed` · `any`	Default `open` — the ones still unanswered.
`limit`	query	integer

Example request

curl "https://api.showpilot.com/v1/insights/knowledge-gaps" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The questions.

Field	Type	Always	Meaning
`items`	array of KnowledgeGap	yes
`redaction`	object	yes

KnowledgeGap

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`question`	string	yes	The visitor's own words. Masked unless the key holds `conversations:transcripts`.
`normalized`	string	yes	Lowercased and stripped
`reason`	string or null	yes	Why the agent could not answer — a guardrail
`status`	`open` · `answered` · `dismissed`	yes
`answered`	boolean	yes
`redacted`	boolean	no	True when something in the question was masked. Absent on a verbatim read.
`visitorId`	string or null (uuid)	yes
`conversationId`	string or null (uuid)	yes
`askedAt`	string (date-time)	yes
`answeredAt`	string or null (date-time)	yes

Errors

Status	When
400	A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code `invalid-request`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Companies worth a call right now

GET /insights/sales-ready-accounts

Scope: insights:read. Operation id: listSalesReadyAccounts.

Recently engaged visitors grouped by company, strongest intent first, with whether your CRM already shows an open deal and who owns it. There is no fit or ICP score — engagement and intent are measured, fit is not, and a number we invented would be worse than none.

Parameters

Name	In	Type	Meaning
`withinDays`	query	integer	How recently someone from the company was seen. Default 30.
`minIntent`	query	integer	Lowest intent score to include. Default 40.
`limit`	query	integer

Example request

curl "https://api.showpilot.com/v1/insights/sales-ready-accounts" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The companies.

Field	Type	Always	Meaning
`items`	array of SalesReadyAccount	yes

SalesReadyAccount

Field	Type	Always	Meaning
`domain`	string	yes
`name`	string or null	yes
`industry`	string or null	yes
`visitorCount`	integer	yes	People from this company seen in the window.
`identifiedCount`	integer	yes	How many of them you have an email for.
`topIntent`	integer	yes	The strongest intent score in the group.
`lastSeenAt`	string (date-time)	yes
`lifecycleStage`	string or null	yes	From your CRM.
`ownerEmail`	string or null	yes
`hasOpenDeal`	boolean	yes	False when no CRM is connected.
`visitorIds`	array of string (uuid)	yes	The strongest-intent visitors

Errors

Status	When
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Tour plays, completions and time watched, by tour and by day

GET /insights/tours

Scope: insights:read. Operation id: listTourInsights.

Per-tour totals over the range plus one row per tour per day. identified sums per-day distinct viewer emails, so a repeat viewer across days counts each day. Reads rollups only; cost is a few hundred rows whatever the traffic.

Parameters

Name	In	Type	Meaning
`from`	query	string (date)	First day of the range (UTC), `YYYY-MM-DD`. Default is 29 days before `to`.
`to`	query	string (date)	Last day of the range (UTC), `YYYY-MM-DD`, inclusive. Default is today. The range is at most 366 days.

Example request

curl "https://api.showpilot.com/v1/insights/tours?from=2026-08-25&to=2026-09-23" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Totals and daily rows for the range.

TourInsights

Field	Type	Always	Meaning
`range`	Range	yes
`tours`	array of TourTotal	yes	Sorted by plays, most first.
`daily`	array of TourDay	yes	Sorted by day.

Range

Field	Type	Always	Meaning
`from`	string (date)	yes
`to`	string (date)	yes

TourTotal

One tour over the whole range.

Field	Type	Always	Meaning
`tourId`	string (uuid)	yes
`name`	string or null	yes
`publicId`	string or null	yes	The id in share links and embeds.
`plays`	integer	yes
`engaged`	integer	yes
`completions`	integer	yes
`ctaClicks`	integer	yes
`identified`	integer	yes	Sum of per-day distinct emails.
`totalSecs`	integer	yes
`days`	integer	yes	Days in the range with at least one play.

TourDay

One tour on one day.

Field	Type	Always	Meaning
`tourId`	string (uuid)	yes
`day`	string (date)	yes
`plays`	integer	yes	Sittings that started that day.
`engaged`	integer	yes	Sittings that reached step 2 or later.
`completions`	integer	yes
`ctaClicks`	integer	yes
`identified`	integer	yes	Distinct viewer emails that day.
`totalSecs`	integer	yes	Seconds watched

Example response

{
  "range": {
    "from": "2026-08-25",
    "to": "2026-09-23"
  },
  "tours": [
    {
      "tourId": "c5879294-795a-5430-88b1-7fdbdfa910ce",
      "name": "A First Walk Through the App",
      "publicId": "t_9f3k2q",
      "plays": 184,
      "engaged": 151,
      "completions": 35,
      "ctaClicks": 4,
      "identified": 12,
      "totalSecs": 48551,
      "days": 27
    }
  ],
  "daily": [
    {
      "tourId": "c5879294-795a-5430-88b1-7fdbdfa910ce",
      "day": "2026-09-23",
      "plays": 9,
      "engaged": 7,
      "completions": 2,
      "ctaClicks": 0,
      "identified": 1,
      "totalSecs": 2210
    }
  ]
}

Errors

Status	When
400	`from` or `to` is not a day, `to` is before `from`, or the range is over 366 days. Code `invalid-range`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

Visitors, conversations, meetings and outcomes for the workspace, by day and by source

GET /insights/pulse

Scope: insights:read. Operation id: getPulseInsights.

The Pulse page's totals over the range, one row per day, and the top 25 traffic sources with their sessions, conversations, meetings and outcomes.

Parameters

Name	In	Type	Meaning
`from`	query	string (date)	First day of the range (UTC), `YYYY-MM-DD`. Default is 29 days before `to`.
`to`	query	string (date)	Last day of the range (UTC), `YYYY-MM-DD`, inclusive. Default is today. The range is at most 366 days.

Example request

curl "https://api.showpilot.com/v1/insights/pulse?from=2026-08-25&to=2026-09-23" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Totals, daily rows and sources for the range.

PulseInsights

Field	Type	Always	Meaning
`range`	Range	yes
`totals`	OrgTotals	yes
`daily`	array of OrgDay	yes
`sources`	array of SourceTotal	yes	Top 25 by sessions.

Range

Field	Type	Always	Meaning
`from`	string (date)	yes
`to`	string (date)	yes

OrgTotals

The same fields as a day row, summed over the range.

Field	Type	Always
`visitors`	integer	yes
`conversedVisitors`	integer	yes
`meetingVisitors`	integer	yes
`sessions`	integer	yes
`conversations`	integer	yes
`meetings`	integer	yes
`formSubmitted`	integer	yes
`outcomes`	integer	yes
`tourPlays`	integer	yes
`tourCompletions`	integer	yes

OrgDay

The workspace on one day.

Field	Type	Always	Meaning
`day`	string (date)	yes
`visitors`	integer	yes	Distinct visitors seen.
`conversedVisitors`	integer	yes	Visitors who exchanged messages with the agent.
`meetingVisitors`	integer	yes	Visitors who booked a meeting.
`sessions`	integer	yes
`conversations`	integer	yes	Sessions with at least one message.
`meetings`	integer	yes
`formSubmitted`	integer	yes
`outcomes`	integer	yes	Offers accepted
`tourPlays`	integer	yes
`tourCompletions`	integer	yes

SourceTotal

One traffic source over the range.

Field	Type	Always	Meaning
`source`	string	yes	`utm_source`, else the referrer host, else `direct`.
`sessions`	integer	yes
`conversations`	integer	yes
`meetings`	integer	yes
`outcomes`	integer	yes

Example response

{
  "range": {
    "from": "2026-08-25",
    "to": "2026-09-23"
  },
  "totals": {
    "visitors": 1240,
    "conversedVisitors": 96,
    "meetingVisitors": 11,
    "sessions": 1502,
    "conversations": 104,
    "meetings": 12,
    "formSubmitted": 31,
    "outcomes": 19,
    "tourPlays": 388,
    "tourCompletions": 71
  },
  "daily": [
    {
      "day": "2026-09-23",
      "visitors": 52,
      "conversedVisitors": 4,
      "meetingVisitors": 1,
      "sessions": 60,
      "conversations": 4,
      "meetings": 1,
      "formSubmitted": 2,
      "outcomes": 1,
      "tourPlays": 15,
      "tourCompletions": 3
    }
  ],
  "sources": [
    {
      "source": "google",
      "sessions": 640,
      "conversations": 41,
      "meetings": 5,
      "outcomes": 8
    }
  ]
}

Errors

Status	When
400	`from` or `to` is not a day, `to` is before `from`, or the range is over 366 days. Code `invalid-range`.
401	No key, or an unknown or revoked key. Code `unauthorized`.
403	A valid key without the operation's scope (code `insufficient-scope`), or a plan without API access (code `plan-api-off`).
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page