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.
When you already have one or more alerts, choose New alert above the alert list to switch from editing the selected alert to a fresh creation form.
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. In the web editor, standard accounts choose one of the fixed intervals 1 hour, 6 hours, 12 hours, 1 day, 3 days or 7 days. Administrators and users with the Tools permission alerts.interval.high_frequency additionally see 1, 5, 15 and 30 minute presets. If an older alert already has another valid interval that the current owner is still authorized to use, that existing cadence remains selectable while editing so unrelated changes do not silently reschedule the alert.
The API keeps its existing numeric interval contract: standard accounts may submit 60-10080 minutes, while administrators and users with alerts.interval.high_frequency may also use 1-59 minute intervals. The fixed preset restriction applies to the web editor only.
Country provides the broad location scope. Areas / localities accepts municipalities, towns, districts or nearby areas, one per line, and Location notes can describe preferences such as nearby pickup or acceptable surrounding locations.
Tools combines those structured values into the Alert Engine's existing region context so both the primary required web search and source-recovery classification receive the same geographic constraints. Required terms, exclusions, domain filters, dates and relevance filtering continue to work independently. Geographic context is a search constraint; it is not treated as an exact distance calculation unless a result exposes sufficiently reliable location data.
The alert owner does not need to know another user's exact account email in advance. Delegate results to Tools user is an AJAX-backed searchable picker: type at least two characters from the person's name or email address and choose the matching existing Tools account. The picker loads only a small bounded set of matching accounts instead of preloading the user directory, excludes the signed-in owner and does not offer disabled accounts. An already configured recipient is shown when an alert is edited.
Choosing a result sets the account used by the existing delegation flow. The server still resolves and validates the selected account when the alert is saved; free text that was not selected from the search results is not silently accepted as a delegation target.
Delegation does not transfer ownership. The creator keeps all management controls, including editing, scheduling, running, pausing, resuming and ending the alert. The delegated user sees the alert under Shared with you and can open a dedicated read-only result/run dashboard. The delegated user cannot dismiss results or change the owner's alert.
Enabled normal email/SMS result notifications are sent to the delegated recipient when one is configured. Without delegation they continue to go to the owner. Changing the delegated recipient also changes the target for later notification batches and pending retries are not delivered to an obsolete recipient.
Transfer ownership is separate from delegation. Use it when another active Tools user should become the full owner and manager of the existing alert rather than only receive its results.
The current owner selects the destination account and confirms the exact alert name. Tools refuses the transfer while a run is pending or running, when the destination account is disabled, when that user already owns an alert with the same name, or when the alert's existing interval is shorter than the destination user's allowed minimum. A sub-60-minute alert therefore cannot be handed to an ordinary account unless the interval is increased first.
A successful transfer keeps the same alert id and configuration, moves stored result/run/audit ownership to the new owner, and preserves completed history. The old owner immediately loses owner-only web/API management access. A separate delegated result recipient remains configured unless that recipient is the new owner, in which case the redundant delegation is cleared. Historical delivery rows remain attached to the users who actually received them. The transfer does not rerun web search and does not create historical result notifications. See Web Search Alert ownership transfer in the Web UI documentation for the complete flow.
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.
A missing provider title by itself is not a rejection reason. If the URL and all configured alert rules pass, Tools keeps the candidate and creates a stable display title from the provider's source name when available, otherwise from the public URL host. The stored result metadata records that a fallback title was used so missing provider metadata remains distinguishable from a real supplied title.
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. Relevance uses the existing 0-100 score internally and is displayed in result tables as a percentage, for example 98%, so the scale is explicit without changing sorting, filtering, API output or stored values.
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. The result workspace uses the available page width, and long destinations are shown as compact Open links instead of printing the full URL into the table.
A run can reject candidates before they become normal alert results, for example because an excluded term matched, the result was outside the configured rules, public-link verification failed, or the result had already been dismissed by the owner. Missing title metadata alone does not put a candidate in this bucket. The run history shows a rejected count.
When the rejected count is non-zero, the count itself links directly to the rejected section for that exact run. The exact-run owner view shows the captured title, source, match reason, relevance score, rejection reason and destination when those fields are available. Rejected candidates remain separate from accepted alert_results, do not participate in normal result deduplication, and never trigger normal result notifications.
The detailed provider candidate snapshot is deliberately bounded and sanitized. Older runs can therefore have a rejected total larger than the number of detailed rows that remain available. Raw provider payloads, prompts, credentials and tokens are never exposed through this owner-facing view.
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 recipient 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. When the alert has a delegated recipient, normal result email is addressed to that recipient's current verified Tools account email; otherwise it goes to the owner.
SMS is always explicit opt-in. Both of these conditions must be true at delivery time:
The actual recipient is the delegated Tools user when delegation is configured, otherwise the alert owner. If either condition is false, no SMS is sent. Tools checks the conditions and current recipient again before a queued/retried SMS is delivered, so removing the number, turning SMS off or changing the delegated recipient also blocks an obsolete pending delivery.
The email and SMS controls also provide Send test. It sends one test message to the signed-in owner's current account email address or mobile number so the owner's delivery path can be checked before relying on a real alert result. This one-off test intentionally does not follow delegation and is independent of the saved email/SMS checkbox: clicking Send test authorizes that one owner-scoped delivery only.
A test does not save the form, change notification preferences, start a web search, create a normal Alert delivery record, or alter delivery timestamps. Email requires a usable verified account email address and SMS requires a valid saved mobile number. Test attempts are audited without storing recipient addresses or phone numbers.
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. For compatibility, owner/non-delegated delivery batches keep the legacy notification deduplication key. When a Web Search Alert is genuinely delegated to another user, that recipient identity is added to the key so a later recipient change cannot reuse the previous recipient's batch. Existing pending/failed delivery rows are revalidated at dispatch time against the alert's current recipient.
active_until has passed is completed automatically.Only the alert owner has these controls. A delegated result recipient has read-only access to the shared result/run dashboard.
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. Delegated read access in the web UI does not extend this scope and does not grant cross-user API access. The scope also does not grant SMS sending independently of the per-alert SMS setting and 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 |
POST |
/api/web-search-alerts/{id}/transfer-ownership |
Transfer the owned alert to another active Tools user |
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. Ownership transfer is also rejected while a run is pending/running or when the destination account cannot legally own the stored interval/name.
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.
Delegation changes are included in Alert audit history with user identifiers and delegation state only. Recipient email addresses and mobile numbers are not copied into Alert audit context. Ownership changes create a separate alert.ownership.transferred event containing the previous/new owner ids and actor without contact details.
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.