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