Touchpoint totals over time

Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.

POST

/analytics/v1/traffic/touchpoints/series

const url = 'https://api.eu1.luigisbox.ai/analytics/v1/traffic/touchpoints/series?channel_ids=example';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"attribution_model":"last_touch","date_range":{"date_from":"2026-04-15T12:00:00Z","date_to":"2026-04-15T12:00:00Z"},"filters":{"$and":[{"consent_granted":{"eq":true},"device":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"external_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_id":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page_host":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"personalized":{"eq":true},"platform":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"returning":{"eq":true},"session_rank":{"eq":1,"gt":1,"gte":1,"in":[1],"lt":1,"lte":1,"neq":1,"not_in":[1]},"touchpoint":{"eq":"autocomplete","in":["autocomplete"],"neq":"autocomplete","not_in":["autocomplete"]},"traffic_source":{"eq":"direct","in":["direct"],"neq":"direct","not_in":["direct"]},"traffic_source_type":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]}}],"$not":{"consent_granted":{"eq":true},"device":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"external_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_id":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page_host":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"personalized":{"eq":true},"platform":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"returning":{"eq":true},"session_rank":{"eq":1,"gt":1,"gte":1,"in":[1],"lt":1,"lte":1,"neq":1,"not_in":[1]},"touchpoint":{"eq":"autocomplete","in":["autocomplete"],"neq":"autocomplete","not_in":["autocomplete"]},"traffic_source":{"eq":"direct","in":["direct"],"neq":"direct","not_in":["direct"]},"traffic_source_type":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]}},"$or":[{"consent_granted":{"eq":true},"device":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"external_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_id":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"internal_ab_test_variant":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"landing_page_host":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"personalized":{"eq":true},"platform":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]},"returning":{"eq":true},"session_rank":{"eq":1,"gt":1,"gte":1,"in":[1],"lt":1,"lte":1,"neq":1,"not_in":[1]},"touchpoint":{"eq":"autocomplete","in":["autocomplete"],"neq":"autocomplete","not_in":["autocomplete"]},"traffic_source":{"eq":"direct","in":["direct"],"neq":"direct","not_in":["direct"]},"traffic_source_type":{"eq":"example","exists":true,"in":["example"],"matches":"example","neq":"example","not_in":["example"]}}]},"granularity":"hour","group_by":[],"metrics":["users"],"timezone":"UTC","touchpoints":["autocomplete"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.eu1.luigisbox.ai/analytics/v1/traffic/touchpoints/series?channel_ids=example' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "attribution_model": "last_touch", "date_range": { "date_from": "2026-04-15T12:00:00Z", "date_to": "2026-04-15T12:00:00Z" }, "filters": { "$and": [ { "consent_granted": { "eq": true }, "device": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "external_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_id": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page_host": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "personalized": { "eq": true }, "platform": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "returning": { "eq": true }, "session_rank": { "eq": 1, "gt": 1, "gte": 1, "in": [ 1 ], "lt": 1, "lte": 1, "neq": 1, "not_in": [ 1 ] }, "touchpoint": { "eq": "autocomplete", "in": [ "autocomplete" ], "neq": "autocomplete", "not_in": [ "autocomplete" ] }, "traffic_source": { "eq": "direct", "in": [ "direct" ], "neq": "direct", "not_in": [ "direct" ] }, "traffic_source_type": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] } } ], "$not": { "consent_granted": { "eq": true }, "device": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "external_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_id": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page_host": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "personalized": { "eq": true }, "platform": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "returning": { "eq": true }, "session_rank": { "eq": 1, "gt": 1, "gte": 1, "in": [ 1 ], "lt": 1, "lte": 1, "neq": 1, "not_in": [ 1 ] }, "touchpoint": { "eq": "autocomplete", "in": [ "autocomplete" ], "neq": "autocomplete", "not_in": [ "autocomplete" ] }, "traffic_source": { "eq": "direct", "in": [ "direct" ], "neq": "direct", "not_in": [ "direct" ] }, "traffic_source_type": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] } }, "$or": [ { "consent_granted": { "eq": true }, "device": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "external_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_id": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "internal_ab_test_variant": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "landing_page_host": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "personalized": { "eq": true }, "platform": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] }, "returning": { "eq": true }, "session_rank": { "eq": 1, "gt": 1, "gte": 1, "in": [ 1 ], "lt": 1, "lte": 1, "neq": 1, "not_in": [ 1 ] }, "touchpoint": { "eq": "autocomplete", "in": [ "autocomplete" ], "neq": "autocomplete", "not_in": [ "autocomplete" ] }, "traffic_source": { "eq": "direct", "in": [ "direct" ], "neq": "direct", "not_in": [ "direct" ] }, "traffic_source_type": { "eq": "example", "exists": true, "in": [ "example" ], "matches": "example", "neq": "example", "not_in": [ "example" ] } } ] }, "granularity": "hour", "group_by": [], "metrics": [ "users" ], "timezone": "UTC", "touchpoints": [ "autocomplete" ] }'

What the lists shown at each touchpoint give the site, over time.

Authorizations

HTTPBearer

Parameters

Query Parameters

channel_ids

required

Channel Ids

One or more channel ids to aggregate over. Provide as repeated query parameters (?channel_ids=A&channel_ids=B).

Array<string>

>= 1 items

One or more channel ids to aggregate over. Provide as repeated query parameters (?channel_ids=A&channel_ids=B).

Request Body^required

application/json

TouchpointSeriesRequest

Request for totals per bucket.

object

attribution_model

AttributionModel

Which of the lists that showed an item is credited with an interaction on it; only last_touch, the last of them, is recorded today.

string

default: last_touch

Allowed values: last_touch

date_range

required

DateRange

The time range of the report.

object

date_from

required

Date From

Start, inclusive.

string format: date-time

date_to

required

Date To

End, exclusive.

string format: date-time

filters

Any of:

TrafficFilter
null

One of:

object
object

A group node: exactly one of $and, $or, $not.

object

>= 1 properties <= 1 properties

$and

Nodes that must all match.

Array

>= 1 items

One of:

recursive object
object

object recursive

A condition node: field names mapped to operator objects; sibling fields combine as AND.

object

>= 1 properties

consent_granted

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

device

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

external_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_id

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page_host

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

personalized

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

platform

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

returning

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

session_rank

IntegerCondition

Operators on one whole-number field.

object

>= 1 properties

Equal to.

integer

Greater than.

integer

gte

Gte

At least.

integer

One of.

Array<integer>

>= 1 items <= 100 items

Less than.

integer

lte

Lte

At most.

integer

neq

Neq

Not equal to.

integer

not_in

Not In

None of.

Array<integer>

>= 1 items <= 100 items

touchpoint

TouchpointCondition

Operators on where a session was shown lists.

object

>= 1 properties

TrafficTouchpoint

Equal to.

string

Allowed values: autocomplete serp plp chat

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

neq

TrafficTouchpoint

Not equal to.

string

Allowed values: autocomplete serp plp chat

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

traffic_source

TrafficSourceCondition

Operators on how a session arrived.

object

>= 1 properties

TrafficSource

Equal to.

string

Allowed values: direct paid referral llms

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

neq

TrafficSource

Not equal to.

string

Allowed values: direct paid referral llms

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

traffic_source_type

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

key

additional properties

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

$not

One of:

recursive object
object

object recursive

A condition node: field names mapped to operator objects; sibling fields combine as AND.

object

>= 1 properties

consent_granted

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

device

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

external_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_id

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page_host

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

personalized

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

platform

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

returning

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

session_rank

IntegerCondition

Operators on one whole-number field.

object

>= 1 properties

Equal to.

integer

Greater than.

integer

gte

Gte

At least.

integer

One of.

Array<integer>

>= 1 items <= 100 items

Less than.

integer

lte

Lte

At most.

integer

neq

Neq

Not equal to.

integer

not_in

Not In

None of.

Array<integer>

>= 1 items <= 100 items

touchpoint

TouchpointCondition

Operators on where a session was shown lists.

object

>= 1 properties

TrafficTouchpoint

Equal to.

string

Allowed values: autocomplete serp plp chat

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

neq

TrafficTouchpoint

Not equal to.

string

Allowed values: autocomplete serp plp chat

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

traffic_source

TrafficSourceCondition

Operators on how a session arrived.

object

>= 1 properties

TrafficSource

Equal to.

string

Allowed values: direct paid referral llms

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

neq

TrafficSource

Not equal to.

string

Allowed values: direct paid referral llms

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

traffic_source_type

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

key

additional properties

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

$or

Nodes of which at least one must match.

Array

>= 1 items

One of:

recursive object
object

object recursive

A condition node: field names mapped to operator objects; sibling fields combine as AND.

object

>= 1 properties

consent_granted

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

device

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

external_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_id

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page_host

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

personalized

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

platform

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

returning

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

session_rank

IntegerCondition

Operators on one whole-number field.

object

>= 1 properties

Equal to.

integer

Greater than.

integer

gte

Gte

At least.

integer

One of.

Array<integer>

>= 1 items <= 100 items

Less than.

integer

lte

Lte

At most.

integer

neq

Neq

Not equal to.

integer

not_in

Not In

None of.

Array<integer>

>= 1 items <= 100 items

touchpoint

TouchpointCondition

Operators on where a session was shown lists.

object

>= 1 properties

TrafficTouchpoint

Equal to.

string

Allowed values: autocomplete serp plp chat

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

neq

TrafficTouchpoint

Not equal to.

string

Allowed values: autocomplete serp plp chat

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

traffic_source

TrafficSourceCondition

Operators on how a session arrived.

object

>= 1 properties

TrafficSource

Equal to.

string

Allowed values: direct paid referral llms

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

neq

TrafficSource

Not equal to.

string

Allowed values: direct paid referral llms

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

traffic_source_type

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

key

additional properties

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

A condition node: field names mapped to operator objects; sibling fields combine as AND.

object

>= 1 properties

consent_granted

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

device

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

external_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_id

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

internal_ab_test_variant

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

landing_page_host

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

personalized

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

platform

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

returning

BooleanCondition

Operators on one true-or-false field.

object

>= 1 properties

Equal to.

boolean

session_rank

IntegerCondition

Operators on one whole-number field.

object

>= 1 properties

Equal to.

integer

Greater than.

integer

gte

Gte

At least.

integer

One of.

Array<integer>

>= 1 items <= 100 items

Less than.

integer

lte

Lte

At most.

integer

neq

Neq

Not equal to.

integer

not_in

Not In

None of.

Array<integer>

>= 1 items <= 100 items

touchpoint

TouchpointCondition

Operators on where a session was shown lists.

object

>= 1 properties

TrafficTouchpoint

Equal to.

string

Allowed values: autocomplete serp plp chat

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

neq

TrafficTouchpoint

Not equal to.

string

Allowed values: autocomplete serp plp chat

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: autocomplete serp plp chat

traffic_source

TrafficSourceCondition

Operators on how a session arrived.

object

>= 1 properties

TrafficSource

Equal to.

string

Allowed values: direct paid referral llms

One of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

neq

TrafficSource

Not equal to.

string

Allowed values: direct paid referral llms

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

Allowed values: direct paid referral llms

traffic_source_type

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

key

additional properties

StringCondition

Operators on one text field.

object

>= 1 properties

Equal to.

string

exists

Exists

Has a value (true) or has none (false).

boolean

One of.

Array<string>

>= 1 items <= 100 items

matches

Matches

Contains this text.

string

>= 1 characters

neq

Neq

Not equal to.

string

not_in

Not In

None of.

Array<string>

>= 1 items <= 100 items

granularity

Granularity

The length of a bucket.

string

default: day

Allowed values: hour day week month quarter year

group_by

Group By

Fields that split every row, summary and series point, e.g. ["device"]. At most one of landing_page, url_path, url_params.* and context.*; a summary or series holds at most 500 groups, and a session with several values of a key counts once in each of its groups.

Array

default: <= 2 items unique items

metrics

Metrics

Metrics to compute; every metric of the report when left out.

Array<string>

>= 1 items unique items

Allowed values: users sessions session_share lists clicks click_through_rate attributed_cart_value attributed_items attributed_transaction_rate attributed_revenue attributed_key_events_1 attributed_key_events_1_rate attributed_key_events_2 attributed_key_events_3

timezone

Timezone

The IANA timezone whose calendar the buckets follow, e.g. Europe/Bratislava: UTC or an <area>/<location> name. Every bucket after the first starts at a whole hour, or at the local midnight that starts a day, a Monday, or a month, quarter or year there, so across a change of the zone’s offset a day lasts 23 or 25 hours. date_range stays two instants: give it local midnights, e.g. 2026-10-01T00:00:00+02:00, for whole first and last buckets.

string

default: UTC <= 64 characters

touchpoints

Any of:

Array<string>
null

Array<string>

>= 1 items

Allowed values: autocomplete serp plp chat

Responses

200

Successful Response

application/json

TouchpointSeries

Totals per touchpoint and bucket.

object

granularity

required

Granularity

The length of a bucket, as requested.

string

Allowed values: hour day week month quarter year

points

required

Points

Every bucket of date_range per touchpoint some session was shown lists at, by touchpoint in the order serp, autocomplete, plp, null, then chat, and then time; with group_by, by touchpoint, group value and then time. A bucket without data has counts and money of 0, and every other metric null. At most 10,000 points.

Array<object>

TouchpointSeriesPoint

One time bucket.

object

group

Group

Its group_by values; present with group_by.

object

channel_id

Any of:

string
null

string

consent_granted

Any of:

boolean
null

boolean

context

Any of:

object
null

object

key

additional properties

Any of:

string
null

string

device

Any of:

string
null

string

external_ab_test_variant

Any of:

string
null

string

internal_ab_test_id

Any of:

string
null

string

internal_ab_test_variant

Any of:

string
null

string

landing_page

Any of:

string
null

string

landing_page_host

Any of:

string
null

string

personalized

Any of:

boolean
null

boolean

platform

Any of:

string
null

string

result_type

Any of:

string
null

string

returning

Any of:

boolean
null

boolean

surface_id

Any of:

string
null

string

touchpoint

Any of:

SearchReportTouchpoint
null

SearchReportTouchpoint

Where a search list was shown: serp, the results page, or autocomplete, the as-you-type panel.

string

Allowed values: autocomplete serp

traffic_source

Any of:

TrafficSource
null

TrafficSource

string

Allowed values: direct paid referral llms

traffic_source_type

Any of:

string
null

string

url_host

Any of:

string
null

string

url_params

Any of:

object
null

object

key

additional properties

Any of:

string
null

string

url_path

Any of:

string
null

string

metrics

required

TouchpointMetrics

Metrics over the bucket.

object

attributed_cart_value

Any of:

number
null

number

attributed_items

Any of:

number
null

number

attributed_key_events_1

Any of:

number
null

number

attributed_key_events_1_rate

Any of:

number
null

number

attributed_key_events_2

Any of:

number
null

number

attributed_key_events_3

Any of:

number
null

number

attributed_revenue

Any of:

number
null

number

attributed_transaction_rate

Any of:

number
null

number

click_through_rate

Any of:

number
null

number

clicks

Any of:

number
null

number

lists

Any of:

integer
null

integer

session_share

Any of:

number
null

number

sessions

Any of:

integer
null

integer

users

Any of:

integer
null

integer

starts_at

required

Starts At

Start of the bucket, as a UTC instant at a boundary of timezone; the first and last buckets are clipped to date_range.

string format: date-time

touchpoint

required

Any of:

TrafficTouchpoint
null

TrafficTouchpoint

Where a list was shown, read off the service that showed it; a recommender list records no touchpoint yet.

string

Allowed values: autocomplete serp plp chat

timezone

required

Timezone

The timezone the buckets follow: the request’s timezone, or UTC.

string

Example

{
  "granularity": "hour",
  "points": [
    {
      "group": {
        "touchpoint": "autocomplete",
        "traffic_source": "direct"
      },
      "touchpoint": "autocomplete"
    }
  ]
}

400

Malformed request

application/json

ErrorResponse

Canonical error body — every non-2xx response uses this shape.

object

exception_details

ExceptionDetails

Machine-readable error context; empty object when there is nothing to add.

object

error_code

Error Code

Stable machine code naming why a well-formed request was refused: snake_case, prefixed by its domain — e.g. filter_unknown_field or cursor_mismatch. Safe to branch on; reason is not. Absent when the status code says all there is to say.

string

validation_errors

Validation Errors

Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.

Array<object>

ValidationProblem

One field-level reason a request was rejected.

object

loc

required

Loc

Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].

