Read API

Query your analytics data programmatically. The Read API gives access to your analytics, visitors, revenue, and traffic data via simple GET requests, and lets you create and edit saved funnels.

Overview

The Read API lets you pull analytics data into your own tools, dashboards, or scripts. Use it for:

Building custom dashboards and reports
Feeding data into AI assistants via MCP
Integrating analytics into internal tools
Automated reporting and alerting

Base URL: https://app.himetrica.com/api/v1

Project Discovery

Use GET /me to discover your project ID from your secret key. All other endpoints require the project ID in the URL.

bash

curl "https://app.himetrica.com/api/v1/me" \
  -H "X-API-Key: hm_sk_your_secret_key"

json

{
  "data": {
    "projectId": "abc123-...",
    "name": "My Project",
    "timezone": "America/New_York"
  }
}

Authentication

All endpoints require your secret key in the X-API-Key header. Secret keys start with hm_sk_.

Find your secret key in Project Settings under "Secret Key (Server API)".

Keep your secret key safe

Never expose the secret key in client-side code, public repositories, or browser-accessible files. Use environment variables on your server.

Rate Limiting

The Read API is limited to 100 requests per minute per secret key on the Starter plan. Higher plans can have higher ceilings. Single-visitor endpoints (/visitors/{visitorId} and its /events) have an additional ceiling of 10 requests per minute on all plans. For bulk visitor data, use the paginated /visitors list endpoint instead of fetching profiles one by one. The response headers are the source of truth for your actual limit:

Header	Description
`X-RateLimit-Limit`	Max requests per window for your plan
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Timestamp when the window resets

If you exceed the limit, you'll receive a 429 response with a Retry-After header.

Common Parameters

Most endpoints accept these query parameters:

Parameter	Type	Description
`startDate`	ISO 8601	Start of date range. Default: 7 days ago.
`endDate`	ISO 8601	End of date range. Default: now.

Summary

GET /projects/:projectId/summary

Weekly or monthly summary compared with the previous period of the same length: traffic, top sources, pages, countries and events, revenue, plus ranked highlights of what changed. Covers complete days only (through yesterday).

period (optional) — 7d or 30d. Default: 7d

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/summary?period=7d" \
  -H "X-API-Key: hm_sk_your_secret_key"

Analytics

GET /projects/:projectId/analytics

Overview stats: visitors, pageviews, sessions, bounce rate, avg duration, with automatic period-over-period comparison.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/analytics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

json

{
  "data": {
    "pageViews": 12450,
    "uniqueVisitors": 3210,
    "sessions": 4820,
    "bounceRate": 42.5,
    "avgDuration": 185,
    "topPages": [...],
    "topReferrers": [...],
    "topCountries": [...]
  }
}

GET /projects/:projectId/analytics/timeseries

Time series data points for charting trends.

granularity (optional) — hour, day, week, or month. Default: day

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/analytics/timeseries?startDate=2024-01-01&endDate=2024-01-07&granularity=day" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/analytics/realtime

Active visitors on your site right now.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/analytics/realtime" \
  -H "X-API-Key: hm_sk_your_secret_key"

Pages

GET /projects/:projectId/pages

Top pages ranked by views, with average duration, scroll depth, and interaction scores.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/pages?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/pages/insights

Entry and exit page analysis with bounce rates.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/pages/insights?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

Traffic Sources

GET /projects/:projectId/sources

Traffic source breakdown with sessions, visitors, and bounce rates.

groupBy (optional) — referrer, utmSource, utmMedium, or utmCampaign. Default: referrer

limit (optional) — Results per page. Default: 25

page (optional) — Page number. Default: 1

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/sources?groupBy=utmSource&limit=10" \
  -H "X-API-Key: hm_sk_your_secret_key"

Locations

GET /projects/:projectId/locations

Geographic breakdown of visitors.

groupBy (optional) — country or city. Default: country

country (optional) — Filter cities by country

limit / page (optional) — Pagination

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/locations?groupBy=country&limit=10" \
  -H "X-API-Key: hm_sk_your_secret_key"

Events

GET /projects/:projectId/events

Custom event analytics: total count, unique event names, and top events ranked by count.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/events?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/events/names

List all unique event names tracked in your project.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/events/names" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/events/timeseries

Event trends over time. Optionally filter by a specific event name.

