# Serply's documented calls on SpecStream

Date: 2026-11-10

Client: requests 2.34.2 (PyPI), Python 3.14.4, as in Serply's own Python example

The one line a user changes:

```python
requests.get("https://api.specstream.ai/serply/v1/search/?q=search+api", headers={"X-Api-Key": SPECSTREAM_KEY})
```

## Request parameters

| Parameter | Sent | Status | Result |
| --- | --- | --- | --- |
| `q` | `q=Larkspur Colorado mayor` | 200 | honoured |
| `q in the path` | `q=Larkspur Colorado mayor` | 200 | honoured |
| `num` | `num=5` | 200 | honoured |
| `num in the path` | `num=5` | 200 | honoured |
| `num=20` | `num=20` | 200 | honoured (10, Serply's ceiling) |
| `start` | `start=10` | 200 | honoured |
| `tbs` | `tbs=qdr:w` | 200 | honoured |
| `gl` | `gl=fr` | 200 | honoured (checked in code: tests/finder/test_dialect_serply.py::test_a_search_in_the_path_is_read_as_its_google_parameters) |
| `hl` | `hl=lang_fr` | 200 | honoured (checked in code: tests/finder/test_dialect_serply.py::test_a_search_in_the_path_is_read_as_its_google_parameters) |
| `lr` | `lr=lang_fr` | 200 | honoured (checked in code: tests/finder/test_dialect_serply.py::test_a_search_in_the_path_is_read_as_its_google_parameters) |
| `cr` | `cr=countryFR` | 200 | honoured (checked in code: tests/finder/test_dialect_serply.py::test_a_search_in_the_path_is_read_as_its_google_parameters) |
| `X-Proxy-Location` |  | 200 | honoured (header X-Proxy-Location: FR; also the search's country) |
| `X-User-Agent` |  | 200 | accepted, not applied (header X-User-Agent: mobile; echoed in device_type) |
| `safe` | `safe=active` | 200 | honoured (checked in code: tests/finder/test_dialect_serply.py::test_a_search_in_the_path_is_read_as_its_google_parameters) |
| `q empty` | `q=` | 400 | refused (no search terms) |
| `X-Api-Key (none)` | `X-Api-Key=` | 401 | refused |

## Response fields

| Field | State |
| --- | --- |
| `results[].title` | present |
| `results[].description` | present |
| `results[].position` | present |
| `results[].realPosition` | present |
| `results[].result_type` | present |
| `results[].metadata.display_url` | present |
| `results[].metadata.attributes` | present |
| `results[].link` | present |
| `ai_overview` | absent |
| `ads` | empty |
| `ads_count` | present |
| `answers` | empty |
| `image_results` | empty |
| `shopping_ads` | empty |
| `places` | empty |
| `local_businesses` | empty |
| `related_searches.text` | empty |
| `related_searches.images` | empty |
| `carousel` | empty |
| `company` | empty |
| `total` | empty |
| `knowledge_graph` | empty |
| `related_questions` | empty |
| `carousel_count` | present |
| `ts` | present |
| `device_region` | empty |
| `device_type` | empty |
| `query` | present |