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 429 with a Retry-After header.
  • Ranges: range is 24h, 7d or 30d, or two dates as 2026-10-01..2026-10-31. The default is 7d. 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"
  }
}
StatusMeaning
401Missing, invalid or revoked API key
403The key is read-only: create one with "Allow notes and exports"
404No such board · No such site · No such site (or board) · No such board (or site on it)
422The board holds as many notes as it can
429Over 600 requests an hour per key; see Retry-After
503Exports 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
  • boards array of objectThe workspace's boards.
    • id string (uuid)The board's id. Use it in /v1/boards/{id}/… paths.
    • name stringThe board's name.
    • siteCount integer, ≥ 0How many sites are on the board.
    • createdAt string (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.

ParameterTypeDescription
idpathstring, 1–100 charactersA 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
  • board objectThe board.
    • id string (uuid)The board's id.
    • name stringThe board's name.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • sites array of objectEvery site on the board, busiest first.
    • id stringThe site's Vercel project id. Use it in /v1/sites/{id}/… paths.
    • domain stringThe site's production domain.
    • visitors integer, ≥ 0Unique visitors in the range.
    • previousVisitors integer, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.
    • change number or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.
    • pageviews integer, ≥ 0Page views in the range.
    • pagesPerVisit number or nullPage views per visitor; null when it can't be worked out.
    • topSource object or nullThe referrer that sent the most visitors; null when there is none.
      • name stringThe referrer host.
      • share numberPercent of the site's visitors, 0–100.
    • topCountry object or nullThe country with the most visitors; null when there is none.
      • name stringThe country.
      • share numberPercent of the site's visitors, 0–100.
    • goal string or nullThe site's goal, a Vercel custom event; null when the site has no goal.
    • conversions integer, ≥ 0 or nullGoal conversions in the range; null when the site has no goal.
  • unavailable array 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).

ParameterTypeDescription
idpathstring, 1–100 charactersA 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
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • nodes array of objectThe board's sites that answered, with their visitors.
    • projectId stringThe site's Vercel project id.
    • domain stringThe site's production domain.
    • visitors integer, ≥ 0Unique visitors in the range.
    • sources array 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.
  • hops array of objectVisitors who arrived at one site of the board from another.
    • from stringThe project id of the site they came from.
    • to stringThe project id of the site they arrived at.
    • visitors integer, ≥ 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.

