Hierarchical traffic time series for a scope

curl --request GET \
  --url https://www.closient.com/analytics/api/v1/traffic \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/analytics/api/v1/traffic', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/analytics/api/v1/traffic",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/analytics/api/v1/traffic"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/analytics/api/v1/traffic")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "scope": {
    "name": "<string>",
    "id": "<string>"
  },
  "breadcrumb": [
    {
      "name": "<string>",
      "id": "<string>"
    }
  ],
  "period": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "total": 1,
  "previous_period_total": 1,
  "series": [
    {
      "id": "<string>",
      "name": "<string>",
      "data": [
        123
      ],
      "total": 1,
      "has_children": true
    }
  ],
  "timestamps": [
    "2023-12-25"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Traffic

Hierarchical traffic time series for a scope

Returns a stacked time series suitable for an ECharts stacked area / bar chart, plus a breadcrumb describing the drill-down path. The shape mirrors the Customer Analytics Dashboard contract (C-1045).

Scopes form a hierarchy organization → brand → product (optional) → trade_item; the response’s series[*].type discriminator tells the frontend whether clicking a stacked segment should drill into another product, an ungrouped trade item, or stop.

Data comes from the pre-aggregated ScanDailySummary table — no raw event scans are queried at request time. Today’s partial day is excluded; pre-aggregation runs nightly.

Caller must be a member of organization_id or a 404 is returned. scope_id (when supplied) must belong to that organization or a 404 is returned.

GET

analytics

api

traffic

Hierarchical traffic time series for a scope

curl --request GET \
  --url https://www.closient.com/analytics/api/v1/traffic \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/analytics/api/v1/traffic', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/analytics/api/v1/traffic",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/analytics/api/v1/traffic"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/analytics/api/v1/traffic")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "scope": {
    "name": "<string>",
    "id": "<string>"
  },
  "breadcrumb": [
    {
      "name": "<string>",
      "id": "<string>"
    }
  ],
  "period": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "total": 1,
  "previous_period_total": 1,
  "series": [
    {
      "id": "<string>",
      "name": "<string>",
      "data": [
        123
      ],
      "total": 1,
      "has_children": true
    }
  ],
  "timestamps": [
    "2023-12-25"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Authorizations

X-API-Key

string

header

required

Query Parameters

organization_id

string<shortuuid>

required

UUID of the organization to query (caller must be a member).

Required string length: 22

Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

scope_type

enum<string>

default:organization

Hierarchy level being viewed. Defaults to organization (the top-level entry view).

Available options:

organization,

brand,

product,

trade_item

scope_id

string<shortuuid>

UUID of the brand / product / trade item to scope to. Required for every scope_type other than organization.

Required string length: 22

Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

group_by

enum<string>

Override the default child grouping. Most callers leave this blank — the service derives it from scope_type (org → brand, brand → product_and_trade_item, product → trade_item).

Available options:

brand,

product_and_trade_item,

trade_item

interval

enum<string>

default:day

Time bucket size for the X-axis.

Available options:

day,

week,

month

start

string<date-time>

Window start (UTC, inclusive). Defaults to 30 days before end.

end

string<date-time>

Window end (UTC, exclusive). Defaults to now.

metric

enum<string>

default:resolves

Counter to plot on the Y-axis. resolves = every scan the resolver served; page_visits = the hosted-page subset.

Available options:

resolves,

page_visits

top_n

integer

default:10

Cap on distinct stacked series. The remainder collapses into a single Others series so the chart stays readable.

Required range: 1 <= x <= 50

Response

Stacked traffic time series for a scope, ready for ECharts.

Shape mirrors the ticket's Response shape example. The frontend feeds timestamps to the X-axis and each :class:SeriesEntryOut to a stacked series; total / previous_period_total power the summary cards above the chart.

scope

ScopeOut · object

required

Entity the chart is currently zoomed into.

Show child attributes

Example:

{
  "id": "8kPq2mWvNc4RtYuIoPaSdF",
  "name": "Salsa Fresca",
  "type": "brand"
}

Drill-down path from the org root to the current scope. The frontend renders this as a click-to-navigate trail.

Show child attributes

interval

enum<string>

required

Time bucket size used to build timestamps.

Available options:

day,

week,

month

metric

enum<string>

required

Which counter the data arrays report.

Available options:

resolves,

page_visits

period

PeriodOut · object

required

Window covered by timestamps.

Show child attributes

Example:

{
  "end": "2026-07-08T00:00:00Z",
  "start": "2026-07-01T00:00:00Z"
}

total

integer

required

Sum of every series total within period — top summary card.

Required range: x >= 0

previous_period_total

integer

required

Sum for the immediately preceding equal-length window. Used to compute the delta-vs-previous summary and per-series trend indicator. Zero when no historical data exists.

Required range: x >= 0

series

SeriesEntryOut · object[]

required

Children of the current scope, ranked by total descending. High-cardinality scopes apply a Top N + Others collapse — see top_n query param.

Show child attributes

timestamps

string<date>[]

required

X-axis bucket starts, ISO date / datetime. Length matches every series' data array.

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

Hierarchical traffic time series for a scope

Authorizations

Query Parameters

Response