Skip to main content
POST
Web research
Every action returns normalized output; check result_status for delivery. News, places, scholar, shopping, images, videos and similar expose output.items[] with fixed fields per row; answer exposes output.answer and citations[]. Scrape exposes text, markdown, html, and raw_html; missing formats are null. The Provider’s native output is not repeated in output; it stays on the Run and is readable with Get Run. Glasser does not convert HTML to text or judge semantic quality from wording or length. Search returns output.results[] and supports time_range: day | week | month | year. An empty but valid answer is no_result and keeps the action’s shape: results or items is [], and an empty answer is answer: null with citations: []. Scrape has no empty answer: a page that cannot be delivered is error, with output: null and the reason in error.code. Fetch (scrape) uses Serper then Firecrawl within a default 30-second request budget. HTML or explicit cache-age requests go directly to Firecrawl. X/Twitter and LinkedIn enrichment exclude Firecrawl. A named Provider never falls back. Empty or invalid output, Provider errors, timeout, or missing supported formats can trigger fallback. The delivered content comes from the final Run; content from different captures is not merged. charge_usd totals this response’s runs, including charged failures and empty results, and is null until all Runs settle. The final Run’s lifecycle remains in status; COMPLETED alone does not prove content delivery. For pending work, follow the authenticated result_url to retain normalized output and total charges. Get Run remains native and reports an individual charge. Polling creates no Runs and does not resume fallback. An intentional POST retry uses the same Idempotency-Key and execution parameters, reuses existing Runs, and starts a new request time window. See Provider selection and charges.

​
Output by action

Every field is present on every row; a value the Provider does not report is null. Fields follow the field conventions.
  • published_at is an ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa publishedDate, SerpApi news iso_date). fetched_at is the same format.
  • date_text is Google’s display text exactly as returned. It may be relative to the Run’s completed_at (“3 hours ago”) and is never parsed.
  • search date is deprecated: it holds Google’s display text for Serper and SerpApi and Exa’s raw publishedDate for Exa. Use published_at or date_text.
  • snippet is Google’s short excerpt, or Exa’s extracted highlight for Exa; it is never the full page text.
  • price_text and duration_text are display strings, not parsed; the price currency follows country.
  • rating is Google’s 1–5 star average and reviews is a count. source is a publisher or site name.
  • address is the Provider’s own text; Serper may return only the street line.
  • exa_similarity_score is Exa’s own score, comparable only within one response. Similar leaves out pages from the requested URL’s host.
  • text_character_limit is the character cap Glasser asked the Provider to apply (10000 for Exa); text of exactly that length may be truncated. cached says whether the Provider served the page from its cache.
  • quality is always unverified and will be removed in the next breaking revision.

Headers

​
idempotency-key
string
required

Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run.

Minimum string length: 1

Body

application/json
​
action
enum<string> | null

Default: search.

  • Supply query for search, news, places, scholar, shopping, images, videos, or answer.
  • Supply url for scrape or similar.
Available options:
search,
news,
places,
scholar,
shopping,
images,
videos,
answer,
scrape,
similar
​
provider
enum<string> | null

Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below.

Available options:
auto,
serper,
serpapi,
exa,
dataforseo,
firecrawl
​
query
string | null
Required string length: 1 - 500
​
url
string | null
Required string length: 1 - 2048
​
formats
enum<string>[]

For scrape only. When omitted, use the selected Provider's native default: text for Serper/Exa, markdown for Firecrawl/DataForSEO. Requested formats guide routing and fallback; output exposes fixed text/markdown/html/raw_html fields. html means cleaned HTML; raw_html means original HTML. Auto uses Serper then Firecrawl. HTML requests go directly to Firecrawl. Read result_status and missing_formats for delivery; an unrequested null field is not a partial result. Firecrawl does not supply text; Glasser does not convert HTML to text. X/Twitter and enrichment routes are excluded from Firecrawl.

Required array length: 1 - 4 elements
Available options:
text,
markdown,
html,
raw_html
​
timeout_ms
integer