ParameterTypeDescription
idpathstring, 1–100 charactersA 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
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • mainSite object or nullThe board's main site (its busiest), which isn't graded; null when the board has none.
    • projectId stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • rows array of objectOne row per graded landing page, best first.
    • projectId stringThe site's Vercel project id.
    • domain stringThe site's production domain.
    • visitors integer, ≥ 0Unique visitors in the range.
    • grade "A" | "B" | "C" | "D"The grade, from A (best) to D.
    • score number, ≥ 0, ≤ 1Points out of the most the graded factors allow, 0–1. Rows sort by it.
    • factors array 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).
      • label stringThe factor's name as the dashboard shows it.
      • value stringThe 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.
      • bench stringWhat the value is measured against (for example vs previous week).
      • note stringA short note on the value.
      • bar number, ≥ 0, ≤ 1000–100: the length of the bar under the value.
    • why stringA short reason: what holds the page back, or what it does well.
    • reason stringThe reason in one full sentence.
    • next stringWhat to fix first: the fix for the worst factor.
    • fixable booleanWhether any factor is weak.
    • partial booleanWhether some factor couldn't be graded (no goal, or Speed Insights off).
    • vitals object or nullThe p75 Core Web Vitals behind the speed factor; null without Speed Insights.
      • lcp number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
      • inp number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
      • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
  • unavailable array of stringSites whose figures couldn't be read just now (team access lost or Vercel slow), by domain.
  • tooFew array of object, default [] optionalLanding pages with too few visitors to grade, busiest first.
    • projectId stringThe site's Vercel project id.
    • domain stringThe site's production domain.
    • visitors integer, ≥ 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • name stringThe project's name in Vercel.
    • domain stringThe site's production domain.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • speed objectCore Web Vitals from Vercel Speed Insights: p75 of real visitors, production only, for the range.
    • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
    • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
    • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
    • samples integer, ≥ 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).
    • mobile object or nullThe values for mobile visitors; null when there are none.
      • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
      • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
      • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • samples integer, ≥ 0How many page loads the values come from.
    • desktop object or nullThe values for desktop visitors; null when there are none.
      • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
      • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
      • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • samples integer, ≥ 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • range stringThe 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.
  • points array of objectVisitors per hour or day, oldest first.
    • start string (date-time)The start of the hour or day (ISO 8601).
    • visitors integer, ≥ 0Visitors in this hour or day.
    • previousVisitors integer, ≥ 0 or nullVisitors in the matching hour or day of the previous period; null when there is nothing to compare with.
  • visitors integer, ≥ 0Unique visitors in the range.
  • previousVisitors integer, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.
  • change number or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.
  • pageviews integer, ≥ 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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 · optionalstring, 1–100 charactersA 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • name stringThe project's name in Vercel.
    • domain stringThe site's production domain.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • goal string 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.
  • visitors integer, ≥ 0Unique visitors in the range.
  • previousVisitors integer, ≥ 0 or nullVisitors in the previous period of the same length; null when there is nothing to compare with.
  • change number or nullChange in visitors against the previous period, in percent (12.5 is +12.5%); null when there is nothing to compare with.
  • pageviews integer, ≥ 0Page views in the range.
  • points array of objectVisitors per hour or day, oldest first.
    • start string (date-time)The start of the hour or day (ISO 8601).
    • visitors integer, ≥ 0Visitors in this hour or day.
    • previousVisitors integer, ≥ 0 or nullVisitors in the matching hour or day of the previous period; null when there is nothing to compare with.
  • referrers array of objectThe top 5 referrers.
    • name stringThe referrer host.
    • visitors integer, ≥ 0Visitors from this referrer.
    • share numberPercent of the site's visitors, 0–100.
  • countries array of objectThe top 5 countries.
    • name stringThe country.
    • visitors integer, ≥ 0Visitors from this country.
    • share numberPercent of the site's visitors, 0–100.
  • pages array of objectThe top 5 pages.
    • name stringThe page's path.
    • visitors integer, ≥ 0Visitors who saw this page.
    • share numberPercent of the site's visitors, 0–100.
  • deployments array of object or nullProduction deployments in the range, newest first (at most 20); null when Vercel didn't answer.
    • at string (date-time)When the deployment was made (ISO 8601).
    • message string or nullThe commit message; null when there is none.
    • branch string or nullThe git branch; null when there is none.
    • state stringVercel's state for the deployment, for example READY.
  • speed objectCore Web Vitals from Vercel Speed Insights: p75 of real visitors, production only, for the range.
    • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
    • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
    • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
    • samples integer, ≥ 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).
    • mobile object or nullThe values for mobile visitors; null when there are none.
      • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
      • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
      • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • samples integer, ≥ 0How many page loads the values come from.
    • desktop object or nullThe values for desktop visitors; null when there are none.
      • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
      • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
      • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • samples integer, ≥ 0How many page loads the values come from.
  • notes array of object optionalThe board's notes.
    • id string (uuid)The note's id.
    • siteId string or nullThe site the note is for; null when it is for every site on the board.
    • date string (date)The day the note is pinned to (YYYY-MM-DD).
    • text stringThe 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • referrers array of objectThe top 5 referrers.
    • name stringThe referrer host.
    • visitors integer, ≥ 0Visitors from this referrer.
    • share numberPercent of the site's visitors, 0–100.
  • countries array of objectThe top 5 countries.
    • name stringThe country.
    • visitors integer, ≥ 0Visitors from this country.
    • share numberPercent of the site's visitors, 0–100.
  • pages array of objectThe top 5 pages.
    • name stringThe page's path.
    • visitors integer, ≥ 0Visitors who saw this page.
    • share numberPercent 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).

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • deployments array of objectProduction deployments in the range, newest first (at most 20).
    • at string (date-time)When the deployment was made (ISO 8601).
    • message string or nullThe commit message; null when there is none.
    • branch string or nullThe git branch; null when there is none.
    • state stringVercel'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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • range stringThe 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).
  • lcpMs number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
  • inpMs number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
  • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
  • samples integer, ≥ 0How many page loads the values come from.
  • routes array of objectThe device's slowest routes by LCP.
    • route stringThe route, as the app names it (for example /blog/[slug]).
    • lcpMs numberThe route's Largest Contentful Paint at p75, in milliseconds.
    • samples integer, ≥ 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).

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A 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
  • site objectThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • range stringThe 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).
  • goal string or nullThe site's goal, a Vercel custom event; null when the site has no goal.
  • visitors integer, ≥ 0All the site's visitors in the range, tagged or not.
  • campaigns array of objectOne row per campaign and source.
    • campaign stringThe utm_campaign value. In platform mode, the ad platform.
    • source stringThe utm_source value. In platform mode, the referrer host.
    • medium stringThe utm_medium value. In platform mode, referrer.
    • visitors integer, ≥ 0Visitors from this campaign and source.
    • previousVisitors integer, ≥ 0Visitors from this campaign and source in the previous period.
    • pageviews integer, ≥ 0Page views from this campaign and source.
    • conversions integer, ≥ 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A site's Vercel project id, from GET /v1/boards/{id}/sites
