Overview

Return visitor, session and page-view totals, bounce and consent rates, top pages, referrers, locations, and a time series.

curl -X GET "https://api.beacon.hard.al/v1/reports/overview?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&path=example_string&channel=example_string&source=example_string&device=example_string&os=example_string&country=USA&city=New%20York&eventName=John%20Doe" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests
import json

url = "https://api.beacon.hard.al/v1/reports/overview?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&path=example_string&channel=example_string&source=example_string&device=example_string&os=example_string&country=USA&city=New%20York&eventName=John%20Doe"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://api.beacon.hard.al/v1/reports/overview?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&path=example_string&channel=example_string&source=example_string&device=example_string&os=example_string&country=USA&city=New%20York&eventName=John%20Doe", {
  method: "GET",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
)

func main() {

    req, err := http.NewRequest("GET", "https://api.beacon.hard.al/v1/reports/overview?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&path=example_string&channel=example_string&source=example_string&device=example_string&os=example_string&country=USA&city=New%20York&eventName=John%20Doe", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.beacon.hard.al/v1/reports/overview?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&path=example_string&channel=example_string&source=example_string&device=example_string&os=example_string&country=USA&city=New%20York&eventName=John%20Doe')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

{
  "success": true,
  "data": {
    "range": {
      "startDate": "2026-10-01",
      "endDate": "2026-10-07",
      "timezone": "Europe/Istanbul"
    },
    "previousRange": {
      "startDate": "2026-09-24",
      "endDate": "2026-09-30",
      "timezone": "Europe/Istanbul"
    },
    "scoreCards": {
      "consentedVisitors": 1840,
      "sessions": 4200,
      "pageViews": 9660,
      "bounceRate": 0.42,
      "sessionDuration": 96,
      "totalEvents": 25200,
      "consentRate": 0.55
    },
    "previousScoreCards": {
      "consentedVisitors": 1600,
      "sessions": 3750,
      "pageViews": 8250,
      "bounceRate": 0.45,
      "sessionDuration": 88,
      "totalEvents": 21750,
      "consentRate": 0.52
    },
    "timeSeries": [
      {
        "date": "2026-10-01",
        "pageViews": 1196,
        "consentedVisitors": 228,
        "sessions": 520,
        "consentedSessions": 286,
        "unconsentedSessions": 234
      },
      {
        "date": "2026-10-02",
        "pageViews": 1380,
        "consentedVisitors": 263,
        "sessions": 600,
        "consentedSessions": 330,
        "unconsentedSessions": 270
      },
      {
        "date": "2026-10-03",
        "pageViews": 1472,
        "consentedVisitors": 280,
        "sessions": 640,
        "consentedSessions": 352,
        "unconsentedSessions": 288
      },
      {
        "date": "2026-10-04",
        "pageViews": 1380,
        "consentedVisitors": 263,
        "sessions": 600,
        "consentedSessions": 330,
        "unconsentedSessions": 270
      },
      {
        "date": "2026-10-05",
        "pageViews": 1518,
        "consentedVisitors": 289,
        "sessions": 660,
        "consentedSessions": 363,
        "unconsentedSessions": 297
      },
      {
        "date": "2026-10-06",
        "pageViews": 1518,
        "consentedVisitors": 289,
        "sessions": 660,
        "consentedSessions": 363,
        "unconsentedSessions": 297
      },
      {
        "date": "2026-10-07",
        "pageViews": 1196,
        "consentedVisitors": 228,
        "sessions": 520,
        "consentedSessions": 286,
        "unconsentedSessions": 234
      }
    ],
    "sessionBreakdowns": {
      "browsers": [
        {
          "value": "Chrome",
          "sessions": 2520
        },
        {
          "value": "Safari",
          "sessions": 1050
        },
        {
          "value": "Edge",
          "sessions": 336
        },
        {
          "value": "Firefox",
          "sessions": 294
        }
      ],
      "operatingSystems": [
        {
          "value": "Windows",
          "sessions": 1596
        },
        {
          "value": "macOS",
          "sessions": 1134
        },
        {
          "value": "iOS",
          "sessions": 924
        },
        {
          "value": "Android",
          "sessions": 546
        }
      ],
      "devices": [
        {
          "value": "desktop",
          "sessions": 2730
        },
        {
          "value": "mobile",
          "sessions": 1386
        },
        {
          "value": "tablet",
          "sessions": 84
        }
      ]
    },
    "acquisitionBreakdowns": {
      "channels": [
        {
          "value": "Direct",
          "sessions": 1680
        },
        {
          "value": "OrganicSearch",
          "sessions": 1260
        },
        {
          "value": "PaidSearch",
          "sessions": 630
        },
        {
          "value": "Referral",
          "sessions": 420
        },
        {
          "value": "OrganicSocial",
          "sessions": 210
        }
      ],
      "sources": [
        {
          "value": "google",
          "sessions": 1890
        },
        {
          "value": "direct",
          "sessions": 1680
        },
        {
          "value": "partner.example",
          "sessions": 420
        },
        {
          "value": "linkedin",
          "sessions": 210
        }
      ]
    },
    "pages": [
      {
        "pageTitle": "Home",
        "pagePath": "/",
        "consentedVisitors": 820,
        "sessions": 1890
      },
      {
        "pageTitle": "Pricing",
        "pagePath": "/pricing",
        "consentedVisitors": 410,
        "sessions": 940
      },
      {
        "pageTitle": "Product tour",
        "pagePath": "/product",
        "consentedVisitors": 330,
        "sessions": 760
      },
      {
        "pageTitle": "Blog",
        "pagePath": "/blog",
        "consentedVisitors": 280,
        "sessions": 610
      }
    ],
    "locations": {
      "countries": [
        {
          "countryCode": "TR",
          "consentedVisitors": 1010,
          "sessions": 2310
        },
        {
          "countryCode": "US",
          "consentedVisitors": 460,
          "sessions": 1050
        },
        {
          "countryCode": "DE",
          "consentedVisitors": 220,
          "sessions": 504
        },
        {
          "countryCode": "GB",
          "consentedVisitors": 150,
          "sessions": 336
        }
      ],
      "cities": [
        {
          "countryCode": "TR",
          "city": "Istanbul",
          "consentedVisitors": 610,
          "sessions": 1390
        },
        {
          "countryCode": "TR",
          "city": "Ankara",
          "consentedVisitors": 240,
          "sessions": 550
        },
        {
          "countryCode": "US",
          "city": "New York",
          "consentedVisitors": 190,
          "sessions": 430
        },
        {
          "countryCode": "DE",
          "city": "Berlin",
          "consentedVisitors": 120,
          "sessions": 270
        }
      ]
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-required",
    "message": "tenant-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "validation-error",
    "message": "Validation failed for 'timeframe': timeframe must be one of: today, yesterday, last7days, last30days, custom",
    "details": {
      "field": "timeframe",
      "message": "timeframe must be one of: today, yesterday, last7days, last30days, custom"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "bearer-required",
    "message": "bearer-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "invalid-credential",
    "message": "invalid-credential"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-revoked",
    "message": "credential-revoked"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-expired",
    "message": "credential-expired"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-granted",
    "message": "tenant-not-granted",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "source-does-not-belong-to-tenant",
    "message": "source-does-not-belong-to-tenant"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "insufficient-scope",
    "message": "insufficient-scope",
    "details": {
      "required": "reports:read"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-found",
    "message": "tenant-not-found",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "source-not-found",
    "message": "source-not-found",
    "details": {
      "sourceId": "7b0e5a54-1d43-4c8e-8d2f-5a9c3e6b1f27"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "rate-limited",
    "message": "rate-limited",
    "details": {
      "retryAfterSeconds": 30
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/overview",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

GET

/v1/reports/overview

GET

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

OAuth access token (token exchange) or organization API key.

query

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

Format: uuid

query

sourceIdstring

UUID of one source of the tenant. Omit it to include every source of the tenant.

Format: uuid

query

timeframestring

Reporting period. The presets today, yesterday, last7days and last30days cover whole calendar days ending today in the request timezone; last7days is today and the six days before it. Use custom together with startDate and endDate. Defaults to today.

query

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

query

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

query

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

Min length: 1 • Max length: 100

query

intervalstring

Bucket size of timeSeries: minute, hour, day, week or month. Defaults to hour; send day for periods longer than a day.

query

pathstring

Only count traffic on these page paths, for example /pricing. Exact match. Separate several values with commas.

query

channelstring

Only count traffic from these channels. acquisitionBreakdowns matches the channel name, for example OrganicSearch; the other sections match the utm_medium of the events. Exact match. Separate several values with commas.

query

sourcestring

Only count traffic from these traffic sources, for example google. acquisitionBreakdowns matches the session source; the other sections match the utm_source of the events. This is not sourceId. Exact match. Separate several values with commas.

query

devicestring

Only count traffic from these device types, for example desktop or mobile. Exact match. Separate several values with commas.

query

osstring

Only count traffic from these operating systems, for example iOS. Exact match. Separate several values with commas.

query

countrystring

Only count traffic from these countries, as two-letter codes such as TR. Exact match. Separate several values with commas.

query

citystring

Only count traffic from these cities. Exact match. Separate several values with commas.

query

eventNamestring

Only count events with these names. Exact match. Separate several values with commas.

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. OAuth access token (token exchange) or organization API key.

Query Parameters

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

sourceIdstring

UUID of one source of the tenant. Omit it to include every source of the tenant.

timeframestring

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

intervalstring

Bucket size of timeSeries: minute, hour, day, week or month. Defaults to hour; send day for periods longer than a day.

pathstring

Only count traffic on these page paths, for example /pricing. Exact match. Separate several values with commas.

channelstring

sourcestring

devicestring

Only count traffic from these device types, for example desktop or mobile. Exact match. Separate several values with commas.

osstring

Only count traffic from these operating systems, for example iOS. Exact match. Separate several values with commas.

countrystring

Only count traffic from these countries, as two-letter codes such as TR. Exact match. Separate several values with commas.

citystring

Only count traffic from these cities. Exact match. Separate several values with commas.

eventNamestring

Only count events with these names. Exact match. Separate several values with commas.

Responses

successboolean

Required

Allowed values:true

dataobject

Required

timestampstring

Required

pathstring

Required

requestIdstring

Required

Was this page helpful?