REST API endpoint

GET /v1/sources-history

Traffic mix over time: average concurrent readers per source category for the last hour, 24 hours, today, yesterday, 7 days, or a custom date range.

Request

History available since 16 November 2026

Source history has been recorded since 16 November 2026 and grows every day. Recording started at around 16:00 UTC, so 16 November contains only the evening hours and its daily value is not comparable with full days. If a range reaches back before 16 November 2026, from is moved to that date and the response contains a notice; a range that ends before that date returns no points. Earlier times are never reported as zero.

GET https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today

Use this endpoint to see how the traffic mix developed over time, for example when Google Discover traffic started or whether organic search is weaker than yesterday. Each point contains the average number of concurrent readers per source category at that time. Values are not visits or pageviews and must not be added up over time; use /v1/recap or /v1/overview for totals. For individual live sources such as a specific social network or newsletter, use /v1/sources.

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.
range string optional Time range. One of 1h (last 60 minutes, 2-minute points), 24h (rolling 24 hours, 10-minute points), today and yesterday (calendar day in the tracker time zone, 10-minute points), 7d (today and the previous 6 days, hourly points), or custom (requires start and end). Default: today.
start string optional First calendar day of a custom range in the format YYYY-MM-DD, in the tracker time zone. Required with range=custom and not allowed with other ranges. Must not be in the future.
end string optional Last calendar day of a custom range in the format YYYY-MM-DD, inclusive. Required with range=custom. A range may cover at most 366 days; an end date in the future is cut to the current time. The resolution follows the days with recorded data: up to 2 days 10-minute points, up to 31 days hourly points, longer ranges daily points.

cURL example

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today"

Example response

{
  "site": "TRACKER_ID",
  "range": "today",
  "start": null,
  "end": null,
  "timezone": "Europe/Zurich",
  "unit": "avg_concurrent_readers",
  "resolution_minutes": 10,
  "from": "2026-11-18T00:00:00+01:00",
  "to": "2026-11-18T09:24:00+01:00",
  "data_available_from": "2026-11-16",
  "notice": null,
  "updated_at": "2026-11-18T08:24:30+00:00",
  "stale": false,
  "categories": [
    "organic",
    "discover",
    "direct",
    "internal",
    "social",
    "referral",
    "email",
    "ai"
  ],
  "points": [
    {
      "t": "2026-11-18T09:00:00+01:00",
      "total": 412.6,
      "unattributed": 6.4,
      "values": {
        "organic": 96.2,
        "discover": 131.5,
        "direct": 88.1,
        "internal": 41.3,
        "social": 27.9,
        "referral": 12.6,
        "email": 7.2,
        "ai": 1.4
      }
    },
    {
      "t": "2026-11-18T09:10:00+01:00",
      "total": 428.3,
      "unattributed": 5.9,
      "values": {
        "organic": 98.7,
        "discover": 144,
        "direct": 86.4,
        "internal": 42.8,
        "social": 28.5,
        "referral": 12.1,
        "email": 8.6,
        "ai": 1.3
      }
    }
  ]
}

Response fields

Field Type Description
site string Tracker ID used for the request.
range string Requested time range.
start string|null Requested first day for range=custom, otherwise null.
end string|null Requested last day for range=custom, otherwise null.
timezone string Tracker time zone used for calendar days and timestamps, for example Europe/Zurich.
unit string Always avg_concurrent_readers: average number of readers active at the same time within each point.
resolution_minutes integer Length of each point in minutes: 2, 10, 60, or 1440 (one calendar day).
from string Start of the range as ISO 8601 timestamp with the tracker time zone offset. If the requested range starts before data_available_from, this is moved to that date.
to string End of the range as ISO 8601 timestamp with offset. For ongoing ranges, this is the current time.
data_available_from string First day with recorded source history: 2026-11-16. Recording started at around 16:00 UTC that day, so it is an incomplete day.
notice object|null Set if the range reaches before data_available_from, otherwise null. The request still succeeds with HTTP 200.
notice.code string partial_history: the range starts earlier, so from was moved and earlier days have no points. no_history: the range ends before data recording started, so points is empty.
notice.message string Short English explanation for logs or display.
updated_at string UTC timestamp for when the history was calculated.
stale boolean true if this is the last valid result because the history backend is briefly unavailable.
categories[] array<string> All source categories in fixed order: organic, discover, direct, internal, social, referral, email, ai. The list is always complete, even if a category had no readers.
points[] array<object> Points in chronological order. Times without collected data are omitted, so gaps are possible.
points[].t string Start of the point as ISO 8601 timestamp with offset. When clocks go back at the end of daylight saving time, the repeated hour is combined into one point.
points[].total number Average concurrent readers across all sources, rounded to one decimal place.
points[].unattributed number Readers in total without an assignable category. Currently this is usually 0, so the categories add up to total. Always calculate shares as category value divided by total, so the result stays correct if unassigned readers occur.
points[].values object Average concurrent readers per category, keyed by the names in categories. Categories without readers are 0.

Freshness and caching

Responses are cached per tracker and range: 60 seconds for 1h, 24h and today, 5 minutes for 7d, and 30 minutes for yesterday. Custom ranges are cached per start and end date: 30 minutes if the range has ended, otherwise 60 seconds with 10-minute points and 5 minutes with hourly or daily points. If the history backend is briefly unavailable, the last valid result is returned with stale: true and a Warning header. The response also includes X-NowMetrix-Microcache with HIT, MISS, or STALE.

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.
400 invalid_range The range parameter must be 1h, 24h, today, yesterday, 7d, or custom.
400 invalid_date_range start or end is missing or not a valid YYYY-MM-DD date, start is after end or in the future, the range covers more than 366 days, or start and end were sent without range=custom.
503 source_history_unavailable The source history is temporarily unavailable and no recent result is cached. Retry after the Retry-After header.
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}