Developer APIs and reporting connectors

What you will learn #

This chapter is for developers and advanced users who want to read Hitsteps analytics from their own software, or put Hitsteps numbers into external tools. After reading it you will be able to choose the right API for the job, find and protect the correct credential, run your first request, connect Grafana or Looker Studio, automate a daily pull with a tool such as n8n, and understand the limits and safety rules that apply. It covers the publicly documented APIs only: the Reports API, the Analytics (callback) API, the Grafana connector, the Looker Studio connector, and the account-gated White-label API.

Before you begin #

• You need a Hitsteps account with at least one website added and its tracking code installed. An API can only return data that the tracker has collected. If you have not installed the tracker, finish the installation guide first.
• Every Hitsteps website has a site API code (also called API key or tracking code). It is a 37-character code shown in the tracking code section of that website's settings. Many plugins, the desktop apps, the Grafana connector and the Looker Studio connector use this code. The Reports API uses a different, per-report key.
• The Reports API is available on every account and every plan, but only for saved Pages and Referrers reports. Other saved report types, such as Visitor sources, do not have a Reports API section yet; use the Analytics API for those.
• The Analytics API (the original website-level callback API) is available on every account and is documented as the safe first choice for a new server integration.
• Grafana and Looker Studio data access require a Hitsteps Business plan or higher, or an active trial. Below that level the endpoints answer HTTP 403 with plan_required. Check the current plans at https://www.hitsteps.com/features.php#price before building around paid access.
• The White-label API is for reseller accounts that already have white-label. Its reference lives inside the product and is not part of the public documentation.
• Report days follow your Hitsteps account's fixed UTC offset, not your browser or server timezone. You cannot override it in an API request.
• Read actions return aggregate data and do not expose visitor identities. No API call in this chapter changes your tracking setup unless the section says it is a write action.

Where to find it #

Credentials:

• Site API code and tracking code: sign in, open My websites, choose the website, open its Settings, then open the Tracking Code section. The full API code is 37 characters and is also shown on the public page Find your Hitsteps API key and tracking code. The same page explains the four setup steps: create or open the account, add the website, copy the API key, use the tracking code for manual installs.
• Reports API key: from the dashboard open /stats/<your-site-id>/reports/, open a saved Pages or Referrers report, expand the Reports API section (labelled Share and automate → Reports API in the quickstart), choose an expiry of 1, 7, 30 or 90 days, and click Create API key. Copy it immediately; it is shown once and cannot be recovered.

Documentation (all public, English):

• API index: https://www.hitsteps.com/api/ explains which API fits which job, how each authenticates, the limits, and where the full reference lives.
• Reports API guide and quickstart: https://www.hitsteps.com/api/reports-guide.html and https://www.hitsteps.com/api/reports-api-quickstart.html cover the request, the date rules, the JSON response, every error code, and cURL, Python, PHP and n8n examples.
• Analytics API reference: https://www.hitsteps.com/api/callback-doc renders the interactive reference; the machine-readable spec is at https://www.hitsteps.com/api/callback.oas2.
• Grafana setup: https://www.hitsteps.com/grafana-integration/ with the importable dashboard JSON at https://www.hitsteps.com/api/hitsteps-grafana-dashboard.json.
• Looker Studio connector: https://www.hitsteps.com/plugin/?type=lookerstudio.
• Where to find keys: https://www.hitsteps.com/support.php#api-key and https://www.hitsteps.com/plugin/?type=api.

Step by step #

A. Choose the right API

The two public APIs are not interchangeable: they use different credentials and different request formats. Pick by what you need to read, not by which page you landed on first.

B. Create your first Reports API key and request

1. Finish tracking: make sure the website has visits and its report data has finished processing. A brand new or quiet website shows no Reports API section until data has processed; the API would answer 422 report_unavailable in that window.
2. From the dashboard open /stats/<your-site-id>/reports/, open a saved Pages or Referrers report, and expand the Reports API section.
3. Choose an expiry (1, 7, 30 or 90 days) and click Create API key. Copy the key and store it in your server's secret manager. It is shown only once.
4. Save the report exactly as you want it. The API returns that saved report: its metrics, filters, sort and comparison setting. Editing the report afterwards invalidates the key.
5. Send a POST from your server. The endpoint is https://www.hitsteps.com/api/reports-v2.php, with no query fields; the credential goes in the Authorization header and the body is JSON. The quickstart provides a safe cURL form:

# Previous complete account-local day for an account at UTC+02:00.
OFFSET=7200   # your Hitsteps account's UTC offset in seconds
UNTIL=$(( ( $(date +%s) + OFFSET ) / 86400 * 86400 - OFFSET ))
FROM=$(( UNTIL - 86400 ))