Array

msg

required

Msg

What is wrong with the value at loc.

string

type

required

Type

Stable machine code for the problem, e.g. missing or string_too_short.

string

key

additional properties

any

reason

required

Reason

Human-readable, actionable error message.

string

request_id

Any of:

string
null

string

Example ^generated

{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}

401

Missing or invalid credentials

application/json

ErrorResponse

Canonical error body — every non-2xx response uses this shape.

object

exception_details

ExceptionDetails

Machine-readable error context; empty object when there is nothing to add.

object

error_code

Error Code

string

validation_errors

Validation Errors

Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.

Array<object>

ValidationProblem

One field-level reason a request was rejected.

object

loc

required

Loc

Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].

Array

msg

required

Msg

What is wrong with the value at loc.

string

type

required

Type

Stable machine code for the problem, e.g. missing or string_too_short.

string

key

additional properties

any

reason

required

Reason

Human-readable, actionable error message.

string

request_id

Any of:

string
null

string

Example ^generated

{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}

403

Authenticated but not permitted

application/json

ErrorResponse

Canonical error body — every non-2xx response uses this shape.

object

exception_details

ExceptionDetails

Machine-readable error context; empty object when there is nothing to add.

object

error_code

Error Code

string

validation_errors

Validation Errors

Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.

Array<object>

