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.

Query Parameters

Parameter	Required	Description
account	optional	A single account key. Without it, every account you can access is included
accounts	optional	Comma-separated list of account keys
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
429	Hourly request limit reached. Retry later