API documentation

One endpoint and one op field. Every endpoint shares the same request shape.

Quick start

Want to see what comes back first? Try the Playground. No need to read this page first.

curl -X POST https://widefetch.com/v1/call \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"google.search","params":{"keyword":"vector database"}}'

Authentication

Authorization: Bearer sk_…. Keys are issued in the console and shown in full only once; we store a hash.

Revocation takes effect immediately. If a key leaks, revoke it and issue a new one.

Making a call

POST /v1/call

Field	Type	Description
op	string	The endpoint to call, see the table below
params	object	Parameters for that endpoint

Bounded sync: calls that finish within about 25 seconds return the result directly. Longer ones return status: "running" and a request_id to poll. Browser-based endpoints (executor: browser) take longer more often; http and api ones usually return in a second or two.

{
  "request_id": "req_7Qn1vK…",
  "status": "done",          // done | running | failed
  "outcome": "ok",
  "credits_charged": 1,      // 0 when the call failed
  "timing": {
    "queued_ms": 400,
    "ran_ms": 8100,
    "attempts": 1            // >1 means it was retried
  },
  "result": { "items": [ … ] }
}

Polling

GET /v1/requests/{request_id}

Same response shape as above. Poll every 2 seconds, backing off to 5.

Billing rules

Failed calls are free. Captchas, rate limits, timeouts and unmapped responses are on us and refunded automatically.
Empty results are charged. "Nothing found" is an answer, not a failure, and the cost is already incurred.

Charged outcomes

no_resultsokverified_page

Free outcomes

bad_paramscancelledcaptchaclaim_timeoutneeds_mappingnot_configuredrate_limitedtimeouttransient

Any outcome not listed is free. Charging by default would turn our bugs into your bill.

Endpoints

op	credit	Parameters	Description
brave.search	1	keyword*, limit, region, language	Web search results: title, URL and snippet. Fast, built for many parallel calls.	Try it
github.repo	1	repo*	One GitHub repository: stars, forks, open issues, language, license and topics.	Try it
github.search	1	query*, sort, order, limit	GitHub repository search, sorted by stars, forks or last update.	Try it
google.search	1	keyword*, limit, language, region	Google organic results: title, URL, source domain and snippet.	Try it
google.trends	1	keyword*, region	Google Trends search interest: a weekly series for the past two years (0–100).	Try it
hn.comments	1	keyword*, limit, sort, since	Hacker News comment search: the original text, author and parent story.	Try it
hn.item	1	id*, comments	One Hacker News thread in full: the post text and its comments.	Try it
hn.search	1	keyword*, limit, sort, since, min_points	Hacker News stories: title, link, author, points, comment count and time.	Try it

Error codes

Code	Meaning	What to do
400	Invalid parameters or unknown op	Fix the request. Not charged.
401	Key is wrong or revoked	Use another key
402	Out of credits	Upgrade or wait for the monthly reset
403	This key's allow-list doesn't include the op	Check the `error` field in the response
429	Rate or concurrency limit exceeded	Back off and retry. Not charged.
502	Problem on our side or upstream	Retry. Not charged.

Rate limits

Each key defaults to 60 calls per minute with limited concurrency. Over the limit you get 429, not a queue.

Need more? Get in touch.