Skip to main content
POST
Web research

Headers

idempotency-key
string
required

A caller-generated idempotency key (a UUID is recommended). One key binds to one run: a retry with the same key after a network timeout is a read, not a second execution.

Minimum string length: 1

Body

application/json
action
enum<string> | null

Default search. search, news, places, scholar, shopping, images, videos and answer take query; scrape and similar take url.

Available options:
search,
news,
places,
scholar,
shopping,
images,
videos,
answer,
scrape,
similar
provider
enum<string> | null

Data provider: auto (default) or one of serper, serpapi, exa, dataforseo. Name one only when the caller asks for that vendor.

Available options:
auto,
serper,
serpapi,
exa,
dataforseo
query
string | null
Required string length: 1 - 500
url
string | null
Required string length: 1 - 2048
country
string | null

Country for search-type actions, as a two-letter ISO code or a country name. Default us. Not for scrape or similar. Refused with 400 when the named provider cannot apply it.

Required string length: 2 - 60
language
string | null

Language for search-type actions, two letters such as en, de. Not for scrape or similar.

Pattern: ^[A-Za-z]{2}$
limit
integer | null

Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further.

Required range: 1 <= x <= 100

Response

a terminal run: COMPLETED, FAILED or STOPPED

id
string
required
run_url
string
required
provider
string
required
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
required
Pattern: ^\/.+$
endpoint_version
integer
required
status
enum<string>
required
Available options:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
required
input
object
required
output
any
required
provider_response
object | null
required
charge_usd
string | null
required

Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
required
stoppable
boolean
required
stop_requested_at
string<date-time> | null
required

ISO-8601 UTC timestamp

created_at
string<date-time>
required

ISO-8601 UTC timestamp

started_at
string<date-time> | null
required

ISO-8601 UTC timestamp

completed_at
string<date-time> | null
required

ISO-8601 UTC timestamp