REST API endpoint

GET /v1/recap

Recap data, summary metrics, and top pages for presets or a custom date range.

Request

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25

Use this endpoint for historical reporting, top-page exports, custom date ranges, and search-filtered recap data.

Authentication

Requires an API key in the Authorization header: Authorization: Bearer nm_YOUR_KEY.

Query parameters

Name Type Required Description
site string required Tracker ID. The API key must have access to this tracker.
preset string optional Date preset. One of today, yesterday, last7, last14, last30, last90, this_month, last_month, custom. Default: last30.
start date optional Start date for preset=custom. Format: YYYY-MM-DD.
end date optional End date for preset=custom. Format: YYYY-MM-DD.
limit integer optional Maximum number of top pages to return. Values are clamped to 1-100. Default: 100.
q string optional Search term for top pages. Matches URL, title, or author. Alias: search.
search string optional Alias for q.

cURL example

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25"

Example response

{
  "site": "TRACKER_ID",
  "preset": "last30",
  "timezone": "Europe/Zurich",
  "range": {
    "from": "2026-05-28",
    "to": "2026-06-26",
    "label": "Last 30 Days",
    "days": 30
  },
  "limits": {
    "min_date": "2025-03-17",
    "max_date": "2026-06-26",
    "max_days": null
  },
  "search": {
    "query": ""
  },
  "daily": [
    {
      "date": "2026-06-25",
      "pageviews": 102400,
      "visits": 12800
    },
    {
      "date": "2026-06-26",
      "pageviews": 98450,
      "visits": 12130
    }
  ],
  "summary": {
    "total_pageviews": 3158127,
    "total_visits": 388450,
    "pages_per_visitor": 8.1
  },
  "top_pages": [
    {
      "rank": 1,
      "title": "Home page",
      "author": "",
      "pubdate": "",
      "url": "/",
      "url_full": "https://example-media.test/",
      "url_id": "5dc0a5883395e2a126e5239650d9268e",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example.jpg",
      "pageviews": 159280
    },
    {
      "rank": 2,
      "title": "Culture desk live notes",
      "author": "Alex Morgan",
      "pubdate": "2026-06-24",
      "url": "/culture/live-notes",
      "url_full": "https://example-media.test/culture/live-notes",
      "url_id": "b35c1a5f2fd0cbb7f3c13b853c2a9d2c",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example-2.jpg",
      "pageviews": 85632
    }
  ],
  "generated_at": "2026-06-26T12:30:00Z"
}

Response fields

Field Type Description
site string Tracker ID used for the request.
preset string Resolved preset used for the response.
timezone string Tracker timezone used to resolve local dates.
range object Resolved date range with from, to, label, and day count.
limits object Available history limits for the tracker.
search.query string Normalized search query used for top-page filtering.
daily[] array<object> Daily pageviews and visits for the resolved range.
summary.total_pageviews integer Total pageviews across the resolved range.
summary.total_visits integer Total visits across the resolved range.
summary.pages_per_visitor number Pageviews divided by visits, rounded to one decimal place.
top_pages[] array<object> Top pages sorted by pageviews.
top_pages[].rank integer Rank within the returned top-pages list.
top_pages[].title string Page title.
top_pages[].author string Author if available.
top_pages[].pubdate string Publication date if available.
top_pages[].url string Path or compact URL.
top_pages[].url_full string Absolute URL if available.
top_pages[].url_id string Stable URL identifier.
top_pages[].thumbnail string Thumbnail URL if available.
top_pages[].pageviews integer Pageviews for the resolved range.
generated_at string UTC timestamp for when the payload was generated.

Freshness and caching

Responses are microcached for 60 seconds per tracker, preset, custom range, limit, and normalized search term.

Errors

HTTP Code Description
400 site_required The site query parameter is missing.
401 missing_token The Authorization header is missing.
401 invalid_token The token is invalid or revoked.
403 site_not_authorized The API key has no access to this tracker.
429 rate_limit_exceeded The rate limit has been exceeded.
503 redis_unavailable The realtime backend is temporarily unavailable.
503 clickhouse_unavailable Historical data is temporarily unavailable.
500 encoding_failed The recap response could not be encoded. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}