Filters reference
WordPress filters for customising REST API behaviour in Burst Statistics. Filters specific to share links are documented in Share links.
burst_get_data_request_args
Filters the normalized request arguments used by GET burst/v1/data/{type} before the data handler runs. Use this to inject or override parameters that are not part of the default allowed argument list.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$args | array | Normalized request arguments |
$type | string | Requested data type |
$request | WP_REST_Request | Original REST request object |
Show code
add_filter( 'burst_get_data_request_args', function( array $args, string $type, WP_REST_Request $request ): array {
// Inject custom comparison dates for the compare type.
if ( $type === 'compare' ) {
$args['compare_date_start'] = sanitize_text_field( $request->get_param( 'compare_date_start' ) );
$args['compare_date_end'] = sanitize_text_field( $request->get_param( 'compare_date_end' ) );
}
return $args;
}, 10, 3 );
burst_get_data
Fallback filter for custom GET burst/v1/data/{type} handlers. Fires when the requested {type} does not match any built-in type. Use this to add support for custom data types without modifying core files.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array | Current data array (empty [] by default for unknown types) |
$type | string | Requested data type |
$args | array | Normalized request arguments |
$request | WP_REST_Request | Original REST request object |
Show code
add_filter( 'burst_get_data', function( array $data, string $type, array $args, WP_REST_Request $request ): array {
if ( $type === 'my_custom_type' ) {
$data = [
'value' => get_my_custom_metric( $args['date_start'], $args['date_end'] ),
];
}
return $data;
}, 10, 4 );
burst_get_data_available_args
Filters the list of accepted request argument names for GET burst/v1/data/{type}. Any argument not present in this list is stripped before the request reaches the data handler. Use this to register custom request arguments for a data type, then sanitize the value with burst_sanitize_arg.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$args | array | Current list of allowed request argument names |
$type | string | Requested data type |
Show code
add_filter( 'burst_get_data_available_args', function( array $args, string $type ): array {
// Allow a custom boolean argument on the reading engagement endpoints.
if ( $type === 'reading_engagement' || $type === 'datatable-reading-engagement' ) {
$args[] = 'least_engagement';
}
return $args;
}, 10, 2 );
burst_sanitize_arg
Filters sanitization for custom request arguments in the data endpoint. Return null to fall back to Burst's default handling, or return a sanitized value to override it. Register the argument with burst_get_data_available_args first, otherwise it is stripped from the request before this filter runs.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed / null | Return a sanitized value to override, or null to use default handling |
$key | string | Argument name |
$raw | mixed | Raw value from the request |
Show code
add_filter( 'burst_sanitize_arg', function( $value, string $key, $raw ) {
if ( $key === 'least_engagement' ) {
return filter_var( $raw, FILTER_VALIDATE_BOOLEAN );
}
return $value; // null — let Burst handle it.
}, 10, 3 );
burst_statistics_allowed_filter_keys
Filters the list of accepted keys in the filters request parameter. Use this to allowlist additional filter keys for custom data integrations.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$keys | array | Current list of allowed filter key strings |
$is_strict | bool | Whether the request is in strict mode (i.e. the user is not an admin) |
Show code
add_filter( 'burst_statistics_allowed_filter_keys', function( array $keys, bool $is_strict ): array {
if ( ! $is_strict ) {
$keys[] = 'my_custom_dimension';
}
return $keys;
}, 10, 2 );
status filter key
status is a built-in accepted filter key that selects hits by response status. It is a virtual filter with no dedicated database column — it resolves against the stored page type, where 404 (not found) hits are recorded with a page type of 404.
| Value | Selects |
|---|---|
404 | Only 404 (not found) hits |
200 | Everything except 404 hits |
all | All hits, including 404s |
404 hits are excluded from statistics queries by default. Pass status in the filters request parameter to include or isolate them.
// Request only 404 hits from a data endpoint.
$request->set_param( 'filters', [ 'status' => '404' ] );
burst_rest_api_fields_get
Filters the response payload returned by GET burst/v1/fields/get. Use this to expose additional metadata alongside the core fields and menu configuration.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$response | array | The full fields/menu response array |
Show code
add_filter( 'burst_rest_api_fields_get', function( array $response ): array {
$response['my_plugin_data'] = get_my_plugin_metadata();
return $response;
} );
burst_rest_api_goals_get
Filters the goals payload returned by the goals GET endpoints. Applied to both the standard goals list and the share-link-safe goals response.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$response | array | The goals response array |
Show code
add_filter( 'burst_rest_api_goals_get', function( array $response ): array {
// Add a custom field to each goal.
if ( ! empty( $response['goals'] ) ) {
foreach ( $response['goals'] as &$goal ) {
$goal['my_field'] = get_my_goal_data( $goal['id'] );
}
}
return $response;
} );
burst_countries
Filters the country lookup array returned for country option lists in the admin app.
Expected format: associative array keyed by ISO 3166-1 alpha-2 country code.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$countries | array | Associative array of [ 'US' => 'United States', ... ] |
burst_continents
Filters the continent lookup array returned for continent option lists in the admin app.
Expected format: associative array keyed by two-letter continent code.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$continents | array | Associative array of [ 'EU' => 'Europe', ... ] |
burst_endpoint_tab_map
Filters the map of REST endpoint paths to dashboard tab slugs. Burst uses this map to resolve which tab a share-link viewer is requesting, so the request can be matched against the tabs allowed by the active share token. Use this to register custom endpoints so they fall under the correct shareable tab, or to mark an endpoint as unrestricted with the all slug.
The endpoint path is relative to the burst/v1 namespace (for example data/insights, not /wp-json/burst/v1/data/insights). Endpoints that are not present in the map are denied for shared viewers by default.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$map | array | Associative array of [ 'data/insights' => 'statistics', ... ] |
Show code
add_filter( 'burst_endpoint_tab_map', function( array $map ): array {
// Expose a custom endpoint to share-link viewers on the statistics tab.
$map['data/my_custom_widget'] = 'statistics';
return $map;
} );
burst_datatable_id_tab_map
Filters the map of datatable IDs to dashboard tab slugs. The generic datatable endpoints (data/datatable/{id} and data/ecommerce/datatable/{id}) resolve the active tab from the requested datatable ID rather than the endpoint path. Use this to register custom datatable IDs so they map onto the correct shareable tab.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$map | array | Associative array of [ 'statistics_pages' => 'statistics', ... ] |
Show code
add_filter( 'burst_datatable_id_tab_map', function( array $map ): array {
$map['my_custom_datatable'] = 'statistics';
return $map;
} );
burst_datatable_config
Filters the per-datatable configuration that controls which metric keys each datatable accepts and which capability a user must hold to access it. The config is an associative array keyed by datatable ID, where each entry is an array with a metrics list and a capability string. Incoming metrics arguments are intersected with the metrics list for the requested datatable ID, so any metric not declared here is silently dropped. Use this to register custom metrics for a datatable, change its required capability, or register an entirely new datatable ID.
This filter replaces burst_datatable_metric_allow_list. See the deprecation note below.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$config | array | Associative array of [ 'statistics_pages' => [ 'metrics' => [ 'page_url', 'pageviews', ... ], 'capability' => 'view_burst_statistics' ], ... ] |
Show code
add_filter( 'burst_datatable_config', function( array $config ): array {
// Add a custom metric to the pages datatable.
$config['statistics_pages']['metrics'][] = 'my_custom_metric';
// Register a new datatable with its own metric set and required capability.
$config['my_custom_datatable'] = [
'metrics' => [ 'page_url', 'pageviews', 'visitors' ],
'capability' => 'view_burst_statistics',
];
return $config;
} );
burst_datatable_metric_allow_list
@deprecated Use burst_datatable_config instead, which carries both the metric allowlist and the required capability per datatable.
burst_datatable_pre_data
Short-circuits the default datatable database query. Return a non-null array to use that data as the datatable response and bypass the built-in query for the requested datatable ID. Return null to let Burst run the default query. Use this to serve synthetic, cached, or remote data for custom datatable IDs.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | array / null | Pre-computed datatable rows, or null to fall through to the default query |
$args | array | Datatable arguments including id, date_start, date_end, metrics, filters, group_by, limit |
Show code
add_filter( 'burst_datatable_pre_data', function( ?array $data, array $args ): ?array {
if ( ( $args['id'] ?? null ) === 'my_custom_datatable' ) {
return [
[ 'page_url' => '/example', 'pageviews' => 1200, 'visitors' => 950 ],
[ 'page_url' => '/about', 'pageviews' => 480, 'visitors' => 410 ],
];
}
return $data; // null — let Burst run the default query.
}, 10, 2 );
burst_datatable_response
Filters the assembled datatable response after the columns, rows and metrics have been resolved, before it is returned by the datatable endpoints. Use this to append response-level metadata, post-process the rows, or attach progress indicators for a custom datatable ID.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$response | array | The datatable response array with columns, data and metrics keys |
$args | array | Datatable arguments including id, date_start, date_end, metrics, filters, group_by, limit |
Show code
add_filter( 'burst_datatable_response', function( array $response, array $args ): array {
if ( ( $args['id'] ?? null ) === 'my_custom_datatable' ) {
// Attach extra metadata alongside the rows.
$response['my_meta'] = get_my_datatable_meta();
}
return $response;
}, 10, 2 );
burst_rest_api_optimizer_keep_plugins
Filters the plugins that stay active while Burst's REST API optimizer disables other plugins during Burst REST requests. The value is grouped by matching strategy: plugins under partial_match are kept active when their plugin path contains one of the listed strings, while plugins under exact_match are kept only when their full plugin file path matches an entry exactly. Use this to keep a plugin loaded that Burst's REST requests depend on.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$plugins_to_keep | array | Plugins to keep active, grouped into partial_match (substring match) and exact_match (full plugin file path) lists |
Show code
add_filter( 'burst_rest_api_optimizer_keep_plugins', function( array $plugins_to_keep ): array {
// Keep any plugin whose path contains 'my-security'.
$plugins_to_keep['partial_match'][] = 'my-security';
// Keep one specific plugin by its exact plugin file path.
$plugins_to_keep['exact_match'][] = 'my-plugin/my-plugin.php';
return $plugins_to_keep;
} );
burst_select_sql_for_metric
Filters the SQL select expression used to resolve a metric in a statistics query. Handlers receive an accumulating SQL string as the first parameter so that multiple registrants (core geo metrics, Pro campaign and ecommerce metrics) compose without overwriting each other. Return the incoming $sql untouched when your handler does not own the metric, otherwise return the SQL expression to use for it. Call $qd->with( 'join_name' ) to add any joins your expression depends on.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$sql | string | SQL accumulated by earlier handlers (empty string '' on the first pass) |
$metric | string | The metric being resolved |
$qd | Statistics_Query | The query object; use $qd->with() to register required joins |
Show code
add_filter( 'burst_select_sql_for_metric', function( string $sql, string $metric, $qd ): string {
// Leave already-resolved SQL untouched so other handlers can run.
if ( $sql !== '' ) {
return $sql;
}
if ( $metric === 'my_custom_metric' ) {
$qd->with( 'sessions' );
return 'sessions.my_column';
}
return $sql; // not our metric — pass the accumulated value through.
}, 10, 3 );
burst_geoip_handler
Filters the class that resolves and stores a visitor's location during tracking. The default handler reads the MaxMind GeoLite2 Country database; the Pro build swaps in a city-level reader. The returned class must expose static add_location_data() and get_location_data() methods compatible with the core handler.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$handler | string | Fully qualified class name of the GeoIP handler |
add_filter( 'burst_geoip_handler', function( string $handler ): string {
return My_Custom_GeoIp_Handler::class;
} );
burst_location_data
Filters the resolved location data for a tracked hit before it is stored. Use this to mock location data in environments without a MaxMind database, or to adjust the resolved values.
Expected format: associative array with city, city_code, state, state_code, country_code, continent_code and accuracy_radius keys.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$location_data | array | Resolved location data for the current visitor |
Show code
add_filter( 'burst_location_data', function( array $location_data ): array {
// Provide a fallback country when none could be resolved.
if ( empty( $location_data['country_code'] ) ) {
$location_data['country_code'] = 'NL';
$location_data['continent_code'] = 'EU';
}
return $location_data;
} );
burst_maxmind_download_frequency
Pro - CreatorAvailable in the Creator tier
City-level location resolution requires a paid plan. See geographic insights.
Filters how often the Pro MaxMind GeoLite2 City database is refreshed, in seconds. Only the Pro City database cadence is filterable; the free Country database refresh cadence is fixed and cannot be altered through hooks.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$interval | int | Refresh interval in seconds |
Show code
add_filter( 'burst_maxmind_download_frequency', function( int $interval ): int {
// Refresh the City database every two weeks.
return 2 * WEEK_IN_SECONDS;
} );
burst_source_classifier_map
Filters the classification map used to categorise traffic sources into search, social, referral, AI referral, paid, email and direct, based on referrer hosts, UTM mediums and sources, and paid click IDs. Use this to add hosts, mediums or click ID parameters to an existing category.
Pro - CreatorAvailable in the Creator tier
Source classification requires a paid plan. See referral source analysis.
Parameters:
| Parameter | Type | Description |
|---|---|---|
$map | array | Classification map keyed by category, each holding hosts, mediums, utm_sources, utm_mediums or click_ids lists |
Show code
add_filter( 'burst_source_classifier_map', function( array $map ): array {
// Treat an additional host as a search engine.
$map['search']['hosts'][] = 'search.marginalia.nu';
// Recognise a custom paid click ID parameter.
$map['paid']['click_ids'][] = 'my_click_id';
return $map;
} );