> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# web.search

> Governed web search via HASP's retrieval layer — PHI-safe, vertically ranked, citation-persisted.

`web.search` performs a governed web search via HASP's retrieval layer. The model receives up to 10 ranked results with title, URL, snippet, domain, and published date. HASP controls which provider executes, applies vertical-aware result ranking, and injects results into context before the model continues.

## PHI enforcement

Two PHI scans run before any provider call:

1. **On receipt** — when the tool call is intercepted at the gateway, the query is scanned.
2. **Pre-dispatch** — immediately before the outbound provider call, the planned query is scanned again.

The retrieval-specific behavior is controlled by your org's `phi_retrieval_behavior` setting (configured under **Settings → Retrieval**): `redact` (default) strips PHI from queries before they leave HASP; `block` rejects the tool call entirely if PHI is detected. Web search providers (Tavily by default) never receive PHI under any circumstance — this is a hard architectural invariant enforced at the platform level.

## Billing

* **5 AI Credits** flat surcharge per call, debited on provider success.
* Normal input-token cost applies to the injected result content.

The surcharge is only charged when the provider returns a successful response. No charge is applied for failed provider calls or PHI-blocked calls.

## Input parameters

| Parameter         | Type    | Required | Description                                                                     |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------- |
| `query`           | string  | Yes      | The search query.                                                               |
| `maxResults`      | integer | No       | Number of results to return. Range 1–10. Default: `5`.                          |
| `freshnessWindow` | string  | No       | Freshness filter. Accepted values: `"7d"`, `"30d"`, `"1y"`. Omit for no filter. |
| `conversationId`  | string  | No       | Correlation context. Passed automatically by HASP in chat sessions.             |

## Output fields

Each result injected into context contains:

| Field                | Type           | Description                                    |
| -------------------- | -------------- | ---------------------------------------------- |
| `title`              | string         | Page title.                                    |
| `url`                | string         | Source URL.                                    |
| `snippet`            | string         | Relevant excerpt from the page.                |
| `domain`             | string         | Apex domain (e.g., `nih.gov`).                 |
| `publishedDate`      | string \| null | ISO 8601 date if known; `null` if unavailable. |
| `retrievedTimestamp` | string         | ISO 8601 timestamp of retrieval.               |
| `rank`               | integer        | Position in the result set (1-indexed).        |

## Vertical-aware ranking

For orgs with a healthcare vertical configured, HASP applies boosted ranking for authoritative clinical and regulatory sources including NIH, CDC, FDA, CMS, and PubMed. Results from these domains are ranked higher than general-web equivalents when present in the provider response.

## Citations

Results injected into the model's context are persisted as citations linked to the conversation message. Citations survive page refresh and are available in the [Audit endpoint](/ai-api/control/audit). Each citation records the source URL, snippet, rank, and `retrievedTimestamp`.

## Example

Tool call emitted by the model:

```json theme={null}
{
  "type": "tool_use",
  "name": "web.search",
  "input": {
    "query": "HIPAA breach notification rule requirements 2024",
    "maxResults": 3,
    "freshnessWindow": "1y"
  }
}
```

Result injected into context:

```json theme={null}
{
  "type": "tool_result",
  "name": "web.search",
  "results": [
    {
      "rank": 1,
      "title": "Breach Notification Rule | HHS.gov",
      "url": "https://www.hhs.gov/hipaa/for-professionals/breach-notification/index.html",
      "snippet": "The HIPAA Breach Notification Rule, 45 CFR §§ 164.400-414, requires HIPAA covered entities and their business associates to provide notification following a breach of unsecured protected health information.",
      "domain": "hhs.gov",
      "publishedDate": "2023-11-15",
      "retrievedTimestamp": "2026-05-16T14:22:01Z"
    },
    {
      "rank": 2,
      "title": "Breach Notification — CMS",
      "url": "https://www.cms.gov/priorities/key-initiatives/burden-reduction/administrative-simplification/hipaa/breach-notification",
      "snippet": "Covered entities must notify affected individuals, HHS, and in some cases the media, of a breach of unsecured PHI.",
      "domain": "cms.gov",
      "publishedDate": null,
      "retrievedTimestamp": "2026-05-16T14:22:01Z"
    }
  ]
}
```

## Error codes

| Code                             | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `RETRIEVAL_DISABLED`             | Web retrieval is not enabled for this org.                               |
| `RETRIEVAL_PHI_BLOCKED`          | PHI was detected in the query and `phi_retrieval_behavior=block` is set. |
| `RETRIEVAL_PROVIDER_UNAVAILABLE` | The upstream search provider returned an error or timed out.             |

See [Errors](/ai-api/reference/errors) for the full error envelope shape.