Insights

GET https://searchlight.digital/api/<organization>/insights

Returns AI-generated performance insights for your accounts: written findings and recommended actions produced from each account's activity, published periodically per account.

Unlike events and benchmarks, this endpoint returns documents rather than computed numbers. You receive the published insight as-is.

About the insights

AI insights are written summaries of patterns the system found in an account's data — patterns that would take a human analyst hours to spot manually. SearchLight's AI reviews the business's calls, bookings, marketing channels, and revenue data, then writes plain-language observations about what's notable for that business that week.

Insights are delivered in the AI Insights section of the Weekly Brief email and in the SearchLight app under Insights (currently experimental); the app renders exactly what this endpoint returns.

What the AI analyzes

Every week, SearchLight processes the account's:

Incoming call and form data — who contacted the business, from which channel, and what happened
Booking outcomes — which contacts led to appointments, and which didn't
Revenue data — which channels are actually driving paying customers vs. just calls
Lead quality — whether calls represent real demand or noise (spam, wrong number, out-of-scope)

The AI looks for patterns that deviate from the business's own historical baseline — not generic benchmarks. If the book rate drops, it looks at which channels, days, or call types drove the change. Lead quality comes from the lead grading system, which classifies calls as Bookable — Booked, Bookable — Didn't Book, or Unbookable.

What the AI does not do

It doesn't access your customers' personal information in the insights it writes
It doesn't make financial decisions — it surfaces findings; you decide what to do
It doesn't replace your judgment — it provides data-driven context for decisions you make

How accurate is it?

Numbers in an insight are computed deterministically — the AI doesn't calculate them. All statistics (book rates, lead counts, revenue figures) are pre-computed from actual data before the AI writes anything. The AI's job is to interpret and explain those pre-computed numbers, not generate them.

This means the numeric facts are reliable. The AI's interpretations are informed analysis, not guarantees.

What makes a good insight

A strong AI insight will:

Reference a specific metric or pattern (not just "your book rate was good")
Explain why the pattern is notable (compared to the business's own recent history)
Suggest a direction to investigate or act on

If an insight doesn't meet this bar, SearchLight's system suppresses it rather than including a low-quality observation.

Query Parameters

Parameter	Required	Description
`account`	optional	A single account key under the `<organization>` in the path. Without it, every account you can access under it is included
`accounts`	optional	Comma-separated list of account keys. Every key must be under the `<organization>` in the path; otherwise the request returns `404` and names the keys that are not
`start`	optional	Start date in `YYYY-MM-DD` format. Must be paired with `end`
`end`	optional	End date in `YYYY-MM-DD` format. Must be paired with `start`
`fields`	optional	Comma-separated list of document sections to return. Omit to receive the whole document

Omit start and end to receive the most recent insight for each account. Provide both to receive every insight published in that range. Providing only one returns a 400.

Dates refer to when an insight was published, not the period it covers. The period it analyzes is inside the document, as period.

Response

A JSON array (gzip-compressed, see responses). One object per insight document:

[
  {
    "account": "example-home-services",
    "date": "2026-07-21",
    "insight": {
      "account": "Example Home Services",
      "period": "June 2026",
      "generated_at": "2026-07-21T09:30:00.000000+00:00",
      "confidence": "high",
      "graded_calls": 412,
      "action_items": [
        {
          "title": "6 calls from 'water heater rental' searches, a service you don't offer",
          "summary": "The top negative keyword recommendation is ...",
          "action": "Worth discussing with your marketing agency: ...",
          "category": "operations",
          "priority": "low",
          "impact": { "value": 6, "unit": "calls", "display": "6 calls" }
        }
      ],
      "deep_insights": [
        {
          "title": "Weekend calls book at 38% while weekday calls book at 55%",
          "summary": "Weekend callers reach the answering service more often ...",
          "takeaway": "Booking capacity, not lead quality, is the weekend constraint ...",
          "priority": "high"
        }
      ]
    }
  }
]

Field	Description
`account`	The account key the insight belongs to
`date`	The date the insight was published, `YYYY-MM-DD`
`insight`	The published document, returned unmodified

Accounts with no published insights are absent from the response. When nothing matches, the response is an empty array [] with status 200.

Document sections

The document is returned as published, and its sections are still expanding while insights are in beta. The main ones today:

Section	Description
`period`	The period the insight analyzes, e.g. `"June 2026"`
`generated_at`	When the insight was produced
`confidence`	The confidence in the analysis
`graded_calls`	How many graded calls informed it
`action_items`	Specific recommended actions, each with a title, summary, suggested action, category, priority and estimated impact
`deep_insights`	Longer findings and patterns, each with a title, summary and takeaway
`surprise_insights`	Unexpected patterns worth a look, each with the insight, a suggested action, the audience and the calls behind it
`main_themes`	Recurring themes across the period, each with an overview, its share of activity, and the channels, campaigns and drivers behind it

Because this list will grow, don't assume a fixed shape. Read the sections you need and ignore the rest.

Selecting sections

Pass fields to return only the sections you need, which can substantially reduce the response size:

GET /api/<organization>/insights?fields=period,action_items

[
  {
    "account": "example-home-services",
    "date": "2026-07-21",
    "insight": {
      "period": "June 2026",
      "action_items": [ ... ]
    }
  }
]

A section name that a document doesn't carry is ignored rather than treated as an error, so request without fields first to see everything a document holds, then narrow.

Limits

A single request returns at most 200 documents. Requesting many accounts over a wide date range can exceed that:

{ "error": "This request matched 412 insight documents, exceeding the limit of 200. Request fewer accounts or a shorter time period." }

Errors

Status	Cause
`400`	`start` without `end` (or the reverse), or more than 200 matching documents
`401`	Missing, incorrect, or revoked API key
`404`	Unknown or inaccessible organization, or an `account`/`accounts` value that is not under it; the message names the keys that are not
`429`	Hourly request limit reached. Retry later

About the insights​

What the AI analyzes​

What the AI does not do​

How accurate is it?​

What makes a good insight​

Query Parameters​

Response​

Document sections​

Selecting sections​

Limits​

Errors​