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 Recap when your integration needs to look back: historical reporting, top-page exports, custom date ranges, or search-filtered results.

Try in API Playground

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, all_time, 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 top pages per response, including paginated responses. 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.
offset integer optional Start pagination with offset=0. Integer from 0 to 2000. Later pages require snapshot. Without offset or snapshot, the existing response remains unchanged.
snapshot string optional Use pagination.snapshot_id from the first response. Repeat the original site, preset, start, end and search parameters. The page size may change. Omit snapshot to start a new traversal.

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"
}

Pagination

Add offset=0 to opt into pagination. Each response contains at most 100 articles; the snapshot contains at most 2000. Without offset or snapshot, the existing response format and limit remain unchanged.

For each next page, send pagination.next_offset as offset and pagination.snapshot_id as snapshot. Repeat the original site, preset, start, end and search parameters, including custom dates. Stop when next_offset is null. An offset at or beyond the available count returns an empty top_pages array.

Article order, pageviews, daily values, summary and generated_at stay fixed across pages, including ranges containing today. Summary metrics cover the full selected range; pagination.total only counts articles in the capped snapshot. Every request still requires valid authorization and counts toward the tracker rate limit.

Snapshots expire after 10 minutes without renewal on reads. On HTTP 410, discard the partial traversal and restart with offset=0 without snapshot. The examples below show the first request, a continuation, and the additional pagination object.

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=0
GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=100&snapshot=0123456789abcdef0123456789abcdef0123456789abcdef
{
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2000,
    "max_results": 2000,
    "has_more": true,
    "next_offset": 100,
    "snapshot_id": "0123456789abcdef0123456789abcdef0123456789abcdef",
    "expires_at": "2026-06-26T12:40: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 in the complete snapshot when paginating; ranks continue across pages.
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.
pagination object Present only in pagination mode. At most 2000 articles are available across all pages.
pagination.limit integer Effective page size, from 1 to 100.
pagination.offset integer Zero-based position of the requested page.
pagination.total integer Number of articles in this snapshot, capped at 2000. This is not the uncapped number of matching URLs.
pagination.max_results integer Maximum articles per snapshot: 2000.
pagination.has_more boolean Whether another page is available within this snapshot.
pagination.next_offset integer|null Pass this value as offset for the next page. Null means the end has been reached.
pagination.snapshot_id string Opaque ID for subsequent requests using the snapshot parameter. Bound to the authenticated user and tracker.
pagination.expires_at string Fixed expiry in UTC, 10 minutes after storage. Reading pages does not extend it.

Freshness and caching

Requests without pagination use the existing 60-second microcache and historical fallback. Pagination stores an immutable snapshot in the local Stats Redis for 600 seconds, with automatic expiry and no sliding renewal. Identical starts by the same user within 60 seconds can reuse a snapshot, so use expires_at as the deadline. Continuations never rebuild the data or use a different snapshot as fallback.

Errors

HTTP Code Description
400 site_required The required site 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.
400 invalid_pagination Pagination query parameters must be scalar values.
400 invalid_offset Offset must be an integer from 0 to 2000.
400 invalid_snapshot Snapshot ID has an invalid format.
400 snapshot_required Offsets greater than zero require a snapshot ID. Start with offset=0.
400 snapshot_mismatch The preset, dates or search differ from the original request.
410 snapshot_expired Snapshot expired or is no longer available in this user/tracker context. Restart with offset=0 and without snapshot.
503 snapshot_storage_unavailable Snapshot storage cannot be read or written. Retry; an existing snapshot ID must remain unchanged.
503 recap_unavailable A complete new snapshot cannot currently be built. Retry shortly. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}