# Scrapebento

> Web scraping, search, and grounded research as an API, built for agents.
> Sync-by-default responses, one credit-metered call per operation, automatic
> refunds when a scrape returns nothing.

Base URL: https://api.scrapebento.com
Auth: `Authorization: Bearer <token>` — create a token in the dashboard under API keys.
Keys are `satk_` (live, spends credits) or `satk_test_` (test, spends a self-refilling
125-credit-per-day allowance and never bills). Test keys run the same scrapers against
the same live targets, so they are the right credential for evaluating the API and for CI.

## Start here

- [Quickstart](https://docs.scrapebento.com/quickstart/): working curl examples for the common endpoints.
- [Auth & credits](https://docs.scrapebento.com/auth-and-credits/): live vs test keys, scopes, the 402 path, caching, sync-wait behaviour.
- [Jobs & webhooks](https://docs.scrapebento.com/jobs-and-webhooks/): sync vs async, polling, HMAC signature verification.
- [OpenAPI spec](https://docs.scrapebento.com/openapi/public-api.openapi.yaml): the source of truth for every request and response shape.

## Reference

- [Error codes](https://docs.scrapebento.com/reference/errors/): every code, whether to retry, whether it is refunded.
- [Rate limits](https://docs.scrapebento.com/reference/rate-limits/): per-token buckets and the X-RateLimit-* headers.
- [Credit costs](https://docs.scrapebento.com/reference/credit-costs/): cost per endpoint and per plan.

## Clients

- TypeScript SDK: `npm install @scrapebento/sdk`
- MCP server: https://docs.scrapebento.com/mcp/ — protocol 2026-07-28 over stateless Streamable HTTP; every caller supplies a Bearer token.

## How calls behave

Every metered endpoint runs as a job. A fast one returns `200` with the result
inline; a slow one returns `202` with a `jobId` and `pollUrl`. `research` and
`linkedin/employees` are always asynchronous. Both SDKs hide this and return
the terminal result either way.

A job that ran and failed returns HTTP `200` with `status: "failed"` and a
terminal `error`. Only failures that happen before a job exists use the
top-level `{"error": ...}` envelope.

## Endpoint stability

Every operation carries an `x-stability` label reflecting measured production
success rates, not implementation completeness:

- `ga` — meets its reliability target; safe to build on.
- `beta` — supported, success rate still improving; handle failures.
- `experimental` — unproven or unreliable; not recommended for production, and
  excluded from the MCP tool surface.

Prefer `ga` and `beta` endpoints. The GA set is: HackerNews search and post,
SEO snapshot, infra lookup, and LinkedIn employees. `url`, `search`,
`search/answer`, `research`, `mentions`, `rss`, and `sitemap` are beta.

## Notable behaviour

- Idempotency: send an `Idempotency-Key` header to make a retry return the
  original job instead of creating a second one.
- Caching: slow-moving kinds cache server-side by default. `fresh: true`
  bypasses it; `cacheTtlSec` sets your own window.
- Refunds: automatic for any failure that returned no content. `GET
  /v1/public/usage` reports spend and refunds separately.