API Overview

The SearchLight API provides programmatic access to your performance data. Its main endpoint takes a set of fields (a mix of dimensions and metrics) over a date range and returns aggregated metrics broken out by your chosen dimensions; alongside it you can request anonymized industry benchmarks, AI-generated insights, and a summary of what your credentials can reach.

* The SearchLight API is in beta and under active development. Endpoints, fields, and responses may change.

Base URL

https://searchlight.digital

Endpoints

Endpoint	Returns
GET /api	The organizations and accounts your credentials can reach, the endpoints available to you, and the field dictionary
GET /api/<organization>/events	Aggregated metrics over a date range, broken out by the dimensions you select, with filtering
GET /api/<organization>/benchmarks	Anonymized industry benchmarks for a calendar month: the industry figure for each metric and the range accounts fall into
GET /api/<organization>/insights	AI-generated performance insights published for your accounts

<organization> is your organization's id. If your login only has access to a single account, it's your account id. To look yours up, request /api, which needs no organization and lists the ones you can request.

Authentication

Include your API key in the Authorization header on every request:

--header 'Authorization: <your-api-key>'

API keys look like sl_....

User API keys

Generate your own key in the SearchLight app under Settings → API. A user key can request any organization or account your login has access to. Results are always limited to your accounts. Rotating or deleting the key from settings revokes the old key immediately.

Fields: dimensions and metrics

Every request selects a list of fields. Each field is either a dimension or a metric:

• Dimensions are categorical attributes you group by, such as account, campaign, and attributionCategory. The number of rows returned equals the number of unique combinations of the dimension values you selected.
• Metrics are the numbers computed for each row, such as spend, leads, revenuePotential, and roasPotential. Each metric carries its own definition (what it counts and how), so you never do client-side math.

A request must include at least one metric. Any field that isn't a known metric is treated as a dimension. See the dimensions and metrics references for the full lists.

fields=account,campaign,spend,leads,roasPotential
       └─ dimensions ─┘ └────── metrics ────────┘

Responses

Successful responses are JSON arrays, compressed with gzip. Use curl --compressed, or your HTTP client's automatic decompression, to handle the Content-Encoding: gzip header. Each element is one row: the selected dimension values plus the computed metrics.

Errors

Errors return a JSON object with a human-readable error message and a machine-readable code:

{ "error": "start and end are required.", "code": "missing-range" }

Status	Meaning
400	Invalid request. Missing or invalid parameters, or a request that would return too much data; the message explains what to fix
401	Unauthorized. Missing, incorrect, or revoked API key
404	Unknown or inaccessible organization. The path segment doesn't match an organization or account your credentials can access
429	Hourly request limit reached. Retry later
502	An upstream data service failed or returned an unreadable response
503	Benchmark data for the requested month is still being gathered. Retry shortly
504	The request took too long to complete. Try a shorter date range, fewer dimensions, or fewer metrics

Limits

Each request covers a date range of up to 90 days per chunk. On events, pass an interval (total, month, week, or day) to split a longer range into smaller chunks; with the default interval=total the range must be 90 days or less. Benchmarks covers one calendar month per request.

A request that would span too many accounts and intervals, or return too many rows, is rejected with a 400 whose message says what to reduce. Requests are also rate limited per user per hour; past the limit they return 429 until the hour passes.

Key terms

• Event: a single point of activity for a customer, such as a lead originating, an estimate being created, or a job closing. One customer produces many events over time.
• Conversion: the event that first creates a customer. One customer may produce multiple conversions (e.g. repeat calls), so conversions are not unique by customer.
• Lead: a unique customer whose first event was a conversion.
• Customer: a unique contact. One customer can span many events.
• Spend: ad spend including management fees. When results are grouped by campaign, spend-based metrics use spend attributed to that specific campaign.