Event diagnostics tools

get_pixel_health_status: Get the health of each pixel type and the top issues for failing ones.
get_pixel_event_stream: Sample raw pixel events and see how devices and issues break down.
get_pixel_event_details: Get the full parameters and derived properties for a single pixel event.

get_pixel_health_status

Returns the health of a merchant's tracking pixels: which pixel types are healthy, which have issues, and the top issue categories for each failing type. Pageview pixels and event pixels are reported separately, each with an event count, issue count, issue rate, and top issues.

Start here when you investigate tracking problems. It shows which pixel type is broken and what the dominant issue is, for example url_invalid or missing_uid. Then call get_pixel_event_stream to drill into a failing type and inspect individual events. Use mode='live' for production traffic, or mode='debug' to validate a new integration before go-live.

Request parameters

Name	Type	Required?	Description
`account_name`	`str`	No	The account name. Selected for you when you have exactly one account. Required in live mode with multiple accounts.
`period_hours`	`int`	No	How many hours back from now to query. Defaults to `8`, up to `720` (30 days).
`mode`	`"live" \| "debug"`	No	`'live'` for production traffic, `'debug'` for the test pixel endpoint. Defaults to `'live'`.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to find sites.

Response parameters

The tool returns a PixelHealthStatusResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`account_name`	`str`	The account or merchant name used in the query.
`period_hours`	`int`	The time window queried, in hours back from now.
`page_view_pixels`	`list[PixelTypeSummary]`	Health status per pageview pixel type.
`event_pixels`	`list[PixelTypeSummary]`	Health status per event pixel type.
`error`	`str \| null`	Error message if the request failed.

The PixelTypeSummary object has the following fields:

Field	Type	Description
`display_type`	`str`	The pixel type identifier.
`event_count`	`int`	Total events fired by this pixel type in the window.
`issue_count`	`int`	Events with at least one issue.
`issue_rate_pct`	`float`	The percentage of events with issues, from 0 to 100.
`top_issues`	`list[PixelIssueCount]`	Issue types ordered by frequency, populated when `issue_count` is above 0.

The PixelIssueCount object has the following fields:

Field	Type	Description
`status_key`	`str`	The issue type key, for example `'url_invalid'` or `'missing_uid'`.
`count`	`int`	The number of events with this issue in the window.

get_pixel_event_stream

Fetches a sample of pixel events with optional filters, then aggregates the device type and issue key distributions from the returned records. Use it to drill into a failing pixel type and see which devices and issue categories dominate, for example mostly mobile events flagged as url_invalid.

Call get_pixel_health_status first to find the failing display_types and status_keys, then pass them here to sample the raw events. All PII in the stream is masked server-side. The pixel_id field is safe to share and is the key you pass to get_pixel_event_details.

Request parameters

Name	Type	Required?	Description
`account_name`	`str`	No	The account name. Selected for you when you have exactly one account.
`display_types`	`list[str]`	No	Filter to specific pixel types, for example `['product-pageview', 'search-event']`. Omit for all types.
`status_keys`	`list[str]`	No	Filter to events with specific issue keys, OR-combined. Omit to return all events, including healthy ones.
`period_hours`	`int`	No	How many hours back from now to query. Defaults to `8`, up to `720` (30 days).
`max_events`	`int`	No	The maximum events to return. Defaults to `50`, capped at `100`.
`mode`	`"live" \| "debug"`	No	`'live'` for production traffic, `'debug'` for the test pixel endpoint. Defaults to `'live'`.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to find sites.

Response parameters

The tool returns a PixelEventStreamResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`total_events`	`int`	Total matching events reported by the API.
`returned_events`	`int`	The number of events included in this response.
`device_summary`	`dict[str, int]`	Event count per device type, derived from returned events.
`issue_summary`	`dict[str, int]`	Event count per issue key, derived from returned events.
`events`	`list[PixelEvent]`	The event records.
`error`	`str \| null`	Error message if the request failed.

The PixelEvent object has the following fields:

Field	Type	Description
`timestamp`	`str`	The event timestamp in ISO 8601 format.
`display_type`	`str`	The pixel type that fired this event.
`status_keys`	`list[str]`	Issue keys attached to this event.
`device_type`	`str \| null`	The device type, for example `'mobile'` or `'desktop'`.
`domain_key`	`str \| null`	The domain key where the event fired.
`view_id`	`str \| null`	The view ID for the site.
`pixel_id`	`str`	The unique pixel event ID.

get_pixel_event_details

Returns the full parameters and derived properties for a single pixel event, identified by the pixel_id and timestamp you get from get_pixel_event_stream. Both values must come from the same event record, and the mode must match the source, since live IDs can't be fetched in debug mode and vice versa.

The response has the raw query-string parameters the browser sent (pixel_params, such as url, cat_id, and prod_id) plus server-derived fields (derived_params, such as display type, issue keys, and device class). Use it to diagnose exactly why an event has a particular issue key, for example which URL was flagged as invalid. The cookie_uid and client_ip fields in derived_params are partially redacted by the upstream API.

Request parameters

Name	Type	Required?	Description
`pixel_id`	`str`	Yes	The pixel event ID from `get_pixel_event_stream`, for example `'pixel-6-5701308944-1781681267062'`.
`timestamp`	`str`	Yes	The ISO 8601 event timestamp from `get_pixel_event_stream`, for example `'2026-06-17T07:27:47.062Z'`.
`account_name`	`str`	No	The account name. Selected for you when you have exactly one account.
`mode`	`"live" \| "debug"`	No	`'live'` for production events, `'debug'` for test events. Must match the source of the `pixel_id`. Defaults to `'live'`.
`site_group_id`	`str \| int \| null`	No	The site group ID or site name. Defaults to `-1` (account level). Use `list_discovery_sites` to find sites.

Response parameters

The tool returns a PixelEventDetailResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the event was found and parsed successfully.
`pixel_id`	`str`	The event's unique pixel ID.
`pixel_params`	`dict`	Raw pixel parameters sent by the browser. The keys vary by pixel type.
`derived_params`	`PixelDerivedParams \| null`	Server-derived properties: device class, issues, and masked IDs.
`error`	`str \| null`	Error message if the request failed.

The PixelDerivedParams object has the following fields:

Field	Type	Description
`display_type`	`str`	The pixel type, for example `'category-pageview'`.
`status_keys`	`list[str]`	Issue keys for this event, for example `['cat_required']`.
`cookie_uid`	`str \| null`	The masked cookie UID for the visitor.
`user_agent`	`str \| null`	The full user-agent string.
`device_type`	`str \| null`	A human-readable device description, for example `'Apple iPhone, iOS 18.7'`.
`device_class`	`str \| null`	The broad device class, for example `'mobile'` or `'desktop'`.
`client_ip`	`str \| null`	The masked client IP address.
`cdp_segments`	`dict`	CDP segment membership for this visitor.
`timestamp`	`str`	The ISO 8601 timestamp when the event was received.