# Stophy

> Give your agents the live web. One API to search the web, read what people say, and look up products, places, jobs and homes.

## Quick start for agents

Most calls cost $0.002. That is $2.00 per 1,000, $1.50 after $100, $1.20 after $500 and $0.90 after $2,000 in top-ups. Errors and empty results cost nothing. Without a key you get the first page only, 10 calls a minute and 50 a day for each IP address.

1. Install the CLI: `curl -fsSL https://stophy.dev/install | bash`
2. Make a first call. It needs no key:

```bash
curl -X POST https://api.stophy.dev/v1/google/search \
  -H "content-type: application/json" \
  -d '{"query":"bun runtime"}'
```

3. When a call returns apiKeyRequired or freeLimit, get a key with `stophy login --browser` and send it as Authorization: Bearer <key>. Your human approves the sign-in in the browser. A new account starts with $10 to spend.

- [Auth guide](https://stophy.dev/auth.md): which calls work without a key, how to get one, how to send it and keep it safe
- [Error codes](https://docs.stophy.dev/api-reference/errors): every code, whether to retry, and what to do next
- [MCP setup](https://docs.stophy.dev/mcp-server): connect Claude Code, Codex, Cursor or any MCP client

**Important notes:**

- Stophy returns data, not written answers. Your agent decides what to do with the data.
- There is nothing to install or host to call the API. You do not run a browser or a crawler.
- Every endpoint is POST https://api.stophy.dev/v1/<source>/<endpoint> with a JSON body.
- A request names things the way responses do. To fetch one video, post or place, send exactly one of its link or id fields, like videoUrl or videoId.
- Every response has the same envelope: { success, data, creditsUsed, requestId }. creditsUsed is what the call cost, in units of $0.002. A list call returns one page in data.results. Send page for the next numbered page, or cursor when the response includes one.
- Send Authorization: Bearer <key>. Search, Web Scrape, Web Parse and Web Map also work without a key, within a free daily limit, first page only.
- Errors say whether to retry. Failed calls cost nothing.
- A few calls cost $0.004. Long lists that come back in one answer cost $0.002 per 10 results, and take limit to return fewer. The catalog shows each endpoint's cost in its `credits` field before you call, where 1 = $0.002 at the base price. Transcripts cost $0.002 when the video has captions, otherwise $0.004 plus $0.002 for every 10 seconds of audio. Instagram transcripts cost $0.002 plus $0.002 for every 30 seconds of audio.

## Product

- [Use cases](https://stophy.dev/#use-cases): five examples of an agent prompt and the answer it builds from Stophy data
- [Pricing](https://stophy.dev/#pricing): $10 free on signup, the price per 1,000 calls and the volume discounts
- [FAQ](https://stophy.dev/#faq): what Stophy does, how a call works, the API and billing
- [About](https://stophy.dev/about): what Stophy is, what it covers and how to reach us

## CLI

- [Stophy CLI](https://docs.stophy.dev/sdks/cli): install with `curl -fsSL https://stophy.dev/install | bash`, then sign in with `stophy login --browser`

## MCP Server

- [MCP server docs](https://docs.stophy.dev/mcp-server): connect Claude Code, Codex, Cursor or any MCP client
- [MCP server](https://mcp.stophy.dev/mcp): remote MCP over streamable HTTP with browser sign-in or an API key, every endpoint
- [MCP server without a key](https://api.stophy.dev/mcp): works without a key for Search, Web Scrape, Web Parse and Web Map, and an API key unlocks every endpoint
- [mcp.json](https://stophy.dev/.well-known/mcp.json): MCP server details and tools

## Skills

- [Agent onboarding](https://stophy.dev/agents/SKILLS.md): how an agent gets set up, picks a path and makes its first call
- [Stophy skills on GitHub](https://github.com/stophydotdev/stophy/tree/main/skills): agent skills that run on the CLI

## Docs

- [Full docs index](https://docs.stophy.dev/llms.txt): every docs page with a summary, for loading the full docs into context
- [API reference](https://docs.stophy.dev/api-reference/introduction): how requests, keys and responses work
- [OpenAPI](https://api.stophy.dev/openapi.json): the full OpenAPI document
- [Web search](https://docs.stophy.dev/sources/web): search the web and news
- [Video](https://docs.stophy.dev/sources/video): YouTube, TikTok and Kick videos, channels, transcripts and comments
- [Social](https://docs.stophy.dev/sources/social): posts, profiles and comments from Reddit, Instagram, LinkedIn and more
- [Places and travel](https://docs.stophy.dev/sources/places-and-travel): Google Maps places and reviews, flights and Tripadvisor
- [Shopping](https://docs.stophy.dev/sources/shopping): Amazon products and prices
- [Apps](https://docs.stophy.dev/sources/apps): App Store and Google Play listings, top charts and reviews
- [Jobs](https://docs.stophy.dev/sources/jobs): LinkedIn, Upwork and Indeed job listings
- [Real estate](https://docs.stophy.dev/sources/real-estate): Zillow, Redfin and Realtor.com listings
- [Ads](https://docs.stophy.dev/sources/ads): public ad libraries from Meta, Google, TikTok and LinkedIn

## SDKs

- [TypeScript SDK](https://docs.stophy.dev/sdks/typescript): `npm install stophy`
- [Python SDK](https://docs.stophy.dev/sdks/python): `pip install stophy`
- [SDK on GitHub](https://github.com/stophydotdev/stophy/tree/main/sdk): source for both SDKs

## Get started

- [Sign up](https://stophy.dev/signup): create an account and an API key

## Pricing

- [Billing](https://docs.stophy.dev/billing): calls cost $2.00 per 1,000, $1.50 after $100, $1.20 after $500 and $0.90 after $2,000 in top-ups, failed calls cost nothing, and every response shows what it cost

## Feedback

- POST https://api.stophy.dev/v1/feedback with your API key to report a problem or suggest a change. Send a category (bug, wrong_data, docs_mismatch, missing_feature, slow or other), a note, and a requestId or a url.

## Pages

- [Stophy](https://stophy.dev/index.md)
- [Changelog](https://stophy.dev/changelog.md)
- [About Stophy](https://stophy.dev/about.md)

## Sources

### Search

- [Search](https://docs.stophy.dev/api-reference/endpoint/search): search the web, news, images, scholarly papers, companies and people in one call

### Scrape

- [Web Scrape](https://docs.stophy.dev/api-reference/endpoint/scrape): scrape any public web page as markdown, HTML, links, a screenshot or JSON

### Extract

- [Web Extract](https://docs.stophy.dev/api-reference/endpoint/extract): pull the fields you name from any public page as JSON, each checked against the page

### browser

- [Browser Task](https://docs.stophy.dev/api-reference/endpoint/browser-task): click through a public website in a real browser to search, filter or fill a form
- [Browser Task Status](https://docs.stophy.dev/api-reference/endpoint/browser-task-status): check a browser task and read its result

### Parse

- [Web Parse](https://docs.stophy.dev/api-reference/endpoint/parse): turn a PDF, Word, Excel, PowerPoint or HTML file into markdown

### Map

- [Web Map](https://docs.stophy.dev/api-reference/endpoint/map): scrape the list of pages on a website

### Crawl

- [Web Crawl Start](https://docs.stophy.dev/api-reference/endpoint/crawl): crawl a website in the background

### Batch

- [Web Batch](https://docs.stophy.dev/api-reference/endpoint/batch-scrape): scrape many pages in the background

## Optional

- [Privacy Policy](https://stophy.dev/privacy.md)
- [Terms of Service](https://stophy.dev/tos.md)