# You.com Search API clients against SpecStream

Date: 2026-11-10. Client: youdotcom (Python) 3.6.0.

## The one line a user changes

Before:

```
you.search(query=QUERY)  # You(api_key_auth=YDC_API_KEY)
```

After:

```
you.search(query=QUERY, server_url="https://api.specstream.ai/you")  # You(api_key_auth=SPECSTREAM_API_KEY)
```

## Request parameters

Honoured means the check in the Measured column passed on the reply. Accepted, not applied means status 200 and the reply is the search the call runs without the parameter. Refused means the vendor's error status and body.

Counts: 12 honoured, 4 refused, 11 accepted, not applied.

| Parameter | Sent | Verdict | Measured |
|---|---|---|---|
| `query` | `history of the printing press ...` | honoured | status 200; 10 results |
| `count (the SDK's default 10)` | `10` | honoured | status 200; 10 results |
| `count (not sent)` | absent, plain POST | honoured | status 200; 10 results |
| `count` | `3` | honoured | status 200; 3 results |
| `count (over 100)` | `101` | refused | status 422; {"error": "Use a count of 1 to 100."} |
| `offset` | `1` with `count=5` | honoured | status 200; 4 of 5 results not on the offset 0 page |
| `freshness` | `week` | honoured | status 200; the search ran `history of the printing press Spain after:2026-11-03` |
| `freshness` | `2024-01-01to2024-12-31` | honoured | status 200; the search ran `history of the printing press Netherlands after:2024-01-01 before:2024-12-31` |
| `freshness (not a value You.com takes)` | `decade` | refused | status 422; {"error": "Send freshness as day, week, month, year or YYYY-MM-DDtoYYYY-MM-DD."} |
| `include_domains` | `["wikipedia.org"]` | honoured | status 200; 10 of 10 on wikipedia.org |
| `exclude_domains` | `["wikipedia.org"]` | honoured | status 200; 10 of 10 off wikipedia.org |
| `include_domains with exclude_domains` | both | refused | status 422; {"error": "include_domains cannot be combined with exclude_domains or boost_domains."} |
| `extraction (highlights, the SDK's default)` | `{"extraction_mode": "highlights"}` | honoured | status 200; contents.highlights on 5 of 10 results |
| `extraction (full_page)` | `{"extraction_mode": "full_page"}` | accepted, not applied | status 200; contents on 0 of 10 results |
| `boost_domains` | `['wikipedia.org']` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `country` | `US` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `language` | `EN` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `safesearch` | `strict` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `knowledge` | `core` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `livecrawl` | `web` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `livecrawl_formats` | `['markdown']` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `crawl_timeout` | `20` | accepted, not applied | status 200; 10 results, the search the call runs without it |
| `X-API-Key (no key)` | absent | refused | status 401; body {"detail": "Missing API key. Send your SpecStream API key in an X-API-Key header. Get a key at https |
| `query (older form)` | `history of the printing press ...` | honoured | status 200; 10 hits |
| `num_web_results (older form)` | `3` | honoured | status 200; 3 hits |
| `safesearch (older form)` | `strict` | accepted, not applied | status 200; 10 hits, the search the call runs without it |
| `country (older form)` | `US` | accepted, not applied | status 200; 10 hits, the search the call runs without it |

## Response fields

Present means the field holds a value in every reply or result read; present in n of m counts the results that hold one; absent means the reply leaves it out or sends null.

Counts: 14 present, 5 absent.

| Field | State |
|---|---|
| `results.web[].url` | present |
| `results.web[].title` | present |
| `results.web[].description` | present |
| `results.web[].snippets` | present |
| `results.web[].page_age` | present in 37 of 143 |
| `results.web[].contents` | present in 77 of 143 |
| `results.web[].thumbnail_url` | absent |
| `results.web[].favicon_url` | absent |
| `results.news` | absent |
| `results.knowledge` | absent |
| `metadata.search_uuid` | present |
| `metadata.query` | present |
| `metadata.latency` | present |
| `hits[].url (older form)` | present |
| `hits[].title (older form)` | present |
| `hits[].description (older form)` | present |
| `hits[].snippets (older form)` | present |
| `hits[].thumbnail_url (older form)` | absent |
| `latency (older form)` | present |