eventName (optional) — Filter to a specific event

granularity (optional) — hour, day, week, or month

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/events/timeseries?eventName=signup&granularity=day" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/events/list

Individual event records with their properties (the payload), plus visitor and session info.

eventName (optional) — Exact name, or comma-separated for several

limit (optional) — 1-100. Default: 25

page (optional) — Page number. Default: 1

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/events/list?eventName=signup&limit=25" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/events/visitors

Visitors who fired an event, ranked by how many times they fired it in the range.

eventName (required) — The event name

limit (optional) — 1-100. Default: 20

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/events/visitors?eventName=signup&limit=20" \
  -H "X-API-Key: hm_sk_your_secret_key"

Revenue

GET /projects/:projectId/revenue

Revenue overview: MRR, total revenue, active subscriptions, churn rate, and trial metrics.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/revenue" \
  -H "X-API-Key: hm_sk_your_secret_key"

json

{
  "data": {
    "mrr": 4250.00,
    "mrrUsd": 4250.00,
    "totalRevenue": 51000.00,
    "activeSubscriptions": 142,
    "churnRate": 3.2,
    "currency": "USD"
  }
}

GET /projects/:projectId/revenue/timeseries

Daily revenue breakdown: total, new, and recurring revenue.

days (optional) — Days to look back. Default: 30

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/revenue/timeseries?days=30" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/revenue/top-customers

Top customers ranked by total revenue.

limit (optional) — Max customers. Default: 10

identifiedOnly (optional) — Only show identified customers. Default: false

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/revenue/top-customers?limit=5" \
  -H "X-API-Key: hm_sk_your_secret_key"

Channel ROI

GET /projects/:projectId/channels

ROI per channel: visitors, conversions, revenue, ad spend, CAC, LTV, and conversion rates.

groupBy (optional) — utmSource, utmMedium, or utmCampaign. Default: utmSource

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/channels?groupBy=utmSource&startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/channels/summary

Aggregated channel summary: total visitors, conversions, revenue, and overall CAC/LTV.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/channels/summary?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

Visitors

GET /projects/:projectId/visitors

Search and list visitors, most recently seen first.

search (optional) — Name, email or visitor ID

country (optional) — Country code, e.g. US

device (optional) — desktop, mobile or tablet

source (optional) — Traffic source / referrer

identifiedOnly (optional) — Only visitors with a name or email

filters (optional) — JSON with operator (AND/OR) and rules for advanced fields (city, os, utm*, visitedPage, metadata keys…)

sortBy (optional) — firstSeenAt, lastSeenAt, name or totalRevenueUsd. Default: lastSeenAt

sortOrder (optional) — ASC or DESC

limit (optional) — 1-100. Default: 20

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/visitors?country=US&identifiedOnly=true&limit=20" \
  -H "X-API-Key: hm_sk_your_secret_key"

POST /projects/:projectId/visitors/lookup

Match up to 100 of your app's users (by userId and/or email) to Himetrica visitors in one call, with first-touch attribution. Built for admin tables. It is a read: POST only keeps emails out of the URL.

bash

curl -X POST "https://app.himetrica.com/api/v1/projects/{projectId}/visitors/lookup" \
  -H "X-API-Key: hm_sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "users": [{ "userId": "user_123" }, { "email": "[email protected]" }] }'

GET /projects/:projectId/visitors/:visitorId

One visitor's profile. The id can be the visitor row id, your app's userId, an email, or the tracker visitorId.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/visitors/[email protected]" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/visitors/:visitorId/events

Events fired by one visitor, with full properties.

eventName (optional) — Exact event name

limit (optional) — 1-100. Default: 20

page (optional) — Page number. Default: 1

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/visitors/[email protected]/events?limit=20" \
  -H "X-API-Key: hm_sk_your_secret_key"

Ideal Customer Profile

GET /projects/:projectId/icp

Who your best customers are (countries, devices, revenue), how they behave, the AI-written insights about them, and the top-scoring lookalike visitors not yet converted. Requires customers marked in the dashboard's ICP page.

limit (optional) — Lookalike visitors to return, 1-50. Default: 10

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/icp?limit=10" \
  -H "X-API-Key: hm_sk_your_secret_key"

Funnels

Saved funnels, the same ones on the dashboard's Funnels page. These are the only endpoints that write: POST creates a funnel and PATCH edits one. Funnels can't be deleted through the API.

Funnel fields

name — Up to 120 characters

steps — 1 to 20 steps, in order. Each is { type, value, label? }, where type is page (exact path), page_contains (path contains value), event (custom event name), entry / exit (the visit started / ended on this path) or referrer (referrer domain)

mode — session (all steps in one visit) or user (the same visitor across visits). Default: session

conversionWindow — Max seconds between the first and the last step, up to 365 days. null = no limit

metadataFilters — Up to 10 { key, value } pairs; only visitors whose identify metadata matches are counted

GET /projects/:projectId/funnels

Saved funnels, most recently edited first, each with its dashboard link.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/funnels" \
  -H "X-API-Key: hm_sk_your_secret_key"

GET /projects/:projectId/funnels/:funnelId

One funnel plus its conversion over the date range: how many reached each step, conversion and drop-off per step.

bash

curl "https://app.himetrica.com/api/v1/projects/{projectId}/funnels/{funnelId}?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-API-Key: hm_sk_your_secret_key"

json

{
  "data": {
    "id": "6f1c...",
    "name": "Pricing to signup",
    "steps": [
      { "type": "page", "value": "/pricing", "label": "Saw pricing" },
      { "type": "event", "value": "signup", "label": "Signed up" }
    ],
    "mode": "session",
    "conversionWindow": null,
    "metadataFilters": [],
    "dashboardUrl": "https://www.himetrica.com/dashboard/acme/abc123/funnels/6f1c...",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-01-31T00:00:00.000Z",
    "analysis": {
      "totalSessions": 4820,
      "steps": [
        { "step": { "type": "page", "value": "/pricing" }, "count": 1210, "percentage": 100, "dropoff": 0, "dropoffPercentage": 0 },
        { "step": { "type": "event", "value": "signup" }, "count": 182, "percentage": 15.04, "dropoff": 1028, "dropoffPercentage": 84.96 }
      ]
    }
  }
}

POST /projects/:projectId/funnels

Create a funnel. Returns it with 201. A project can have up to 100 funnels.

bash

curl -X POST "https://app.himetrica.com/api/v1/projects/{projectId}/funnels" \
  -H "X-API-Key: hm_sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing to signup",
    "steps": [
      { "type": "page", "value": "/pricing", "label": "Saw pricing" },
      { "type": "event", "value": "signup", "label": "Signed up" }
    ],
    "mode": "user",
    "conversionWindow": 604800
  }'

PATCH /projects/:projectId/funnels/:funnelId

Edit a funnel. Only the fields sent change; steps, when sent, replaces the whole list.

bash

curl -X PATCH "https://app.himetrica.com/api/v1/projects/{projectId}/funnels/{funnelId}" \
  -H "X-API-Key: hm_sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pricing to paid", "conversionWindow": null }'

Error Handling

Errors return a JSON object with error and code fields:

json

{
  "error": "Invalid API key",
  "code": "INVALID_KEY"
}

Status	Code	Description
401	`AUTH_REQUIRED`	Missing X-API-Key header
401	`INVALID_KEY`	Secret key not found or project inactive
403	`PROJECT_MISMATCH`	API key doesn't belong to this project
405	`METHOD_NOT_ALLOWED`	Method not supported on this endpoint (only GET, plus the visitor lookup and funnel writes)
429	—	Rate limit exceeded, check `Retry-After`
503	`SERVICE_UNAVAILABLE`	Temporary service outage

Example: Node.js

typescript

const API_URL = "https://app.himetrica.com/api/v1";
const SECRET_KEY = process.env.HIMETRICA_SECRET_KEY;

// First, discover your project ID
const me = await fetch(`${API_URL}/me`, {
  headers: { "X-API-Key": SECRET_KEY },
}).then(r => r.json());

const PROJECT_ID = me.data.projectId;

// Then query your analytics
const analytics = await fetch(
  `${API_URL}/projects/${PROJECT_ID}/analytics?startDate=2024-01-01&endDate=2024-01-31`,
  { headers: { "X-API-Key": SECRET_KEY } }
).then(r => r.json());

console.log(analytics.data);

MCP Integration

Want to query your analytics from Claude or other AI assistants? Check out the MCP Server guide — it uses this API under the hood.