utmpathstring: no control characters, 1–200 charactersThe 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
  • current object or nullThe row for this period, else the latest one; null when the campaign has no spend.
    • campaign stringThe campaign (its utm_campaign value).
    • platform "google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.
    • amount number, ≥ 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).
    • periodStart string: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).
    • repeatMonthly booleanWhether the amount repeats every month until it is changed.
  • history array of objectEvery row, newest first.
    • campaign stringThe campaign (its utm_campaign value).
    • platform "google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.
    • amount number, ≥ 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).
    • periodStart string: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).
    • repeatMonthly booleanWhether 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.

ParameterTypeDescription
idpathstring: letters, digits, _ and -, up to 64A site's Vercel project id, from GET /v1/boards/{id}/sites
utmpathstring: no control characters, 1–200 charactersThe utm_campaign value, URL-encoded

Request body (JSON)

  • amount number, ≥ 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).
  • periodStart string: 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.
  • repeatMonthly booleanWhether 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
  • current object or nullThe row for this period, else the latest one; null when the campaign has no spend.
    • campaign stringThe campaign (its utm_campaign value).
    • platform "google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.
    • amount number, ≥ 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).
    • periodStart string: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).
    • repeatMonthly booleanWhether the amount repeats every month until it is changed.
  • history array of objectEvery row, newest first.
    • campaign stringThe campaign (its utm_campaign value).
    • platform "google" | "meta" | "linkedin" | "tiktok" | "other"Where the money went: google, meta, linkedin, tiktok or other.
    • amount number, ≥ 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).
    • periodStart string: YYYY-MM-DDThe first day of the period (YYYY-MM-DD).
    • repeatMonthly booleanWhether 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.

ParameterTypeDescription
idpathstring, 1–100 charactersA board's id from GET /v1/boards, or its exact name (case-insensitive)
sitequery · optionalstring: letters, digits, _ and -, up to 64Only this site's notes (and the board-wide ones)
rangequery · optional"24h" | "7d" | "30d" or string: two dates, YYYY-MM-DD..YYYY-MM-DDOnly 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
  • board objectThe board.
    • id string (uuid)The board's id.
    • name stringThe board's name.
  • notes array of objectThe board's notes.
    • id string (uuid)The note's id.
    • boardId string (uuid)The board the note is on.
    • siteId string or nullThe site the note is for; null when it is for every site on the board.
    • date string (date)The day the note is pinned to (YYYY-MM-DD).
    • text stringThe 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.

ParameterTypeDescription
idpathstring, 1–100 charactersA board's id from GET /v1/boards, or its exact name (case-insensitive)

Request body (JSON)

  • date string (date)The day the note is pinned to (YYYY-MM-DD).
  • text string, 1–200 charactersThe note's text. It is trimmed and kept to its first 80 characters.
  • siteId string: 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
  • note objectThe note that was added.
    • id string (uuid)The note's id.
    • boardId string (uuid)The board the note is on.
    • siteId string or nullThe site the note is for; null when it is for every site on the board.
    • date string (date)The day the note is pinned to (YYYY-MM-DD).
    • text stringThe 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.