printf 'Authorization: Bearer %s\n' "$HITSTEPS_REPORT_API_KEY" |
  curl --silent --show-error --include \
  'https://www.hitsteps.com/api/reports-v2.php' \
  -H @- \
  -H 'Content-Type: application/json' \
  --data "{\"from\":$FROM,\"until\":$UNTIL}"

The printf pipe keeps the key out of cURL's process arguments, and --include shows the status and headers, including Retry-After when rate-limited. HITSTEPS_REPORT_API_KEY must be set in your server environment.

6. Check the HTTP status before reading the body. An error response still carries a JSON body, so branch on the status, not on whether cURL connected.

7. Read the response under result.rows and result.totals. Empty rows mean the window found no matching data, which is a successful result, not a failure.

The request body has exactly two fields, both integer Unix timestamps in seconds:

Do not add sid, report_id, timezone, metrics, filters, SQL or definition JSON. Change the saved report in the dashboard instead, then create a replacement key.

C. Use the Analytics API

1. Get your site API code from the tracking code section of the website settings (or from https://www.hitsteps.com/plugin/?type=api).
2. Send POST requests to https://www.hitsteps.com/api/callback/<action> with the apicode form field, and website_id for most actions, as multipart/form-data.
3. The documented actions are:

• Account and website access: getAPI (obtain an account API code from account credentials), getAccountInfo, getListofTrackingWebsites, newTrackingAPI (add a website via API code) and newTrackingUser (add a website via login details).
• Visitor and traffic reports: getXdaysHits, dailyhits, hourlyhits, secondlyhits.
• Live analytics and report links: now (online and real-time activity) and shortlink (generate a direct link to a supported Hitsteps report).

4. Treat the write actions with care: newTrackingAPI and newTrackingUser add a website to the account, so only call them from code that is meant to create sites. Read actions are what most integrations need.
5. The OpenAPI 2.0 specification at https://www.hitsteps.com/api/callback.oas2 defines every request field and every response property and is the authoritative reference for this API.
6. Keep credentials server-side. The interactive reference does not accept credentials and does not make authenticated requests for you.

D. Connect Grafana with the Infinity data source

1. Confirm the plan: Grafana data access needs a Business plan or higher, or an active trial.
2. Install Grafana's Infinity data source. Grafana Cloud already includes it; self-managed Grafana installs the yesoreyeram-infinity-datasource plugin from the Grafana plugin catalog and restarts Grafana if asked.
3. Add an Infinity data source with URL https://www.hitsteps.com/api/grafana.php (or base URL https://www.hitsteps.com and request path /api/grafana.php).
4. On the Authentication tab choose Bearer Token and paste the full 37-character site API code into the token field. Keep it in Grafana's protected secret setting; never put it in a panel URL or a dashboard query.
5. In Allowed hosts enter https://www.hitsteps.com/ so Grafana permits requests to the connector.
6. Save and test the data source. Grafana should make requests from its server, not from a browser panel.
7. Download the ready-made dashboard JSON from https://www.hitsteps.com/api/hitsteps-grafana-dashboard.json, open Dashboards → Import, upload it, and select your Hitsteps Infinity data source when Grafana asks. The import file contains no API key.
8. Panels cover pageviews, visits, new visitors, bounce rate, sources, countries, search, technology, live visitors, top/entry/exit pages, referrers, downloads, outbound links, videos, goals, AI referrals, Segments and Funnels. The dashboard refreshes every five minutes by default.

Read-only report queries look like this:

{"action":"top_pages","days":30,"limit":10}

Supported report actions: query, live, top_pages, entry_pages, exit_pages, top_referrers, countries, search_engines, search_keywords, technology, downloads, outbound_links, actions, videos, goals, ai_referrals, triggers, funnels, funnel_steps, plus the diagnostic info action for connection tests. The endpoint supports hour, day, week and month grains and accepts Grafana epoch-millisecond values in from and to to follow a dashboard time range. Hourly queries are limited to 31 days and use the retained hourly rollup, which does not keep bounce, bot or social-source dimensions; use daily or coarser grains for those metrics. info returns the authorized website and metric names without returning the API key.

E. Connect Looker Studio (Data Studio)

1. Confirm the plan: Looker Studio reporting needs a Business plan or higher, or an active trial.
2. In Hitsteps, open My websites, choose the website, open its Settings, find the Tracking Code section and copy the full API code. It is 37 characters and Data Studio needs the whole code, not a short version.
3. In Data Studio choose Add data, then Hitsteps. Paste the API code into the key field.
4. Pick one of the 10 reports and set a start and end date. Traffic over time returns one row per day; the other reports list the top rows for the range, up to 50.
5. Add one data source per website. A second client site needs its own data source and its own API code.
6. If the numbers for the chosen dates are not ready, Data Studio shows an error; it does not fill the report with zeros. To load the latest numbers, an editor can choose Refresh data. Numbers from Hitsteps can be up to an hour old.

The 10 reports are: Traffic over time, Top pages, Entry pages, Exit pages, Referrers, Countries, Technology, AI referrals, Search engines and Goals.

F. Automate a daily pull with n8n

The Reports API quickstart documents a native n8n workflow that needs no Hitsteps plugin:

1. Add an HTTP Request node with a credential of type Header Auth (Name Authorization, Value Bearer <your key>). The key lives in the credential, not in the workflow.
2. Set the node to POST and the URL to https://www.hitsteps.com/api/reports-v2.php.
3. Add a small Code node that returns the previous complete account-local day in seconds, so you never hardcode timestamps.
4. Set the request body to {"from": {{ $json.from }}, "until": {{ $json.until }}} (n8n sets the JSON content type itself).
5. Read the report further down the workflow through {{ $json.result.rows }} and {{ $json.result.totals }}.

The same pattern works in any scheduler or HTTP client. Results for the same report and days are cached for up to an hour, so schedule runs at most every 15 minutes.

G. White-label API (resellers)

The White-label API provisions accounts and sites for reseller deployments. It is only for accounts that already have white-label; there is no public key signup. The reference is inside the product: sign in at https://www.hitsteps.com/api/whitelabel-doc to open it. The public OpenAPI 2.0 specification file is at https://www.hitsteps.com/api/whitelabel.oas2 and lists the documented actions such as obtaining an access token and provisioning sites. Treat this API as account-gated: linking the spec does not make the reference public.

H. Other product hooks (not general developer APIs)

• Form integration hooks. The WordPress plugin includes integrations for Contact Form 7, Gravity Forms, Ninja Forms and WooCommerce. Use the plugin’s supported setup and the form analytics chapter; these are not standalone developer APIs.
• Uptime notifications. Use the supported monitoring and alert-channel setup in the uptime chapter. No general-purpose customer webhook API is promised here.
• Feedback delivery and key pages. These are product features, not documented standalone developer APIs. Use the public Reports or Analytics API for supported retrieval; do not build integrations against undocumented dashboard or service endpoints.

Worked example #

Suppose a developer runs an online store called your-store.example. They saved a Pages report in Hitsteps that counts pageviews and unique visitors per page URL, with no comparison, and created a Reports API key with a 30-day expiry.

The request for the previous complete account-local day (their account is fixed at UTC+02:00) is the single POST shown in section 4B. A successful response has HTTP 200 and a body shaped like this (illustrative values, not a real customer's data):

{
  "ok": true,
  "version": 2,
  "report_id": 103,
  "report_revision": 1,
  "result": {
    "dataset": "pages",
    "timezone_offset": 7200,
    "current": {
      "from_date": "2026-11-05",
      "until_date": "2026-11-06",
      "days": 1
    },
    "rows": [
      {
        "dimension_1": {"id": "page.url", "value": "/pricing", "state": "set"},
        "pageviews": "120",
        "unique_visitors": "38"
      },
      {
        "dimension_1": {"id": "page.url", "value": "/help", "state": "set"},
        "pageviews": "34",
        "unique_visitors": "12"
      }
    ],
    "totals": {"pageviews": "154", "unique_visitors": "50"},
    "warnings": [],
    "has_more": false
  }
}

Expected result: the script prints the two rows and the totals, converts the string numbers before doing any maths, and stores the result privately. The day shown in current uses the account's local dates. If the report had no data on that day, rows would be an empty array with a still-successful status. If the developer asked for a window that includes today, starts before retained history, or spans more than 31 days, the API answers 422 report_unavailable instead. This example is illustrative; it does not describe a real customer account or a measured result.

Controls and metrics #

Problems and fixes #

• 401 unauthorized on the Reports API. Check the Bearer header, the key and its expiry. Saving changes to the report invalidates its keys; create a replacement key in that report. A website tracking code will not work here.
• 422 report_unavailable. The window includes today, starts before your retained history, spans more than 31 days, or the data is still processing. Shorten the range, use complete account-local days in your account's offset, or wait. Unavailable data is not an empty report.
• 400 invalid_request. Send only integer from and until (each between 1 and 2147483647, until > from). Check for milliseconds, extra fields, or invalid JSON.
• 403 not_available or plan_required. Open the report in the dashboard and check feature availability and plan access; for Grafana and Looker Studio, Business plan or higher (or an active trial) is required. Reduce the range if the report is too expensive. Do not keep retrying without a change.
• 429 rate_limited. Wait at least the Retry-After value in seconds and spread requests out. Reuse cached results instead of creating extra keys to bypass limits.
• 404 not_found on the Reports API. The endpoint may be disabled on the deployment. Confirm feature availability with support.
• A web browser shows an error when you open the endpoint. Use POST from your server, not a browser GET. Opening the endpoint in a browser is not a report request.
• Numbers look wrong or missing. Confirm the tracker collected data for the dates, use complete account-local days for your account's offset, and expect that recent completed days can still be processing. The current day is never served. A blank or waiting report is not zero traffic.
• Values come back as strings or null. That is the designed precision. Convert explicitly and never treat unavailable values as zero.
• Looker Studio shows an error instead of numbers. The numbers for those dates are not ready yet; the connector shows an error, not zeros. Use Refresh data for the latest numbers, which can be up to an hour old.
• Grafana panels are empty. Check the Infinity query: Bearer token in the data source (never in the panel), Allowed hosts set to https://www.hitsteps.com/, the data root selector, and a grain your plan and rollup support.
• I cannot create a Reports API key. The report type may not support it yet (use the Analytics API instead), or the website's report data has not finished processing. Check support if it stays missing after visits.

Access, privacy and limits #

• The Grafana connector returns aggregate analytics without visitor identities, individual Segment matches or Funnel events. Legacy account and website operations return account/website metadata; keep that information and its credentials private. Do not assume every endpoint or exported report has the same data scope.
• Keep credentials server-side. Never place a password, API code, report key, or visitor data in browser JavaScript, public repositories, URLs, screenshots, or support messages. The documentation pages never accept credentials and never make authenticated requests for you.
• Reports API keys expire after 1, 7, 30 or 90 days. Rotate them and revoke a lost key in the saved report's API section. Editing or deleting the report, or losing the owner's access, stops authorized reads.
• Grafana and Looker Studio data access require a Business plan or higher, or an active trial (current plan details at https://www.hitsteps.com/features.php#price). Below Business, the endpoints answer 403 plan_required. This chapter does not state exact prices; check the plan page.
• The Reports API answers 422 report_unavailable for windows that include today, start before retained history, or exceed the 31-day default range. The API cannot return expired history.
• Rate limits: Reports API 6 requests per minute and 60 per hour per key, and 240 per hour per website. Analytics API has no published quota; failed API-code attempts are throttled with HTTP 429 and Retry-After.
• Role and access depend on the API and credential. A Reports API key is bound to one saved report and revision. Grafana and Looker Studio reads select a website and enforce its access checks. The legacy API accepts owner and delegated-user credentials with different authority: an owner API code can access account-wide operations such as getListofTrackingWebsites, which can return other accessible websites and their API codes. Treat it as an account credential, not a one-website least-privilege key. Delegated access remains subject to the permitted websites and operation checks. Prefer a report-scoped key when only one saved report is needed.
• Write actions: newTrackingAPI and newTrackingUser in the Analytics API add a website to an account. Only call them from code meant to create sites, and protect the credentials that can do so.
• The API does not edit reports, create schedules, or email results. Scheduled dashboard CSV exports and email reports are separate product features (see the reports and exports chapter) and do not require an API key.
• Exact per-plan retention windows and any future limits are verified on the current plan page; this chapter lists only the limits stated in the current public documentation. Undocumented dashboard and service endpoints are not supported public developer APIs.

Related help #

• Hitsteps manual home
• Getting started and installation
• Dashboard, real-time and visitor reports
• Reports, exports and scheduled delivery
• Form analytics and abandonment
• Uptime monitoring and alerts
• Privacy, data controls and tracking exclusions
• CMS, website platforms and mobile apps
• API index and references: https://www.hitsteps.com/api/, https://www.hitsteps.com/api/reports-guide.html, https://www.hitsteps.com/api/reports-api-quickstart.html, https://www.hitsteps.com/api/callback-doc
• Grafana integration: https://www.hitsteps.com/grafana-integration/
• Looker Studio connector: https://www.hitsteps.com/plugin/?type=lookerstudio
• Find your API key and tracking code: https://www.hitsteps.com/plugin/?type=api and the API key FAQ at https://www.hitsteps.com/support.php#api-key
• AI assistant and AI integrations: https://www.hitsteps.com/ai-integration/
• Plans and features: https://www.hitsteps.com/features.php#price
• Frequently asked questions: https://www.hitsteps.com/support.php

• For account-specific access or setup questions, use the support contact path on https://www.hitsteps.com/contact.php or the support link inside the signed-in dashboard.

• All guide topics

• Frequently asked questions
• Contact support

Last checked #

Checked 8 November 2026 using product documentation and source, with public pages and safe sample screens where available. Account-specific access, provider controls and effective limits can differ; use the current message shown for your website. Examples are illustrative.