Lookout API reference
Every endpoint of Lookout's REST API for Vercel Web Analytics: parameters, request bodies, response fields, rate limits and errors, from its OpenAPI document.
Last updated November 7, 2026
This page lists every endpoint of the Lookout REST API. For keys, the MCP server and webhooks, see API & MCP. The same reference as an OpenAPI 3.0 document: /v1/openapi.json.
Basics
- Base URL:
https://api.lookoutstats.com. Every response is JSON. - Authentication: send an API key from Settings → API & MCP as a bearer token. A key sees only its own workspace. It can only read, unless it was created with Allow notes and exports.
- Rate limit: 600 requests an hour per key. Over the limit, the API answers
429with aRetry-Afterheader. - Ranges:
rangeis24h,7dor30d, or two dates as2026-10-01..2026-10-31. The default is7d. Figures come with the previous period of the same length.
curl "https://api.lookoutstats.com/v1/boards" \ -H "Authorization: Bearer lk_live_your_key_here"
Errors
An error has a status code and a JSON body with a code and a message:
{
"error": {
"code": "not_found",
"message": "Board not found"
}
}| Status | Meaning |
|---|---|
401 | Missing, invalid or revoked API key |
403 | The key is read-only: create one with "Allow notes and exports" |
404 | No such board · No such site · No such site (or board) · No such board (or site on it) |
422 | The board holds as many notes as it can |
429 | Over 600 requests an hour per key; see Retry-After |
503 | Exports aren't set up on this server |
Endpoints
Boards
GET/v1/boards#
The workspace's boards.
curl "https://api.lookoutstats.com/v1/boards" \ -H "Authorization: Bearer lk_live_your_key_here"
Response 200: fields
boardsarray of objectThe workspace's boards.idstring (uuid)The board's id. Use it in /v1/boards/{id}/… paths.namestringThe board's name.siteCountinteger, ≥ 0How many sites are on the board.createdAtstring (date-time)When the board was created (ISO 8601).
Errors: 401 Missing, invalid or revoked API key · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/boards/{id}/sites#
Every site on the board for the range, busiest first.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/boards/{id}/sites?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
boardobjectThe board.idstring (uuid)The board's id.namestringThe board's name.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).sitesarray of objectEvery site on the board, busiest first.idstringThe site's Vercel project id. Use it in /v1/sites/{id}/… paths.domainstringThe site's production domain.visitorsinteger, ≥ 0Unique visitors in the range.previousVisitorsinteger, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.changenumber or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.pageviewsinteger, ≥ 0Page views in the range.pagesPerVisitnumber or nullPage views per visitor; null when it can't be worked out.topSourceobject or nullThe referrer that sent the most visitors; null when there is none.namestringThe referrer host.sharenumberPercent of the site's visitors, 0–100.
topCountryobject or nullThe country with the most visitors; null when there is none.namestringThe country.sharenumberPercent of the site's visitors, 0–100.
goalstring or nullThe site's goal, a Vercel custom event; null when the site has no goal.conversionsinteger, ≥ 0 or nullGoal conversions in the range; null when the site has no goal.
unavailablearray of stringSites whose figures couldn't be read just now (team access lost or Vercel slow), by domain.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/boards/{id}/flow#
Traffic between the board's sites: each site's visitors, and hops (visitors to a site whose referrer is another site of the board).
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/boards/{id}/flow?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).nodesarray of objectThe board's sites that answered, with their visitors.projectIdstringThe site's Vercel project id.domainstringThe site's production domain.visitorsinteger, ≥ 0Unique visitors in the range.sourcesarray of string, 0–3 itemsWhere most of the site's visitors came from outside the board: up to 3 referrer hosts or Direct, busiest first.
hopsarray of objectVisitors who arrived at one site of the board from another.fromstringThe project id of the site they came from.tostringThe project id of the site they arrived at.visitorsinteger, ≥ 0Visitors who arrived at to from from.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/boards/{id}/scorecard#
The board's landing pages graded A–D against each other: trend, pages per visit, conversion, Core Web Vitals, visitors sent onward.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/boards/{id}/scorecard?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).mainSiteobject or nullThe board's main site (its busiest), which isn't graded; null when the board has none.projectIdstringThe site's Vercel project id.domainstringThe site's production domain.
rowsarray of objectOne row per graded landing page, best first.projectIdstringThe site's Vercel project id.domainstringThe site's production domain.visitorsinteger, ≥ 0Unique visitors in the range.grade"A" | "B" | "C" | "D"The grade, from A (best) to D.scorenumber, ≥ 0, ≤ 1Points out of the most the graded factors allow, 0–1. Rows sort by it.factorsarray of objectWhat the grade is made of.key"trend" | "pages" | "conv" | "speed" | "flow" | "paid"The factor: trend, pages (pages per visit), conv (conversion), speed (Core Web Vitals), flow (visitors sent onward) or paid (cost per conversion).labelstringThe factor's name as the dashboard shows it.valuestringThe value as the dashboard shows it (for example +12% or 3.2%); — when not graded.rating"good" | "ok" | "weak" | "na"good, ok or weak; na when the factor isn't graded.benchstringWhat the value is measured against (for example vs previous week).notestringA short note on the value.barnumber, ≥ 0, ≤ 1000–100: the length of the bar under the value.
whystringA short reason: what holds the page back, or what it does well.reasonstringThe reason in one full sentence.nextstringWhat to fix first: the fix for the worst factor.fixablebooleanWhether any factor is weak.partialbooleanWhether some factor couldn't be graded (no goal, or Speed Insights off).vitalsobject or nullThe p75 Core Web Vitals behind the speed factor; null without Speed Insights.lcpnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.
unavailablearray of stringSites whose figures couldn't be read just now (team access lost or Vercel slow), by domain.tooFewarray of object, default [] optionalLanding pages with too few visitors to grade, busiest first.projectIdstringThe site's Vercel project id.domainstringThe site's production domain.visitorsinteger, ≥ 0Unique visitors in the range.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After
Sites
GET/v1/sites/{id}#
The site and its Core Web Vitals (Speed Insights, p75, production) for the range.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/sites/{id}?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.namestringThe project's name in Vercel.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).speedobjectCore Web Vitals from Vercel Speed Insights: p75 of real visitors, production only, for the range.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.status"passing" | "needs_work" | "poor" | "off"passing when LCP, INP and CLS are all good on every device with samples; else needs_work or poor; off when there are no samples (Speed Insights not on).mobileobject or nullThe values for mobile visitors; null when there are none.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.
desktopobject or nullThe values for desktop visitors; null when there are none.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/series#
Visitors per hour (24h) or day, with the previous period.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/sites/{id}/series?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).granularity"hour" | "day"hour for 24h, day for every other range.pointsarray of objectVisitors per hour or day, oldest first.startstring (date-time)The start of the hour or day (ISO 8601).visitorsinteger, ≥ 0Visitors in this hour or day.previousVisitorsinteger, ≥ 0 or nullVisitors in the matching hour or day of the previous period; null when there is nothing to compare with.
visitorsinteger, ≥ 0Unique visitors in the range.previousVisitorsinteger, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.changenumber or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.pageviewsinteger, ≥ 0Page views in the range.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/overview#
One site in depth in one request: series, top referrers, countries and pages, production deployments, Core Web Vitals and, with a board, its notes.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
boardquery · optional | string, 1–100 characters | A board the site is on (id or name): adds its notes dated in the range |
curl "https://api.lookoutstats.com/v1/sites/{id}/overview?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.namestringThe project's name in Vercel.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).goalstring or nullThe site's goal, a Vercel custom event; null when the site has no goal.granularity"hour" | "day"hour for 24h, day for every other range.visitorsinteger, ≥ 0Unique visitors in the range.previousVisitorsinteger, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.changenumber or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.pageviewsinteger, ≥ 0Page views in the range.pointsarray of objectVisitors per hour or day, oldest first.startstring (date-time)The start of the hour or day (ISO 8601).visitorsinteger, ≥ 0Visitors in this hour or day.previousVisitorsinteger, ≥ 0 or nullVisitors in the matching hour or day of the previous period; null when there is nothing to compare with.
referrersarray of objectThe top 5 referrers.namestringThe referrer host.visitorsinteger, ≥ 0Visitors from this referrer.sharenumberPercent of the site's visitors, 0–100.
countriesarray of objectThe top 5 countries.namestringThe country.visitorsinteger, ≥ 0Visitors from this country.sharenumberPercent of the site's visitors, 0–100.
pagesarray of objectThe top 5 pages.namestringThe page's path.visitorsinteger, ≥ 0Visitors who saw this page.sharenumberPercent of the site's visitors, 0–100.
deploymentsarray of object or nullProduction deployments in the range, newest first (at most 20); null when Vercel didn't answer.atstring (date-time)When the deployment was made (ISO 8601).messagestring or nullThe commit message; null when there is none.branchstring or nullThe git branch; null when there is none.statestringVercel's state for the deployment, for example READY.
speedobjectCore Web Vitals from Vercel Speed Insights: p75 of real visitors, production only, for the range.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.status"passing" | "needs_work" | "poor" | "off"passing when LCP, INP and CLS are all good on every device with samples; else needs_work or poor; off when there are no samples (Speed Insights not on).mobileobject or nullThe values for mobile visitors; null when there are none.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.
desktopobject or nullThe values for desktop visitors; null when there are none.lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.
notesarray of object optionalThe board's notes.idstring (uuid)The note's id.siteIdstring or nullThe site the note is for; null when it is for every site on the board.datestring (date)The day the note is pinned to (YYYY-MM-DD).textstringThe note's text.
Errors: 401 Missing, invalid or revoked API key · 404 No such site (or board) · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/breakdowns#
The site's top 5 referrers, countries and pages, with each one's share of visitors.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/sites/{id}/breakdowns?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).referrersarray of objectThe top 5 referrers.namestringThe referrer host.visitorsinteger, ≥ 0Visitors from this referrer.sharenumberPercent of the site's visitors, 0–100.
countriesarray of objectThe top 5 countries.namestringThe country.visitorsinteger, ≥ 0Visitors from this country.sharenumberPercent of the site's visitors, 0–100.
pagesarray of objectThe top 5 pages.namestringThe page's path.visitorsinteger, ≥ 0Visitors who saw this page.sharenumberPercent of the site's visitors, 0–100.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/deployments#
The site's production deployments in the range, newest first (at most 20).
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/sites/{id}/deployments?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).deploymentsarray of objectProduction deployments in the range, newest first (at most 20).atstring (date-time)When the deployment was made (ISO 8601).messagestring or nullThe commit message; null when there is none.branchstring or nullThe git branch; null when there is none.statestringVercel's state for the deployment, for example READY.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/speed#
Core Web Vitals (Speed Insights p75, production) for one device, and its slowest routes by LCP.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
devicequery · optional | "all" | "mobile" | "desktop", default "all" | all, mobile or desktop |
curl "https://api.lookoutstats.com/v1/sites/{id}/speed?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).device"all" | "mobile" | "desktop"all, mobile or desktop.status"passing" | "needs_work" | "poor" | "off"passing, needs_work or poor for this device; off when there are no samples (Speed Insights not on).lcpMsnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpMsnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.samplesinteger, ≥ 0How many page loads the values come from.routesarray of objectThe device's slowest routes by LCP.routestringThe route, as the app names it (for example /blog/[slug]).lcpMsnumberThe route's Largest Contentful Paint at p75, in milliseconds.samplesinteger, ≥ 0How many page loads of this route the value comes from.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
Campaigns
GET/v1/sites/{id}/campaigns#
Visitors by UTM campaign, source and medium (Vercel Web Analytics Plus).
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
curl "https://api.lookoutstats.com/v1/sites/{id}/campaigns?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
siteobjectThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).status"ok" | "plan_required"Always ok. plan_required is no longer sent: see mode.mode"utm" | "events" | "platform"Where the campaigns come from: utm (Vercel's UTM tags, with Web Analytics Plus or Enterprise), events (the site's campaign custom event) or platform (no Plus: the ad platform of the referrer).goalstring or nullThe site's goal, a Vercel custom event; null when the site has no goal.visitorsinteger, ≥ 0All the site's visitors in the range, tagged or not.campaignsarray of objectOne row per campaign and source.campaignstringThe utm_campaign value. In platform mode, the ad platform.sourcestringThe utm_source value. In platform mode, the referrer host.mediumstringThe utm_medium value. In platform mode, referrer.visitorsinteger, ≥ 0Visitors from this campaign and source.previousVisitorsinteger, ≥ 0Visitors from this campaign and source in the previous period.pageviewsinteger, ≥ 0Page views from this campaign and source.conversionsinteger, ≥ 0 or nullGoal conversions from this campaign and source; null when the site has no goal.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
GET/v1/sites/{id}/campaigns/{utm}/spend#
The campaign's spend: this period's row (else the latest), and every period's, newest first.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
utmpath | string: no control characters, 1–200 characters | The utm_campaign value, URL-encoded |
curl "https://api.lookoutstats.com/v1/sites/{id}/campaigns/{utm}/spend" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
currentobject or nullThe row for this period, else the latest one; null when the campaign has no spend.campaignstringThe campaign (its utm_campaign value).platform"google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.amountnumber, ≥ 0What was paid for the period, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.period"month" | "30d"month (a calendar month) or 30d (30 days from periodStart).periodStartstring: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).repeatMonthlybooleanWhether the amount repeats every month until it is changed.
historyarray of objectEvery row, newest first.campaignstringThe campaign (its utm_campaign value).platform"google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.amountnumber, ≥ 0What was paid for the period, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.period"month" | "30d"month (a calendar month) or 30d (30 days from periodStart).periodStartstring: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).repeatMonthlybooleanWhether the amount repeats every month until it is changed.
Errors: 401 Missing, invalid or revoked API key · 404 No such site · 429 Over 600 requests an hour per key; see Retry-After
PUT/v1/sites/{id}/campaigns/{utm}/spend#
Saved: that period's row (this period's when periodStart is omitted) replaced; history is kept. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
idpath | string: letters, digits, _ and -, up to 64 | A site's Vercel project id, from GET /v1/boards/{id}/sites |
utmpath | string: no control characters, 1–200 characters | The utm_campaign value, URL-encoded |
Request body (JSON)
amountnumber, ≥ 0, ≤ 9999999999.99What was paid for the period, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.platform"google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.period"month" | "30d"month (a calendar month) or 30d (30 days from periodStart).periodStartstring: YYYY-MM-DD optionalThe first day of the period to set (YYYY-MM-DD). Without it, the period that holds today. A past period changes only that period.repeatMonthlybooleanWhether the amount repeats every month until it is changed.
curl -X PUT "https://api.lookoutstats.com/v1/sites/{id}/campaigns/{utm}/spend" \
-H "Authorization: Bearer lk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ … }'Response 200: fields
currentobject or nullThe row for this period, else the latest one; null when the campaign has no spend.campaignstringThe campaign (its utm_campaign value).platform"google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.amountnumber, ≥ 0What was paid for the period, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.period"month" | "30d"month (a calendar month) or 30d (30 days from periodStart).periodStartstring: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).repeatMonthlybooleanWhether the amount repeats every month until it is changed.
historyarray of objectEvery row, newest first.campaignstringThe campaign (its utm_campaign value).platform"google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.amountnumber, ≥ 0What was paid for the period, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.period"month" | "30d"month (a calendar month) or 30d (30 days from periodStart).periodStartstring: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).repeatMonthlybooleanWhether the amount repeats every month until it is changed.
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 429 Over 600 requests an hour per key; see Retry-After
Notes and exports
GET/v1/boards/{id}/annotations#
The board's notes (dated annotations), oldest first.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
sitequery · optional | string: letters, digits, _ and -, up to 64 | Only this site's notes (and the board-wide ones) |
rangequery · optional | "24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD | Only the notes dated in this range |
curl "https://api.lookoutstats.com/v1/boards/{id}/annotations?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
boardobjectThe board.idstring (uuid)The board's id.namestringThe board's name.
notesarray of objectThe board's notes.idstring (uuid)The note's id.boardIdstring (uuid)The board the note is on.siteIdstring or nullThe site the note is for; null when it is for every site on the board.datestring (date)The day the note is pinned to (YYYY-MM-DD).textstringThe note's text.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After
POST/v1/boards/{id}/annotations#
The note, pinned to the day on the board's charts. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
Request body (JSON)
datestring (date)The day the note is pinned to (YYYY-MM-DD).textstring, 1–200 charactersThe note's text. It is trimmed and kept to its first 80 characters.siteIdstring: letters, digits, _ and -, up to 64 optionalOnly for this site. Without it, the note is for every site on the board.
curl -X POST "https://api.lookoutstats.com/v1/boards/{id}/annotations" \
-H "Authorization: Bearer lk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ … }'Response 201: fields
noteobjectThe note that was added.idstring (uuid)The note's id.boardIdstring (uuid)The board the note is on.siteIdstring or nullThe site the note is for; null when it is for every site on the board.datestring (date)The day the note is pinned to (YYYY-MM-DD).textstringThe note's text.
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 422 The board holds as many notes as it can · 429 Over 600 requests an hour per key; see Retry-After
POST/v1/boards/{id}/export#
A download link for the board as a PDF or CSV; it works for 5 minutes. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
Request body (JSON)
format"pdf" | "csv", default "pdf" optionalpdf (the default) or csv.range"24h" | "7d" | "30d", default "7d" optionalThe period to export: 24h, 7d (the default) or 30d.
curl -X POST "https://api.lookoutstats.com/v1/boards/{id}/export" \
-H "Authorization: Bearer lk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ … }'Response 200: fields
boardobjectThe board.idstring (uuid)The board's id.namestringThe board's name.
format"pdf" | "csv"pdf or csv.rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).urlstring (uri)The download link.expiresAtstring (date-time)When the link stops working, 5 minutes after it was made (ISO 8601).
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 429 Over 600 requests an hour per key; see Retry-After · 503 Exports aren't set up on this server
Fix list
GET/v1/boards/{id}/fixes#
Everything worth fixing on the board (Core Web Vitals, dead ends, one-page visits, conversion, trend, untagged campaigns, setup), ranked by visitors affected; ?status=open|snoozed|resolved filters the items.
| Parameter | Type | Description |
|---|---|---|
idpath | string, 1–100 characters | A board's id from GET /v1/boards, or its exact name (case-insensitive) |
rangequery · optional | string | The period: 24h, 7d, 30d or two dates (see Basics). Default 7d. |
statusquery · optional | "open" | "snoozed" | "resolved" | Only the items with this status. Without it, every item. |
curl "https://api.lookoutstats.com/v1/boards/{id}/fixes?range=7d" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
rangestringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).itemsarray of objectThe board's items, ranked by visitors affected.idstringThe item's id, kind:domain (for example speed:acme.com). Use it in /v1/fixes/{itemId}/… paths.kind"speed" | "deadend" | "bounce" | "conversion" | "trend" | "campaigns" | "spend" | "setup"speed, deadend, bounce, conversion, trend, campaigns, spend or setup.projectIdstring or nullThe site's Vercel project id; null for a team project Lookout doesn't track yet.domainstringThe site's production domain.frameworkstring or nullThe site's framework preset in Vercel (for example nextjs); null when it isn't known.titlestringWhat to fix.detailstringThe numbers behind it.whystringWhy it matters.verifystringWhere the result shows once it is fixed.impactinteger, ≥ 0Visitors affected in the range. For a spend item, the spend in its currency.prompt"speedfix" | "flow" | "grade" | "utm" | "utm_events" | "speed" | "events" | "analytics"Which repo-ready prompt the dashboard's Copy prompt builds for the item.contextobjectThe data the item's prompt uses.teamSlugstring or null optionalThe site's Vercel team. The public API leaves it out.gradeobject optionalThe site's Scorecard row, for a grade item.grade"A" | "B" | "C" | "D"The grade, from A (best) to D.factorsarray of objectWhat the grade is made of.key"trend" | "pages" | "conv" | "speed" | "flow" | "paid"The factor: trend, pages (pages per visit), conv (conversion), speed (Core Web Vitals), flow (visitors sent onward) or paid (cost per conversion).labelstringThe factor's name as the dashboard shows it.valuestringThe value as the dashboard shows it (for example +12% or 3.2%); — when not graded.rating"good" | "ok" | "weak" | "na"good, ok or weak; na when the factor isn't graded.benchstringWhat the value is measured against (for example vs previous week).notestringA short note on the value.barnumber, ≥ 0, ≤ 1000–100: the length of the bar under the value.
vitalsobject or nullThe p75 Core Web Vitals behind the speed factor; null without Speed Insights.lcpnumber or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpnumber or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber or nullCumulative Layout Shift at p75 (no unit); null without samples.
speedobject optionalThe values behind a speed item.device"all" | "mobile" | "desktop"all, mobile or desktop.valuesobjectCore Web Vitals at p75.lcpnumber, ≥ 0 or nullLargest Contentful Paint at p75, in milliseconds; null without samples.inpnumber, ≥ 0 or nullInteraction to Next Paint at p75, in milliseconds; null without samples.clsnumber, ≥ 0 or nullCumulative Layout Shift at p75 (no unit); null without samples.
mainSitestring or null optionalThe board's main site, by domain.spendobject optionalThe campaign behind a spend item.campaignstringThe campaign (its utm_campaign value).amountnumber, ≥ 0The campaign's spend in the range, in currency.currency"USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.costPerConversionnumber, ≥ 0The campaign's cost per goal conversion, in currency.mediannumber, ≥ 0The median cost per conversion of the board's campaigns in the same currency.
status"open" | "snoozed" | "resolved"open, snoozed or resolved.snoozedUntilnumber or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.resolvedAtnumber or nullWhile resolved: when the item was resolved (epoch milliseconds); else null.
countsobjectItems per status, before the status filter.openinteger, ≥ 0Open items.snoozedinteger, ≥ 0Snoozed items.resolvedinteger, ≥ 0Resolved items.
resolvedThisMonthinteger, ≥ 0Items resolved since the first of the month (UTC), on any board.unavailablearray of stringSites whose figures couldn't be read just now: their items may be missing.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After
POST/v1/fixes/{itemId}/resolve#
Resolved; a note “Resolved: {title}” is added to the site on that board. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
itemIdpath | string, 3–300 characters | A Fix list item's id (`kind:domain`) from GET /v1/boards/{id}/fixes |
Request body (JSON)
boardIdstring, 1–64 charactersThe board whose Fix list holds the item. The note goes on the item's site there.rangestring, 0–40 characters optionalThe range the item was listed for. The default is 7d.
curl -X POST "https://api.lookoutstats.com/v1/fixes/{itemId}/resolve" \
-H "Authorization: Bearer lk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ … }'Response 200: fields
idstringThe item's id, kind:domain.status"open" | "snoozed" | "resolved"open, snoozed or resolved.snoozedUntilnumber or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.resolvedAtnumber or nullWhile resolved: when the item was resolved (epoch milliseconds); else null.
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 429 Over 600 requests an hour per key; see Retry-After
POST/v1/fixes/{itemId}/reopen#
Back on the open list. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
itemIdpath | string, 3–300 characters | A Fix list item's id (`kind:domain`) from GET /v1/boards/{id}/fixes |
curl -X POST "https://api.lookoutstats.com/v1/fixes/{itemId}/reopen" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
idstringThe item's id, kind:domain.status"open" | "snoozed" | "resolved"open, snoozed or resolved.snoozedUntilnumber or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.resolvedAtnumber or nullWhile resolved: when the item was resolved (epoch milliseconds); else null.
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 429 Over 600 requests an hour per key; see Retry-After
POST/v1/fixes/{itemId}/snooze#
Hidden for a week; it comes back on its own. Needs a key created with Allow notes and exports.
| Parameter | Type | Description |
|---|---|---|
itemIdpath | string, 3–300 characters | A Fix list item's id (`kind:domain`) from GET /v1/boards/{id}/fixes |
curl -X POST "https://api.lookoutstats.com/v1/fixes/{itemId}/snooze" \
-H "Authorization: Bearer lk_live_your_key_here"Response 200: fields
idstringThe item's id, kind:domain.status"open" | "snoozed" | "resolved"open, snoozed or resolved.snoozedUntilnumber or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.resolvedAtnumber or nullWhile resolved: when the item was resolved (epoch milliseconds); else null.
Errors: 401 Missing, invalid or revoked API key · 403 The key is read-only: create one with "Allow notes and exports" · 404 No such board (or site on it) · 429 Over 600 requests an hour per key; see Retry-After
Alerts
GET/v1/alerts#
Alert rules and what fired in the last 30 days.
curl "https://api.lookoutstats.com/v1/alerts" \ -H "Authorization: Bearer lk_live_your_key_here"
Response 200: fields
alertsarray of objectThe workspace's alert rules.idstring (uuid)The alert rule's id.boardobjectThe board the rule watches.idstring (uuid)The board's id.namestringThe board's name.
metricstringvisitors, pageviews or pages_per_visit.direction"drop" | "rise"drop or rise.thresholdintegerThe change, in percent, that fires the alert.enabledbooleanWhether the rule is on.lastFiredAtstring (date-time) or nullWhen the rule last fired (ISO 8601); null when it never has.
recentarray of objectWhat fired in the last 30 days, newest first.atstring (date-time)When it fired (ISO 8601).textstringWhat the alert said.boardstring or nullThe board's name; null when the board is gone.
Errors: 401 Missing, invalid or revoked API key · 429 Over 600 requests an hour per key; see Retry-After
Ask Lookout
POST/v1/ask#
One sentence with the key number, up to three points, the site to open and, comparing several, a small chart. Answered only from the workspace's figures.
Request body (JSON)
questionstring, 1–300 charactersA question about the workspace's sites, in plain wordsscope"board" | "workspace", default "workspace" optionalworkspace: every board, sites counted once; board: one board (needs board)boardstring, 1–100 characters optionalFor scope board: the board's id or exact namerange"24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DD, default "7d" optionalThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
curl -X POST "https://api.lookoutstats.com/v1/ask" \
-H "Authorization: Bearer lk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ … }'Response 200: fields
answerstringOne sentence answering the question, the key number in **bold** (Markdown).pointsarray of string, 0–3 itemsVisitors per hour or day, oldest first.siteobject or nullThe site.idstringThe site's Vercel project id.domainstringThe site's production domain.
actionstring or nullA few words for a link to `site`, e.g. "Open the site"; null without a site.chartobject or nullA small bar list, only when the answer compares several sites or boards; null otherwise.titlestringWhat to fix.rowsarray of object, 1–5 itemsOne row per graded landing page, best first.labelstringThe factor's name as the dashboard shows it.valuenumberThe value as the dashboard shows it (for example +12% or 3.2%); — when not graded.unit"%" | "visitors"What `value` counts: % (change against the previous period) or visitors.siteIdstring or nullThe site the note is for; null when it is for every site on the board.
source"model" | "facts"The utm_source value. In platform mode, the referrer host.
Errors: 401 Missing, invalid or revoked API key · 404 No such board · 429 Over 600 requests an hour per key; see Retry-After