ParameterTypeDescription
idpathstring, 1–100 charactersA 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
  • board objectThe board.
    • id string (uuid)The board's id.
    • name stringThe board's name.
  • format "pdf" | "csv"pdf or csv.
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • url string (uri)The download link.
  • expiresAt string (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.

ParameterTypeDescription
idpathstring, 1–100 charactersA board's id from GET /v1/boards, or its exact name (case-insensitive)
rangequery · optionalstringThe 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
  • range stringThe period of the figures: 24h, 7d, 30d or two dates (YYYY-MM-DD..YYYY-MM-DD).
  • items array of objectThe board's items, ranked by visitors affected.
    • id stringThe 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.
    • projectId string or nullThe site's Vercel project id; null for a team project Lookout doesn't track yet.
    • domain stringThe site's production domain.
    • framework string or nullThe site's framework preset in Vercel (for example nextjs); null when it isn't known.
    • title stringWhat to fix.
    • detail stringThe numbers behind it.
    • why stringWhy it matters.
    • verify stringWhere the result shows once it is fixed.
    • impact integer, ≥ 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.
    • context objectThe data the item's prompt uses.
      • teamSlug string or null optionalThe site's Vercel team. The public API leaves it out.
      • grade object optionalThe site's Scorecard row, for a grade item.
        • grade "A" | "B" | "C" | "D"The grade, from A (best) to D.
        • factors array 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).
          • label stringThe factor's name as the dashboard shows it.
          • value stringThe 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.
          • bench stringWhat the value is measured against (for example vs previous week).
          • note stringA short note on the value.
          • bar number, ≥ 0, ≤ 1000–100: the length of the bar under the value.
        • vitals object or nullThe p75 Core Web Vitals behind the speed factor; null without Speed Insights.
          • lcp number or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
          • inp number or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
          • cls number or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • speed object optionalThe values behind a speed item.
        • device "all" | "mobile" | "desktop"all, mobile or desktop.
        • values objectCore Web Vitals at p75.
          • lcp number, ≥ 0 or nullLargest Contentful Paint at p75, in milliseconds; null without samples.
          • inp number, ≥ 0 or nullInteraction to Next Paint at p75, in milliseconds; null without samples.
          • cls number, ≥ 0 or nullCumulative Layout Shift at p75 (no unit); null without samples.
      • mainSite string or null optionalThe board's main site, by domain.
      • spend object optionalThe campaign behind a spend item.
        • campaign stringThe campaign (its utm_campaign value).
        • amount number, ≥ 0The campaign's spend in the range, in currency.
        • currency "USD" | "EUR" | "GBP" | "ILS"ILS, USD, EUR or GBP.
        • costPerConversion number, ≥ 0The campaign's cost per goal conversion, in currency.
        • median number, ≥ 0The median cost per conversion of the board's campaigns in the same currency.
    • status "open" | "snoozed" | "resolved"open, snoozed or resolved.
    • snoozedUntil number or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.
    • resolvedAt number or nullWhile resolved: when the item was resolved (epoch milliseconds); else null.
  • counts objectItems per status, before the status filter.
    • open integer, ≥ 0Open items.
    • snoozed integer, ≥ 0Snoozed items.
    • resolved integer, ≥ 0Resolved items.
  • resolvedThisMonth integer, ≥ 0Items resolved since the first of the month (UTC), on any board.
  • unavailable array 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.

ParameterTypeDescription
itemIdpathstring, 3–300 charactersA Fix list item's id (`kind:domain`) from GET /v1/boards/{id}/fixes

Request body (JSON)

  • boardId string, 1–64 charactersThe board whose Fix list holds the item. The note goes on the item's site there.
  • range string, 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
  • id stringThe item's id, kind:domain.
  • status "open" | "snoozed" | "resolved"open, snoozed or resolved.
  • snoozedUntil number or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.
  • resolvedAt number 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.

ParameterTypeDescription
itemIdpathstring, 3–300 charactersA 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
  • id stringThe item's id, kind:domain.
  • status "open" | "snoozed" | "resolved"open, snoozed or resolved.
  • snoozedUntil number or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.
  • resolvedAt number 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.

ParameterTypeDescription
itemIdpathstring, 3–300 charactersA 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
  • id stringThe item's id, kind:domain.
  • status "open" | "snoozed" | "resolved"open, snoozed or resolved.
  • snoozedUntil number or nullWhile snoozed: when the item comes back (epoch milliseconds); else null.
  • resolvedAt number 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
  • alerts array of objectThe workspace's alert rules.
    • id string (uuid)The alert rule's id.
    • board objectThe board the rule watches.
      • id string (uuid)The board's id.
      • name stringThe board's name.
    • metric stringvisitors, pageviews or pages_per_visit.
    • direction "drop" | "rise"drop or rise.
    • threshold integerThe change, in percent, that fires the alert.
    • enabled booleanWhether the rule is on.
    • lastFiredAt string (date-time) or nullWhen the rule last fired (ISO 8601); null when it never has.
  • recent array of objectWhat fired in the last 30 days, newest first.
    • at string (date-time)When it fired (ISO 8601).
    • text stringWhat the alert said.
    • board string 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)

  • question string, 1–300 charactersA question about the workspace's sites, in plain words
  • scope "board" | "workspace", default "workspace" optionalworkspace: every board, sites counted once; board: one board (needs board)
  • board string, 1–100 characters optionalFor scope board: the board's id or exact name
  • range "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
  • answer stringOne sentence answering the question, the key number in **bold** (Markdown).
  • points array of string, 0–3 itemsVisitors per hour or day, oldest first.
  • site object or nullThe site.
    • id stringThe site's Vercel project id.
    • domain stringThe site's production domain.
  • action string or nullA few words for a link to `site`, e.g. "Open the site"; null without a site.
  • chart object or nullA small bar list, only when the answer compares several sites or boards; null otherwise.
    • title stringWhat to fix.
    • rows array of object, 1–5 itemsOne row per graded landing page, best first.
      • label stringThe factor's name as the dashboard shows it.
      • value numberThe 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.
      • siteId string 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