Web Search Alerts is Tools' Google Alerts-style monitoring service for articles, interviews, videos, press releases and other publicly indexed web pages. Job Search remains the specialized service for job listings; Web Search Alerts uses the shared Alert Engine for generic web monitoring.
After signing in, open Web Search Alerts from either the Dashboard or the Services page.
Each alert belongs to the signed-in Tools user. You can configure:
Alert names are unique per Tools user. If a submitted field is invalid, including a name that is already in use, the form returns with a validation message and keeps the submitted input so it can be corrected. Validation feedback is shown inside the Web Search Alerts view above the alert manager, so it stays attached to the form being corrected.
A new active alert queues its first search immediately. If active_from is in the future, the first run waits until that time. Standard accounts may configure 60-10080 minutes. Administrators and users with the Tools permission alerts.interval.high_frequency may also use 1-59 minute intervals. The form shows the minimum interval available to the signed-in account.
Every Web Search Alert execution requires web search. The saved monitoring instruction is converted into concise search-engine-style queries together with useful date, language, region, domain and term constraints. Response-format instructions and the result schema are kept separate from the actual search query.
Exact multi-word names are kept as search constraints instead of being silently reduced to a surname or partial phrase. When the alert explicitly names a publisher, domain, month, year or similar qualifier, the provider is instructed to keep those constraints in relevant search queries. If initial sources are dominated by the wrong person or another ambiguous same-name/same-surname subject, the primary web-search execution should refine the query with the exact named entity and explicit qualifiers before returning an empty result list.
The machine-readable result shape is enforced with the OpenAI Responses API's native Structured Outputs contract rather than relying only on prompt wording. The primary Alert request uses a bounded web-search tool-call budget, the full configured output allowance and low reasoning effort so the provider has room to finish its structured result instead of spending the response budget on an unbounded search loop.
A provider HTTP success is not treated as a completed search when the Responses API reports an incomplete or failed response state. The provider state remains auditable as incomplete/failed. If that required primary search already exposed usable public source metadata, however, Tools can salvage those already-retrieved sources with one classification pass that has web search disabled. This does not turn the primary provider response into a completed response and does not perform another search. An incomplete response with no usable sources fails explicitly.
Tools also requests the provider's complete web-search source list separately from model-authored structured results and inline citations. The same no-search source-recovery pass can be used when a required search exposes usable sources but the first structured results array is empty, or when the structured text is empty/malformed. Recovery can classify only the supplied source titles and exact URLs; it cannot invent or substitute a source URL.
The recovery response itself still has to satisfy the strict JSON contract. Tools does not recursively retry malformed recovery output and never reruns web search merely because parsing or recovery failed.
Results returned or recovered from the AI provider are not accepted blindly: Tools applies the saved domain, term, date and relevance rules again before storing a result. Recovered candidates go through the same deterministic filtering, public-link verification, canonicalization, deduplication and notification rules as ordinary provider candidates.
A candidate must have a usable public HTTP(S) URL. Tools verifies the destination before storing it and rejects private/local network destinations and failed web destinations. Accepted URLs are canonicalized so common tracking parameters do not create duplicate results.
Some public publishers return HTTP 403 to an automated direct verification even though the page itself remains public. When a configured verification fallback is available, Tools retries that same public URL before rejecting the result. The same public-address and redirect safety checks still apply, and this does not grant access to authenticated or other non-public content.
Only public, normally indexed web content is in scope. Web Search Alerts does not bypass authentication or gain access to private profiles, private groups or other non-public content. Public social pages may be found only when they are available to normal web search/indexing.
Results are stored per alert and include the title, source, publication date when known, first discovery time, summary, match reason, relevance score and verified destination URL.
The same canonical result is not inserted repeatedly for one alert. Later runs update its last-seen state; content changes can be recorded as updates without pretending the item is a new discovery.
The result table, recent run history and recent delivery state are visible from the Web Search Alerts page.
Owner email/SMS notifications are created only when a run stores genuinely new results. A positive Web Search Alert run also creates or refreshes a Tools admin Notifications inbox item and publishes one shared web_search_alert.new_results event so configured Tools notification rules/channels can surface the hit. This shared publication is separate from owner email/SMS and is idempotent per Alert run. Runs with zero new results remain quiet.
Email is enabled by default for a new alert. A successful run with no new results stays quiet.
SMS is always explicit opt-in. Both of these conditions must be true at delivery time:
If either condition is false, no SMS is sent. Tools checks the conditions again before a queued/retried SMS is delivered, so removing the number or turning SMS off also blocks an already pending delivery.
Search execution and notification delivery are separate. A temporary delivery failure can be retried without running the web search again. Delivery records and the shared Tools notification publication are idempotent for their respective Alert run/result batch, so a successful delivery/publication is not repeated.
active_until has passed is completed automatically.Only one run for the same alert may be active at a time. Scheduled execution skips an alert while another run is still active instead of failing the whole schedule. If an earlier run is left unfinished beyond the execution safety window, Tools closes that run as failed and allows a later scheduled run to continue. A manual Run now request still reports an explicit conflict when another run is active instead of silently creating a second concurrent search.
SocialGPT can turn a fact verification into a Web Search Alert from both the floating Verify result and Verify mode in the browser side panel.
The extension sends the selected/article context, the current verification result and an optional verification follow-up to POST /api/socialgpt/alerts/prepare using the user's existing personal ai.socialgpt bearer token. Tools prepares a short alert name and an executable monitoring instruction. A direct monitoring instruction has highest priority, followed by the verification follow-up, then the selected/article/verification context.
The prepared name and instruction are shown before creation and remain editable. The user must explicitly choose how long monitoring should continue and how often it should run. The extension does not silently translate phrases such as "for a while" into a fixed duration. Current choices are 1, 3, 7 or 30 days, or explicitly "until I stop it", with hourly through daily checks.
POST /api/socialgpt/alerts creates the alert for the Tools user who owns the SocialGPT token and queues the first run through the normal Alert Engine. This narrow bridge does not require or grant the broader alerts.manage scope.
SocialGPT-created alerts start with email notifications enabled and SMS disabled. SMS can later be enabled through the normal Tools alert controls, where the same explicit SMS opt-in and valid-mobile requirements apply.
Before planning and audit storage, source URLs are reduced to scheme, host, optional port and path. Query strings and fragments are not kept, so tracking parameters or URL-carried credentials are not copied into the Alert audit context. Preparation and creation are audited without storing the bearer token or the full verification text.
If AI planning temporarily fails, Tools can still prepare a deterministic editable draft from the direct instruction, follow-up, selected text or page title. It never creates the alert without the user's explicit creation action.
The API is available under /api/web-search-alerts and requires a user-bound Tools API key with the alerts.manage scope.
The scope can manage only alerts owned by the same Tools user as the token. It does not grant cross-user access and does not grant SMS sending independently of the per-alert SMS setting. The alerts.manage scope also does not grant sub-hour interval access. The token owner must be an administrator or have the Tools permission alerts.interval.high_frequency before the API accepts an interval from 1 through 59 minutes.
Main operations:
| Method | Path | Purpose |
|---|---|---|
GET |
/api/web-search-alerts |
List the token owner's alerts |
POST |
/api/web-search-alerts |
Create an alert and queue the first run when active |
GET |
/api/web-search-alerts/{id} |
Read one owned alert |
PATCH |
/api/web-search-alerts/{id} |
Partially update one owned alert |
GET |
/api/web-search-alerts/{id}/results |
Read recent stored results |
GET |
/api/web-search-alerts/{id}/runs |
Read recent run history |
POST |
/api/web-search-alerts/{id}/run |
Queue a manual run |
POST |
/api/web-search-alerts/{id}/pause |
Pause the alert |
POST |
/api/web-search-alerts/{id}/resume |
Resume and queue a run |
POST |
/api/web-search-alerts/{id}/end |
End the alert while preserving history |
Use header-based authentication:
Authorization: Bearer YOUR_API_TOKEN
A missing/invalid token returns 401, a token without alerts.manage returns 403, and another user's alert is not exposed. An interval below the account's authorized minimum returns a validation error.
Tools administrators can open Web Search Alerts diagnostics from /admin. The admin surface shows alert ownership, state, result/run/delivery counts and recent dedicated Alert audit events. It also provides explicit Run now, Pause, Resume and End controls for alerts owned by any user.
Admin actions reuse the same Alert manager rules as the owner/API flows. Ending or pausing an alert does not remove stored result, run or delivery history. Admin actions are recorded with source = admin, the alert owner remains the affected user, and the administrator is stored as the action actor so operator changes remain independently auditable.
User/API changes, queued/started/completed/failed runs, and Alert notification queue/delivery outcomes are recorded separately from the general application log. Web Search runs also record structured-output validity/state, provider completion state and incomplete reason, whether an incomplete primary response was recovered, the structured candidate count, exposed web-search source count, citation count, source-recovery usage/count and post-filter accepted/rejected counts. This distinguishes an incomplete provider response recovered from real sources, an incomplete response that could not be recovered, a malformed response recovered from sources, a genuine zero-source search, a valid empty structured response, and candidates later rejected by local rules or link verification.
Administrators can route sanitized Alert Engine audit summaries through the existing Slack log routing settings. The routing includes identifiers, statuses, provider metadata, aggregate counts and grouped rejection reasons; prompts, credentials, raw provider responses and result bodies are not forwarded. Slack delivery remains secondary observability and does not replace or block the primary Alert audit history.