Skip to main content

Read, change or log AI Search’s search results

Premium Intermediate AI Search

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_id is 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 is 404 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_only returns true: a signed-out request is 401 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.
  • q is 2 to 200 characters after trimming, or 400 benecaster_ai_search_query_invalid.
  • Send X-WP-Nonce (a wp_rest nonce) 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_limited with retry_after (seconds) in the error data. The visitor is the IP address after the benecaster_rate_limit_client_ip filter.
  • 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: [] with unavailable: true until midnight UTC. That is not an error, and pinned results still come back.
  • Optional result_visibility (hidden, the default, or locked; anything else is hidden), locked_cta_url and locked_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; [] whenever unavailable is 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: [] with unavailable: 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 hidden mode, and in locked mode returned as locked: true with only id, title, url and the card’s html (date and excerpt empty). Only the show’s published episodes are returned. excerpt is 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 ): array filters 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, default 10. 0 or 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; 500 until changed, 0 for No limit). 0 or less is no limit. Read before every search that would reach the provider; a search past it is answered unavailable: true and 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 ): string filters 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>' );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →