Read, change or log AI Search’s search results
Log what listeners search for, change what the AI Search box returns, or call the search yourself from your own front end. Every search is billed to the podcaster’s provider account, so this recipe also covers the limits that keep that bill in check, and the choice to keep AI Search for signed-in visitors.
GET /wp-json/benecaster-ai-search/v1/search?show_id={id}&q={query} is the benecaster_ai_search box’s request, and AI Search’s only public route (anyone may call it; what each visitor sees is decided inside).
show_idis required: send the show explicitly, because a REST request has no post to tell which show you mean. AI Search must be switched on for that show, or the answer is404 benecaster_ai_search_unavailable.- Signed-in visitors only, when the podcaster chose it on Settings → AI Search (AI Search is for → Signed-in visitors only; off by default) or
benecaster_ai_search_signed_in_onlyreturns true: a signed-out request is401 benecaster_ai_search_sign_in_required, checked straight after the show and before the query, so it never counts toward the rate limit or the daily limit and never reaches the provider. Pinned results are refused with the rest. qis 2 to 200 characters after trimming, or400 benecaster_ai_search_query_invalid.- Send
X-WP-Nonce(awp_restnonce) for a signed-in visitor. Without it WordPress runs the request as signed out, and a member’s paid episodes are left out. - Rate-limited per visitor: 10 searches a minute by default, in a fixed window from the first; then
429 benecaster_ai_search_rate_limitedwithretry_after(seconds) in the error data. The visitor is the IP address after thebenecaster_rate_limit_client_ipfilter. - Capped per show per day: once a show has had its daily limit of searches that reach the provider (500 by default, set on Settings → AI Search, counted per UTC day; a query answered from its saved vector or ranking never counts), the answer is
results: []withunavailable: trueuntil midnight UTC. That is not an error, and pinned results still come back. - Optional
result_visibility(hidden, the default, orlocked; anything else ishidden),locked_cta_urlandlocked_cta_label: see Show locked search results, or replace their card. - The answer is
200 { results: [ { id, title, url, date, excerpt, locked, pinned, html? } ], quotes, unavailable }(quotes: see Read or change what a guest said;[]wheneverunavailableis true), at most 10: the show’s firing pinned results first (pinned: true, see Manage or change AI Search’s pinned results), then the best matches. A provider failure, or no provider or key set, is not an error either:results: []withunavailable: true, and the provider’s message goes to the PHP error log. Fields may be added to a result in later versions; none will be removed. - Each result is decided for the visitor with benecaster_user_can_access_episode(). An episode they cannot open is left out entirely in
hiddenmode, and inlockedmode returned aslocked: truewith onlyid,title,urland the card’shtml(dateandexcerptempty). Only the show’s published episodes are returned.excerptis the episode’s description, never transcript text. - A transcript match counts only for a visitor Transcription allows to see that transcript (benecaster_user_can_see_transcript()), asked per episode for the visitor searching. For anyone else the episode is placed by its own title, description and notes, and an episode found only through its transcript is left out. Without Transcription active no transcript match counts. That check answers true to anyone who can edit the episode, so test as a member, never as the podcaster. With the Anthropic provider no transcript is sent, so none matches.
The hooks:
benecaster_ai_search_before_search( string $query, int $show_id )fires once a request has passed the show, signed-in, query and rate-limit checks, before the provider is asked. Not fired for a refused request.benecaster_ai_search_results( array $results, string $query, int $show_id ): arrayfilters the list above after access is decided. Anything you add is shown to the visitor as it is: never add an episode or text the visitor may not see.benecaster_ai_search_after_search( string $query, int $show_id, array $results )fires with the filtered results. The place to log searches; the query text is what a visitor typed, so treat it as personal data.benecaster_ai_search_rate_limit( int $per_minute ): int, default10.0or less switches the limit off. Read on every search.benecaster_ai_search_daily_cap( int $cap, int $show_id ): int, default the podcaster’s Daily limit on paid searches (Settings → AI Search;500until changed,0for No limit).0or less is no limit. Read before every search that would reach the provider; a search past it is answeredunavailable: trueand is not sent. Settings → AI Search and Dashboard → Needs Attention name a show that reached it today. The count is a ceiling, not a meter: searches arriving at the same instant may count once.benecaster_ai_search_signed_in_only( bool $signed_in_only, int $show_id ): bool, default the podcaster’s AI Search is for choice (Settings → AI Search; Everyone until changed). Read when a box renders and on every search. True: a signed-out visitor’s box renders benecaster_search for the same show, and the route refuses them as above. Decide on the server only: the route answers whoever calls it, so a box attribute could never stop a bot.benecaster_ai_search_signed_out_output( string $html, array $atts, int $show_id ): stringfilters what a signed-out visitor gets in the box’s place: the keyword search box by default. Never return markup that calls the AI search route; it refuses a signed-out visitor.
Code
<?php
// Count zero-result searches per show, to see what listeners look for and do not find.
add_action( 'benecaster_ai_search_after_search', function ( string $query, int $show_id, array $results ): void {
if ( [] === $results ) {
$counts = (array) get_option( 'my_ai_search_misses', [] );
$counts[ $show_id ] = ( $counts[ $show_id ] ?? 0 ) + 1;
update_option( 'my_ai_search_misses', $counts, false );
}
}, 10, 3 );
// A members-only site where every visitor is signed in can allow more searches a minute.
add_filter( 'benecaster_ai_search_rate_limit', fn( int $per_minute ): int => is_user_logged_in() ? 30 : $per_minute );
// A flagship show gets a higher daily limit on paid searches than the others.
add_filter( 'benecaster_ai_search_daily_cap', fn( int $cap, int $show_id ): int => 12 === $show_id ? 2000 : $cap, 10, 2 );
// AI Search for signed-in visitors on show 12 only, whatever Settings → AI Search says.
add_filter( 'benecaster_ai_search_signed_in_only', fn( bool $on, int $show_id ): bool => 12 === $show_id ? true : $on, 10, 2 );
// Invite signed-out visitors to sign in, under the keyword search they get instead.
add_filter( 'benecaster_ai_search_signed_out_output', fn( string $html ): string => $html . '<p><a href="' . esc_url( wp_login_url( get_permalink() ) ) . '">Sign in</a> to search by topic.</p>' );
Hooks Used
Need this built rather than just documented? See our services →