For scrape only. Default 30000. Execution budget for this API request, including serial fallback. A retry has a new request window and reuses existing Runs through Run idempotency. Firecrawl and Exa use the actual remaining time, reserving settlement and response time; less than 1 second of call time is refused.

Required range: 1000 <= x <= 120000
​
max_charge_usd
string

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])$
​
cache_max_age_seconds
integer

For scrape only. Maximum Provider cache age; 0 requires a live fetch. Routes without this control are excluded. Auto selects Firecrawl (milliseconds); explicit Exa receives whole hours rounded down. Unknown cache/fetch metadata remains null.

Required range: 0 <= x <= 2592000
​
time_range
enum<string>

For search only: restrict results to the past day, week, month, or year using Google's time filter. Omit for any time. Auto uses only Providers that support this filter (Serper and SerpApi). Exa is refused when this field is supplied. This is a search-engine filter, not a verified publication date.

Available options:
day,
week,
month,
year
​
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
​
task_id
string | null

Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them.

​
metadata

Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.

  • Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.
  • Values: strings of 1–500 characters.
  • user_id: your End user's opaque ID, never their email address or name.

Invalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored.

Response

Success

​
id
string
required
​
run_url
string
required

Open this Run in the console. Requires Workspace membership.

​
provider
string
required
Pattern: ^[a-z0-9][a-z0-9-]*$
​
endpoint
string
required
Pattern: ^\/.+$
​
endpoint_version
integer
required
​
status
enum<string>
required

QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status.

Available options:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
​
failure
object | null
required

Why the Run failed. Non-null only when status is FAILED.

​
input
object
required
​
output
object
required

Normalized fields per action. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null.

  • search: results[]: url, title, snippet (Google's excerpt; Exa's extracted highlight for Exa), position, published_at, date_text, date (deprecated)
  • news: items[]: title, url, source, published_at, date_text, snippet
  • places: items[]: name, address (Provider's text; may be the street line only), category, rating (1–5), reviews, phone, website, latitude, longitude, google_cid
  • scholar: items[]: title, url, snippet, publication, year, cited_by, pdf_url
  • shopping: items[]: title, url (Google Shopping page), merchant_url, google_product_id, price_text, seller, rating (1–5), reviews, image_url
  • images: items[]: title, image_url, thumbnail_url, source_url, source, width, height
  • videos: items[]: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url
  • answer: answer, citations[]: url, title, published_at
  • scrape: url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality (deprecated)
  • similar: items[]: url, title, exa_similarity_score, published_at, author

published_at is ISO 8601 UTC and set only from a Provider's machine timestamp. date_text is Google's display text as returned; it may be relative to the Run's completed_at and is never parsed. rating is Google's 1–5 star average; reviews is a count. source is a publisher or site name. exa_similarity_score is Exa's own score and is comparable only within one response.

​
provider_response
object | null
required

Non-null only when status is COMPLETED.

  • For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.
  • For non-2xx responses, error contains the Provider's error body and output is null.

Sensitive fields are removed from both bodies.

​
charge_usd
string | null
required

Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
​
charge_basis
object | null
required

Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge.

​
stoppable
boolean
required

Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch.

​
stop_requested_at
string<date-time> | null
required

When a stop was requested. The Run can still continue if dispatch had already started.

​
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

​
task_id
string | null
required
​
metadata
object
required

Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.

  • Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.
  • Values: strings of 1–500 characters.
  • user_id: your End user's opaque ID, never their email address or name.
​
action
enum<string>
required
Available options:
search,
news,
places,
scholar,
shopping,
images,
videos,
answer,
scrape,
similar
​
result_status
enum<string>
required

Business delivery status, independent of the final Run lifecycle in status. success is not a semantic content-quality verdict.

Available options:
success,
partial,
no_result,
error,
pending
​
missing_formats
enum<string>[]
required
Available options:
text,
markdown,
html,
raw_html
​
error
object | null
required
​
runs
object[]
required
​
result_url
string
required

Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run.