Package Information
Documentation
n8n-nodes-hitsteps
This is an n8n community node package for Hitsteps web analytics. It reads
saved Hitsteps reports through the Hitsteps Reports API.
n8n is a fair-code licensed workflow
automation platform.
- Installation
- Credentials
- Nodes and operations
- Days and time zones
- Limits
- Output
- Errors
- Compatibility
- Development
Installation
Follow the community nodes installation guide
and install n8n-nodes-hitsteps.
Credentials
One credential = one saved report. To create it:
- In Hitsteps, open your website, go to Reports and save a Pages or Referrers report.
- Open the saved report, expand Reports API, choose an expiry (1, 7, 30 or 90 days) and click
Create API key. The key is shown once: copy it. - In n8n, create a Hitsteps Reports API credential:
- Report API Key: the key (
hsr2.…). - Account UTC Offset: the fixed offset of your Hitsteps account time zone (Account settings), for
example+02:00,-05:00or+05:30. - Base URL: leave
https://www.hitsteps.comunless Hitsteps support or your white-label dashboard
gives you another address.
- Report API Key: the key (
The credential test checks the key. It does not check the offset (see below).
Rotation. Keys expire, and editing the saved report invalidates its keys. When that happens the
node fails with "The Hitsteps report API key is not valid any more": create a new key in the saved report
and paste it into the credential. Revoke keys you no longer use in the report's Reports API section.
The key reads only that one report. It is not your website tracking code and cannot be used as a general
Hitsteps account key. Keep it secret.
Nodes and operations
Hitsteps (action)
Report → Get Data: returns the saved report's rows and totals for complete days.
- Date Range: Last Complete Day, Last 7 Complete Days, Last 30 Complete Days, or Custom (start and end
date,YYYY-MM-DD, end date before today). One request covers at most 31 days. - Output: One Item per Row (default), or Whole Report (one item with rows, totals, comparison and
warnings). - Options → Wait When Rate Limited (default on): when Hitsteps answers 429 or 503 with a
Retry-Afterof up to 120 seconds, wait and retry once (503: up to twice) instead of failing.
Items that ask for the same range in one run share one API call.
Hitsteps Trigger (polling)
New Completed Day: starts the workflow once per account-local day, when the saved report has data for
the day that just ended.
- Each event carries
event_id=<YYYY-MM-DD>:r<report revision>. - On activation it starts with the most recent complete day (no history backfill). After n8n was off, it
catches up at most 7 missed days, one per poll. - n8n's default Poll Times is every minute. That is fine: the trigger only calls Hitsteps when a new
day is due. While that day is still processing, it checks again at most every 15 minutes (plus random
jitter), and it honoursRetry-Afterafter a 429 or 503. - With One Item per Row, a day with no rows produces no execution. Use Whole Report if you want an
execution for every day, including days with no data. - Fetch Test Event reads the latest complete day without changing what the active trigger has
already emitted, and shows the API error if there is one.
Days and time zones
Hitsteps report days start at midnight in the account's fixed UTC offset, not in the n8n or browser
time zone. The nodes compute every request from the credential's Account UTC Offset, and never include
today, because only complete days are available.
A wrong offset makes every request look like "data not ready" (HTTP 422). If Get Data keeps returning
"Hitsteps has no complete data for these days yet", or the trigger never fires, compare the offset with
your Hitsteps account settings. The offset is fixed: it does not follow daylight-saving changes. If you
change the account time zone, update the credential.
Limits
Hitsteps limits each key to 6 requests per minute and 60 per hour, and each website to 240 requests
per hour across all keys. Results for the same report and days are cached for up to an hour, so polling
more often than every 15 minutes gains nothing. Do not create extra keys to get around the limits.
Other limits come from the saved report and your account: retained history (plan), source readiness,
query cost, and the saved report's row limit. The response has no pagination: if has_more is true, the
saved report's row limit cut the table. Do not treat a limited table as a complete export.
On most accounts the Reports API is available for saved Pages and Referrers reports.
Output
One Item per Row (Simplify on) gives one item per row:
{
"report_id": 42,
"report_revision": 3,
"dataset": "pages",
"period_start": "2026-11-05",
"period_end": "2026-11-05",
"timezone_offset": 7200,
"row_index": 0,
"dimension_1": "/pricing",
"dimension_1_field": "page.path",
"dimension_1_state": "set",
"page_views": "41",
"unique_visitors": "30"
}
- Metric values are kept exactly as Hitsteps sends them: decimal strings or
null. They are never
converted to numbers andnullis never turned into 0. Convert them yourself where needed. dimension_N_statekeepsmissing(no value) distinct fromempty(an explicitly empty value).- Turn Simplify off to get the original row object under
row. - Unique counts and ratios generally cannot be added across days to get an exact longer-period total:
request the longer range instead.
Whole Report gives one item with row_count, has_more, row_cap, warnings, metrics, totals,rows, comparison, comparison_rows, current and, for time-series reports, time_series_rows.
Errors
| Hitsteps answer | Node message | What to do |
|---|---|---|
401 unauthorized |
The Hitsteps report API key is not valid any more | Create a new key in the saved report (expired, revoked, or report edited). |
403 not_available |
This report is not available through the Reports API | Check the report's Reports API section in Hitsteps; shorten a very large range. |
404 not_found |
The Hitsteps Reports API was not found at this address | Check the credential's Base URL. |
422 report_unavailable |
Hitsteps has no complete data for these days yet | Wait if the days are recent; otherwise check the offset and your plan's history. |
422 custom_comparison_not_supported |
Reports with a custom comparison period cannot be read | Save the report with no / previous period / previous year comparison, then create a new key. |
422 report_calendar_changed |
The account time zone changed during the request | Update the offset and retry. |
429 rate_limited |
Hitsteps Reports API rate limit reached | Poll less often (the message includes Retry-After). |
503 temporarily_unavailable |
Hitsteps Reports API is temporarily busy | Retry later. |
The trigger fails only for configuration problems (401, 403, 404, 400). Days still processing, 429 and 503
are retried quietly on later polls.
Compatibility
Built with @n8n/node-cli 0.55 and tested with n8n 2.46. No run-time dependencies.
Development
npm install
npm run lint
npm test # builds, then runs the unit tests in test/
npm run dev # starts a local n8n with the nodes loaded