Visitors

The Visitors metric measures the number of unique individuals who have visited your site or app during a specific time period. It helps you understand audience size, behavior trends, and traffic growth.

Metric model

Name
metric
Type
string
Description
Always visitors for this metric.
Name
value
Type
integer
Description
Number of unique visitors during the current period.
Name
previous
Type
integer
Description
Visitor count from the previous period.
Name
change
Type
float
Description
Percentage change between the current and previous period.
Name
formattedValue
Type
string
Description
Display-friendly visitor count.
Name
formattedPrevious
Type
string
Description
Display-friendly previous visitor count.
Name
period.id
Type
string
Description
Time range identifier (e.g., 7d).
Name
period.name
Type
string
Description
Human-readable time period label.
Name
periodRange.current.start
Type
string
Description
ISO start timestamp of the current period.
Name
periodRange.current.end
Type
string
Description
ISO end timestamp of the current period.
Name
periodRange.previous.start
Type
string
Description
ISO start timestamp of the previous period.
Name
periodRange.previous.end
Type
string
Description
ISO end timestamp of the previous period.
Name
performance.duration
Type
float
Description
Time in milliseconds to compute the metric.
Name
performance.formatted
Type
string
Description
Human-friendly response time.

GET/api/metrics/visitors

Retrieve visitors metric

This endpoint returns the number of unique visitors during a specific period.

Optional query parameters

Name
period
Type
string
Description
The time period to query. Popular options:
- today
- yesterday
- 7d
- 30d
- this_month
View full list of supported periods →

Request

GET

/api/metrics/visitors

curl -G http://localhost:3000/api/metrics/visitors \
  -H "Authorization: Bearer {token}" \
  -d period=7d

Response

{
  "metric": "visitors",
  "value": 47668,
  "previous": 49953,
  "change": -4.57,
  "formattedValue": "47.668",
  "formattedPrevious": "49.953",
  "period": {
    "id": "7d",
    "name": "Last 7 days"
  },
  "periodRange": {
    "current": {
      "start": "2025-03-16T08:50:55.030Z",
      "end": "2025-03-23T08:50:55.029Z"
    },
    "previous": {
      "start": "2025-03-09T08:50:55.030Z",
      "end": "2025-03-16T08:50:55.029Z"
    }
  },
  "performance": {
    "duration": 881.10,
    "formatted": "881 ms"
  }
}

Use cases

Measure marketing reach and campaign traffic
Detect spikes, trends, and traffic drops
Compare visitor growth by segment, campaign, or device