Events
GET https://searchlight.digital/api/<organization>/events
Returns aggregated metrics over a date range, broken out by the dimensions you select. You choose what to compute and how to slice it with the fields parameter; the API does the aggregation and returns finished numbers.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
fields | required | Comma-separated list of dimensions and metrics. Must include at least one metric. Example: fields=account,campaign,spend,leads |
start | required | Start date in YYYY-MM-DD format |
end | required | End date in YYYY-MM-DD format |
account | optional | A single account key to restrict results |
accounts | optional | Comma-separated list of account keys to restrict results |
interval | optional | total (default), month, week, or day. Computes the metrics separately for each interval and allows ranges longer than 90 days |
Any field can also be used as a filter by passing it as a query parameter with a value, for example attributionCategory=Advertising. See filtering for the operators and cross-field logic.
How fields work
Each name in fields is classified automatically:
- If it's a known metric (see the metrics reference), it's computed.
- Otherwise it's treated as a dimension and the results are grouped by it.
One row is returned per unique combination of the selected dimension values, with every selected metric computed for that row. Selecting no dimensions (only metrics) returns a single aggregated row.
To break results out by account, include account in fields. Without it, the accounts in your group (or those named in account/accounts) are aggregated together. When campaign is among the dimensions, spend-based metrics automatically use spend attributed to the specific campaign.
Response
A JSON array (gzip-compressed, see responses). Each object contains the selected dimension values and the computed metrics:
[
{ "account": "Example Home Services", "campaign": "Search - Branded", "spend": 2104.33, "leads": 64, "roasPotential": 5.65 }
]
Intervals
With interval=month, week, or day, the metrics are computed independently for each sub-range and every row is tagged with its start and end. It combines with dimensions, so interval=week with fields=account,... returns one row per week × account. Sub-ranges at the edges of your range may be partial.
[
{ "start": "2026-05-01", "end": "2026-05-03", "account": "Example Home Services", "spend": 1450.00, "leads": 38 },
{ "start": "2026-05-04", "end": "2026-05-10", "account": "Example Home Services", "spend": 3680.50, "leads": 92 }
]
Date range limit
Each interval must stay within the 90-day attribution window. With the default interval=total (a single chunk), a range over 90 days is rejected; split longer ranges with interval=month, week, or day:
{ "error": "Requested range spans 120 days, exceeding the 90-day attribution window. Pass interval=month|week|day to split the request into smaller intervals." }
Errors
| Status | Cause |
|---|---|
400 | Missing start/end, missing fields, fields with no metric, unknown interval, an interval over 90 days, or a request that would span too many accounts and intervals or return too many rows. The message says what to reduce |
401 | Missing, incorrect, or inactive 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 |