ValidationProblem

One field-level reason a request was rejected.

object

loc

required

Loc

Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].

Array

msg

required

Msg

What is wrong with the value at loc.

string

type

required

Type

Stable machine code for the problem, e.g. missing or string_too_short.

string

key

additional properties

any

reason

required

Reason

Human-readable, actionable error message.

string

request_id

Any of:

string
null

string

Example ^generated

{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}

422

Request validation failed, or the report cannot answer it as asked (exception_details.problems).

application/json

ReportError

The 422 body of a report request.

object

exception_details

required

ReportExceptionDetails

Machine-readable error context.

object

error_code

Error Code

string

problems

Problems

Why the report cannot answer the request as asked; validation_errors covers malformed fields.

Array<object>

ReportProblem

One reason a report request cannot be answered.

object

code

required

ReportProblemCode

Stable code of the problem; switch on it, not on message.

string

Allowed values: too_many_groups too_many_high_cardinality_groups too_many_points ab_test_variant_without_test nothing_to_compare report_too_large

loc

required

Loc

Where in the request, as in validation_errors[].loc, e.g. ["body", "group_by", 1].

Array

message

required

Message

What to change.

string

validation_errors

Validation Errors

Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.

Array<object>

ValidationProblem

One field-level reason a request was rejected.

object

loc

