Read API

Query your analytics data programmatically. The Read API provides read-only access to all your analytics, revenue, and traffic data via simple GET requests.

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. Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Max requests per window (100)
`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.
`timezone`	IANA string	Timezone for date calculations. Default: project timezone or UTC.

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"

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"

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`	Only GET requests are allowed
429	—	Rate limit exceeded (100 req/min)
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.