> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# News search
> Google News and Bing News search through SerpApi. Runs one original-query leg per country per engine (up to max_legs per engine), merges canonical article URLs and preserves all source provenance. No LLM angle expansion, translation, AI reranking or SSE. query_source=fallback_original is explicit. Google ISO publish timestamps are exact; Bing relative timestamps are approximate. Undated and out-of-window rows are omitted. Story judgments return null with stories_unavailable unless disabled. Google supports 35 configured editions; Bing supports 33. A country parameter selects the edition, not a geographic article filter. Results are bounded windows, not an exhaustive feed. A persistent shared 30-search allowance protects the existing free provider tier; paid capacity is not configured.
Search Google News and Bing News using one original query per selected country and engine. For example, `query=artificial intelligence&engines=google,bing&countries=US&depth=20` reserves at most **7 credits**: two base, one Google leg, and at most four for twenty Bing articles. The final charge settles to actual returned work. Empty/failed legs cost zero; an entirely empty result costs zero. Cached responses, idempotent replays and failures are free.
The provider configuration contains **35 Google editions and 33 Bing markets**. Both engines support: US, GB, AU, CA, NZ, ZA, IN, AR, CL, MX, ES, BR, AT, DE, BE, NL, FR, CH, IT, DK, FI, NO, SE, PL, RU, TR, JP, KR, HK, TW, ID, MY, PH. Google also supports IE and SG. The country/language describes the searched edition, not detected article language or where an event happened. Only US and GB are included in this release's live acceptance fixtures; the other configured markets are not individually certified.
Each `items[]` row has a headline, canonical URL, publisher, optional snippet/image, publication date and engine/country provenance. Duplicate URLs are merged without losing their source records. Google ISO dates are tagged `exact`; Bing relative dates are tagged `approximate`. Undated articles are omitted rather than assigned invented dates. Google typically has fewer snippets.
* `depth`: 10–100 in steps of ten, default ten; Bing caps at twenty.
* `max_legs`: 1–12 per engine, default twelve; skipped countries are disclosed. No hidden pages or retries.
* `sort=date`: newest first among the retrieved windows. `relevance` interleaves source ranks.
* `time_range`: 1, 7, 30 or 365 rolling days. Explicit `from`/`to` overrides it.
* `publisher` and exact date bounds: Google only. Publisher must be a bare domain, and subdomains match. Bounds are inclusive; date-only `to` includes the UTC day. Filtering is checked locally as well as in the source query.
`legs[]` shows every selected search's count, status, cost and any failure. Partial success returns `partial_results`; all-failed requests return an uncharged error. `total` and `next_cursor` are null and `complete` is false because these are bounded source windows.
Query expansion, translation, AI ranking, story judgments and news SSE are not implemented. Each leg truthfully uses `query_source=fallback_original`; JSON includes `localization_unavailable`. Default story fields are null with `stories_unavailable`. `judgments=off` omits them unless `group=stories` is explicit. Use JSON, not an event stream.
Uses the existing SerpApi key and free account. A persistent shared 30-search verification ceiling fails closed without automatically resetting or buying capacity. Trials are not a sustained availability guarantee.
## OpenAPI
````yaml GET /search/news
openapi: 3.1.0
info:
title: SocialQuery API
version: '2026-10-09'
description: >-
Documented requests for public-source records. Inspect accepted inputs and
credit amounts, then verify the selected operation before integrating
preview coverage.
servers:
- url: https://socialquery.dev/v1
security:
- apiKey: []
paths:
/search/news:
get:
tags:
- Search
summary: Search News
description: >-
Google News and Bing News search through SerpApi. Runs one
original-query leg per country per engine (up to max_legs per engine),
merges canonical article URLs and preserves all source provenance. No
LLM angle expansion, translation, AI reranking or SSE.
query_source=fallback_original is explicit. Google ISO publish
timestamps are exact; Bing relative timestamps are approximate. Undated
and out-of-window rows are omitted. Story judgments return null with
stories_unavailable unless disabled. Google supports 35 configured
editions; Bing supports 33. A country parameter selects the edition, not
a geographic article filter. Results are bounded windows, not an
exhaustive feed. A persistent shared 30-search allowance protects the
existing free provider tier; paid capacity is not configured.
operationId: get_search_news
parameters:
- name: query
in: query
required: true
example: samsung galaxy launch
schema:
type: string
- name: countries
in: query
required: false
example: KR,US,JP
schema:
type: string
description: >-
CSV of 1–12 unique configured editions (default US): US, GB, AU, CA,
NZ, ZA, IN, IE, SG, AR, CL, MX, ES, BR, AT, DE, BE, NL, FR, CH, IT,
DK, FI, NO, SE, PL, RU, TR, JP, KR, HK, TW, ID, MY, PH. Duplicates
collapse. Bing does not support IE or SG.
- name: engines
in: query
required: false
example: google,bing
schema:
type: string
description: >-
CSV google (default), bing, or both. Each selected country runs one
original-query leg per engine. publisher and from/to require Google
only.
- name: sort
in: query
required: false
example: date
schema:
type: string
enum:
- relevance
- date
description: >-
relevance interleaves the source-ranked windows; date sorts their
returned articles by newest timestamp. This does not request an
exhaustive newest-first crawl.
- name: time_range
in: query
required: false
example: week
schema:
type: string
enum:
- day
- week
- month
- year
description: >-
day, week, month or year; default day. Local rolling bounds are
1/7/30/365 days. Ignored when from/to is supplied. Bing year uses a
source-ranked window with local date filtering.
- name: from
in: query
required: false
example: '2026-07-01'
schema:
type: string
description: >-
Inclusive publication bound, YYYY-MM-DD or Unix seconds. Whole UTC
day for a date-only to. Google only. Local exact timestamp filtering
follows the source date query; undated rows are excluded.
- name: to
in: query
required: false
example: '2026-07-31'
schema:
type: string
description: >-
Inclusive publication bound, YYYY-MM-DD or Unix seconds. Whole UTC
day for a date-only to. Google only. Local exact timestamp filtering
follows the source date query; undated rows are excluded.
- name: publisher
in: query
required: false
example: bbc.com
schema:
type: string
- name: depth
in: query
required: false
example: 10
schema:
type: integer
minimum: 10
maximum: 100
description: >-
Maximum articles returned per leg, 10–100 in steps of ten; default
ten. Bing caps at twenty. Source windows can contain fewer results.
No hidden pagination.
- name: max_legs
in: query
required: false
example: 4
schema:
type: integer
minimum: 1
maximum: 12
description: >-
Cap of 1–12 country legs per engine, default twelve. Countries
beyond the cap are returned in skipped_countries; no angle expansion
occurs.
- name: group
in: query
required: false
schema:
type: string
enum:
- stories
description: >-
stories requests grouping, currently unavailable. stories and
story_grouping remain null with a stories_unavailable warning.
- name: judgments
in: query
required: false
schema:
type: string
enum:
- 'on'
- 'off'
description: >-
on (default) returns null story judgment fields and an unavailable
warning. off omits them, unless group=stories is explicit.
- name: Cache-Control
in: header
required: false
example: no-cache
schema:
type: string
- name: Idempotency-Key
in: header
required: false
example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
schema:
type: string
- name: X-Max-Credits
in: header
required: false
description: >-
Optional nonnegative integer cap on the maximum request hold. A live
request whose hold exceeds this cap returns 422
CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
requested limit; cache hits and successful idempotent replays cost
zero.
schema:
type: integer
minimum: 0
responses:
'200':
description: >-
Google News and Bing News search through SerpApi. Runs one
original-query leg per country per engine (up to max_legs per
engine), merges canonical article URLs and preserves all source
provenance. No LLM angle expansion, translation, AI reranking or
SSE. query_source=fallback_original is explicit. Google ISO publish
timestamps are exact; Bing relative timestamps are approximate.
Undated and out-of-window rows are omitted. Story judgments return
null with stories_unavailable unless disabled. Google supports 35
configured editions; Bing supports 33. A country parameter selects
the edition, not a geographic article filter. Results are bounded
windows, not an exhaustive feed. A persistent shared 30-search
allowance protects the existing free provider tier; paid capacity is
not configured.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SocialQueryResponse'
- type: object
properties:
data:
type: object
properties:
items:
type: array
maxItems: 1440
items:
type: object
properties:
id:
type: string
url:
type: string
canonical_url:
type: string
title:
type: string
snippet:
type:
- string
- 'null'
publisher:
type: string
domain:
type: string
image_url:
type:
- string
- 'null'
published_at:
type: string
published_at_precision:
enum:
- exact
- approximate
engine:
enum:
- google
- bing
country:
type: string
language:
type: string
source_rank:
type: integer
minimum: 0
provenance:
type: array
items:
type: object
properties:
engine:
enum:
- google
- bing
country:
type: string
language:
type: string
rank:
type: integer
minimum: 0
required:
- engine
- country
- language
- rank
additionalProperties: false
required:
- id
- url
- canonical_url
- title
- snippet
- publisher
- domain
- image_url
- published_at
- published_at_precision
- engine
- country
- language
- source_rank
- provenance
additionalProperties: false
returned_count:
type: integer
minimum: 0
total:
type: 'null'
next_cursor:
type: 'null'
complete:
const: false
legs:
type: array
maxItems: 24
items:
type: object
properties:
id:
type: string
engine:
enum:
- google
- bing
country:
type: string
language:
type: string
keyword:
type: string
query_source:
const: fallback_original
depth:
type: integer
minimum: 10
maximum: 100
status:
enum:
- ok
- empty
- failed
error_code:
type:
- string
- 'null'
returned_count:
type: integer
minimum: 0
source_count:
type: integer
minimum: 0
dropped:
type: integer
minimum: 0
deduplicated:
type: integer
minimum: 0
truncated:
type: integer
minimum: 0
credits:
type: integer
minimum: 0
maximum: 4
required:
- id
- engine
- country
- language
- keyword
- query_source
- depth
- status
- error_code
- returned_count
- source_count
- dropped
- deduplicated
- truncated
- credits
additionalProperties: false
planned_legs:
type: integer
minimum: 0
skipped_countries:
type: array
items:
type: string
deduplicated:
type: integer
minimum: 0
dropped:
type: integer
minimum: 0
query:
type: string
planner:
const: original_query_only
_warnings:
type: array
items:
type: string
coverage_note:
type: string
stories:
type: 'null'
story_grouping:
type: 'null'
required:
- items
- returned_count
- total
- next_cursor
- complete
- legs
- planned_legs
- skipped_countries
- deduplicated
- dropped
- query
- planner
- _warnings
- coverage_note
additionalProperties: false
required:
- data
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'422':
$ref: '#/components/responses/Error422'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'502':
$ref: '#/components/responses/Error502'
'503':
$ref: '#/components/responses/Error503'
'504':
$ref: '#/components/responses/Error504'
components:
schemas:
SocialQueryResponse:
type: object
required:
- success
- platform
- endpoint
- credits_used
- credits_remaining
- request_id
- cached
- data
properties:
success:
type: boolean
const: true
platform:
type: string
endpoint:
type: string
credits_used:
type: integer
minimum: 0
credits_remaining:
type:
- integer
- 'null'
request_id:
type: string
cached:
type: boolean
data:
type: object
additionalProperties: true
description: >-
The selected operation determines the resource fields in this
object. Source data can omit a metric or report it as null.
SocialQueryError:
type: object
required:
- success
- platform
- endpoint
- credits_used
- credits_remaining
- request_id
- cached
- error
properties:
success:
type: boolean
const: false
platform:
type: string
endpoint:
type: string
credits_used:
type: integer
minimum: 0
credits_remaining:
type:
- integer
- 'null'
request_id:
type: string
cached:
type: boolean
error:
type: object
required:
- code
- type
- message
- status
- doc_url
properties:
code:
type: string
type:
type: string
message:
type: string
status:
type: integer
doc_url:
type: string
format: uri
responses:
Error400:
description: Upstream rejected the request.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error401:
description: Missing, expired, invalid, or revoked API key.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error402:
description: Insufficient SocialQuery credits.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error403:
description: Key scope or provider policy denied access.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error404:
description: Endpoint or upstream resource not found.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error405:
description: HTTP method is not supported.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error409:
description: Idempotency conflict or request in progress.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error422:
description: Invalid parameters.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error429:
description: Request limit reached.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error500:
description: Request processing failed.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error502:
description: Upstream service failed.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error503:
description: Provider or required service is unavailable.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error504:
description: Upstream service timed out.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.