required

Loc

Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].

Array

msg

required

Msg

What is wrong with the value at loc.

string

type

required

Type

Stable machine code for the problem, e.g. missing or string_too_short.

string

key

additional properties

any

reason

required

Reason

Human-readable, actionable error message.

string

request_id

Any of:

string
null

string

Example

{
  "exception_details": {
    "problems": [
      {
        "code": "too_many_groups"
      }
    ]
  }
}

503

Service temporarily unavailable

application/json

ErrorResponse

Canonical error body — every non-2xx response uses this shape.

object

exception_details

ExceptionDetails

Machine-readable error context; empty object when there is nothing to add.

object

error_code

Error Code

string

validation_errors

Validation Errors

Every field-level problem found in the request, when validation is what failed. Absent when the rejection is not about a specific value.

Array<object>

ValidationProblem

One field-level reason a request was rejected.

object

loc

required

Loc

Path to the offending value from the request root, e.g. ["body", "filters", 0, "operator"].

Array

msg

required

Msg

What is wrong with the value at loc.

string

type

required

Type

Stable machine code for the problem, e.g. missing or string_too_short.

string

key

additional properties

any

reason

required

Reason

Human-readable, actionable error message.

string

request_id

Any of:

string
null

string

Example ^generated

{
  "exception_details": {
    "error_code": "example",
    "validation_errors": [
      {
        "loc": [
          "example"
        ],
        "msg": "example",
        "type": "example"
      }
    ]
  },
  "reason": "example",
  "request_id": "example"
}

Was this page helpful?

Thanks.

Touchpoint totals over time

Authorizations

Parameters

Query Parameters

Request Body required

Responses

200

Example

400

Example generated

401

Example generated

403

Example generated

422

Example

503

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated