# serpstack's documented calls on SpecStream

Date: 2026-11-10

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

The one line a user changes:

```python
requests.get("https://api.specstream.ai/serpstack/search", {"access_key": SPECSTREAM_KEY, "query": "mcdonalds"})
```

## Request parameters

| Parameter | Sent | Status | Result |
| --- | --- | --- | --- |
| `query` | `query=Larkspur Colorado mayor` | 200 | honoured |
| `num` | `num=5` | 200 | honoured |
| `page` | `page=2` | 200 | honoured |
| `period` | `period=last_week` | 200 | honoured |
| `period=custom` | `period=custom`, `period_start=2025-01-01`, `period_end=2025-06-30` | 200 | honoured |
| `gl` | `gl=fr` | 200 | honoured (checked in code: tests/finder/test_dialect_serpstack.py::test_language_country_and_safe_search_reach_the_search) |
| `hl` | `hl=fr` | 200 | honoured (checked in code: tests/finder/test_dialect_serpstack.py::test_language_country_and_safe_search_reach_the_search) |
| `safe` | `safe=1` | 200 | honoured (checked in code: tests/finder/test_dialect_serpstack.py::test_language_country_and_safe_search_reach_the_search) |
| `type=news` | `type=news` | 200 | honoured |
| `sort` | `type=news`, `sort=date` | 200 | honoured (news is newest first) |
| `engine` | `engine=google` | 200 | accepted, not applied |
| `type=web` | `type=web` | 200 | accepted, not applied |
| `device` | `device=mobile` | 200 | accepted, not applied |
| `location` | `location=New York` | 200 | accepted, not applied |
| `auto_location` | `auto_location=0` | 200 | accepted, not applied |
| `google_domain` | `google_domain=google.co.uk` | 200 | accepted, not applied |
| `news_type` | `type=news`, `news_type=blogs` | 200 | accepted, not applied |
| `exclude_autocorrected_results` | `exclude_autocorrected_results=1` | 200 | accepted, not applied |
| `output` | `output=csv` | 200 | accepted, not applied (the reply is JSON) |
| `csv_fields` | `csv_fields=organic_results.title` | 200 | accepted, not applied |
| `type=images` | `type=images` | 400 | refused (image results, error 314) |
| `engine=bing` | `engine=bing` | 400 | refused (error 311) |
| `period=soon` | `period=soon` | 400 | refused (error 316, as serpstack answers) |
| `pagination.next_page_url` | `page=2` | 200 | honoured |
| `access_key (none)` | `access_key=` | 401 | refused |

## Response fields

| Field | State |
| --- | --- |
| `request.success` | present |
| `request.processed_timestamp` | present |
| `request.search_url` | absent |
| `request.total_time_taken` | present |
| `search_parameters.engine` | present |
| `search_parameters.query` | present |
| `search_parameters.type` | present |
| `search_parameters.device` | absent |
| `search_parameters.google_domain` | absent |
| `search_parameters.hl` | absent |
| `search_parameters.gl` | absent |
| `search_parameters.page` | present |
| `search_parameters.num` | present |
| `search_information.total_results` | present |
| `search_information.time_taken_displayed` | present |
| `search_information.did_you_mean` | absent |
| `search_information.showing_results_for` | absent |
| `search_information.query_displayed` | present |
| `search_information.detected_location` | absent |
| `search_information.no_results_for_original_query` | present |
| `organic_results[].position` | present |
| `organic_results[].title` | present |
| `organic_results[].url` | present |
| `organic_results[].domain` | present |
| `organic_results[].displayed_url` | present |
| `organic_results[].snippet` | present |
| `organic_results[].sitelinks` | absent |
| `organic_results[].cached_page_url` | absent |
| `organic_results[].related_pages_url` | absent |
| `organic_results[].prerender` | absent |
| `organic_results[].rich_snippet` | absent |
| `news_results[].position` | present |
| `news_results[].title` | present |
| `news_results[].url` | present |
| `news_results[].source_name` | present |
| `news_results[].uploaded` | present |
| `news_results[].uploaded_utc` | present |
| `news_results[].snippet` | present |
| `news_results[].thumbnail_url` | absent |
| `pagination.current_page` | present |
| `pagination.next_page_url` | present |
| `pagination.other_page_urls` | present |
| `ads` | absent |
| `answer_box` | absent |
| `knowledge_graph` | absent |
| `local_results` | absent |
| `related_questions` | absent |
| `related_searches` | absent |
| `inline_images` | absent |
| `top_stories` | absent |