---
name: stophy
description: Query the web's major platforms (search, video, social, maps, shopping, jobs, real estate and more) through one API. Use when a task needs data from the web, when you need a Stophy API key, or when an API call to api.stophy.dev returned 401.
---

# Stophy

Stophy is a web scraping API for AI agents. Every response has the same envelope. You can use it from a CLI, a remote MCP server, TypeScript and Python SDKs, or plain REST.

Human docs: https://docs.stophy.dev

## Rules for this setup

- **Reuse what already works.** If `stophy status` shows you are signed in, `STOPHY_API_KEY` is set, or a Stophy MCP connection already answers, skip that step.
- **Do only what was asked.** If your human asked for the MCP server only, do not install the CLI, and the reverse.
- **Run every check yourself.** Ask your human for one thing only: approving a sign-in in the browser.
- **A step is done when its check passes.** Each step below names its check. A command that ran without an error is not a check.
- **Report one status per surface.** Say ready or pending for the CLI, the MCP connection and the SDK separately. For anything pending, name the one step that is left, then carry on with the rest.

What does not carry over:

- Signing in to the MCP server in the browser does not sign in the CLI, and signing in to the CLI does not connect an MCP client.
- Installing the skills does not create an API key.
- An MCP server in your client's config is not proof that this session has its tools. Call a tool to check.

## Install

Run this once. It installs the CLI, installs every Stophy skill for all your agents, and opens the browser so your human can approve the sign-in:

```bash
npx -y @stophy/cli@latest init --all --browser
```

To do the steps yourself:

```bash
npm install -g @stophy/cli
npx skills add stophydotdev/skills
stophy login --browser
```

## Verify the install

```bash
stophy status
stophy web search "bun runtime"
```

`stophy status` shows the CLI version, whether you are signed in, and your balance. The search must print results.

Done when `stophy status` shows you are signed in and the search prints at least one result with a URL. If it fails, run `stophy doctor`. A 401 means you have no key yet. Read the next section.

## Get credentials

There are two ways to get an API key. Pick the first one that fits.

1. **CLI browser login.** Run `stophy login --browser`. Your human approves in the browser and the key is stored for you. Use this when you can run commands and your human can open a link.
2. **Dashboard.** Your human signs up at https://stophy.dev/signup, creates a key at https://stophy.dev/api-keys and gives it to you. Use this when your human wants to do it themselves.

Store the key as `STOPHY_API_KEY`, for example in `.env` or your client's secret settings. Never print the key, log it, or commit it. If you already have a key, run `stophy login --api-key <key>` to store it for the CLI.

## How you might arrive

- **From the docs or the site.** A page sent you here. Pick a path below.
- **From a 401.** An API call to `https://api.stophy.dev` returned 401. You need a key. Use path D.
- **From a direct URL.** Someone gave you this file. Pick a path below.
- **With a key already set.** `STOPHY_API_KEY` is in your environment. Skip to path A or B.

## Choose your path

- **A.** You need web data during this session. Use the CLI or the MCP server.
- **B.** You are adding Stophy to app code. Use the TypeScript or Python SDK.
- **C.** You want your agent to do a workflow well. Install the skills.
- **D.** You need an API key. Get one.
- **E.** You have nothing installed and want to call the API. Use REST.
- **F.** You have no key and no human to ask. Use the keyless endpoints.

### A. Get web data now

```bash
stophy endpoints youtube
stophy describe youtube.search
stophy youtube search "rust async runtime"
```

`stophy endpoints <term>` finds endpoints and shows what each costs. `stophy describe <id>` shows the options and an example. `stophy <source> --help` lists what a source can do.

If your client supports remote MCP, connect to `https://mcp.stophy.dev/mcp` instead. With an API key you get every endpoint. Claude Code:

```bash
claude mcp add --transport http stophy https://mcp.stophy.dev/mcp --header "Authorization: Bearer $STOPHY_API_KEY"
```

If your human can sign in through the browser, use the sign-in URL instead of a key. Run `/mcp` in Claude Code and choose Authenticate:

```bash
claude mcp add --transport http stophy https://mcp.stophy.dev/mcp
```

Done when a call to `stophy_search_endpoints` returns matches in the session you will work in.

You get these tools:

- `stophy_search_endpoints` `{ query?, category? }` finds endpoints from plain words, such as "restaurant reviews" or "freelance jobs". It returns the best matches with id, title, source, description, required inputs, credit cost, whether it works without a key, its main result fields, and, where endpoints overlap, a one-line hint to help you pick. It never returns an empty list. When nothing matches well it returns the closest endpoints and the list of sources. Ids are camelCase, such as `redditSearch`.
- `stophy_describe_endpoint` `{ id }` returns the required inputs, the optional filters, a working example, the result fields, the cost, whether it pages, and which endpoints open its results (for example a Reddit search result opens `redditPost` with its `postUrl`).
- `stophy_call` `{ id, input?, fields? }` runs it and returns the response with `creditsUsed` and `requestId`. Send `fields`, a list of keys such as `["title", "authorName"]`, to keep only those keys on each result row.

Add `?toolsets=reddit,youtube` to the URL to also get one tool per endpoint of those sources.

### B. Add Stophy to app code

TypeScript:

```bash
npm install stophy
```

```ts
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const { data, creditsUsed } = await stophy.web.search({ query: "bun runtime" });
```

Python:

```bash
pip install stophy
```

```python
import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])
result = stophy.web.search(query="bun runtime")
data = result["data"]
```

Done when the snippet prints data and `creditsUsed`.

Methods follow the endpoint path, so `/v1/linkedin/jobs/search` is `stophy.linkedin.jobs.search(...)`. The SDKs read `STOPHY_API_KEY` from the environment when you pass no key. Read the key from the environment. Never put it in code.

### C. Use skills for a workflow

Skills teach your agent how to use each source well. `init --all` already installed them. To install them alone:

```bash
npx skills add stophydotdev/skills
```

Then use the skill that matches the task. See Skill routing below.

### D. Get an API key

Follow Get credentials above.

### E. Use REST with nothing installed

```bash
curl -X POST https://api.stophy.dev/v1/youtube/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"rust async runtime"}'
```

List every endpoint with its input schema and cost:

```bash
curl https://api.stophy.dev/v1/endpoints
```

### F. No key and no human

These endpoints work without a key:

- Google search
- Google News
- Google suggestions
- Google Patents
- Google ad library search
- YouTube search
- YouTube video details
- YouTube channels
- YouTube comments
- Video transcripts, for YouTube videos
- TikTok profiles
- Video transcripts, for TikTok videos that have captions
- Reddit search
- Google Maps places
- Google Maps reviews
- App Store reviews
- Google Play reviews
- Pinterest pins
- X profiles
- X posts

Without a key a free daily limit applies, and you get the first page only. A call with `cursor`, or with `page` above 1, is refused with a message that says to get a key. Every other endpoint needs a key.

Use this as a fallback. When your human can sign in, follow Get credentials, which removes these limits.

Done when the call below returns `"success": true`.

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

## Skill routing

Use the skill that matches the task:

- **stophy-web:** web search, news, and finding and verifying email addresses.
- **stophy-video:** YouTube and TikTok videos, channels, transcripts and comments.
- **stophy-social:** posts, profiles and comments from Reddit, Instagram, LinkedIn and more.
- **stophy-places:** Google Maps places and reviews, flights and Tripadvisor.
- **stophy-shopping:** Amazon products and prices.
- **stophy-apps:** App Store and Google Play listings, top charts and reviews.
- **stophy-jobs:** LinkedIn, Upwork and Indeed job listings.
- **stophy-real-estate:** Zillow listings.
- **stophy-ads:** public ad libraries from Meta, Google, TikTok and LinkedIn.

## Default workflow

1. Find the endpoint. Run `stophy endpoints <term>`, call `stophy_search_endpoints` with plain words, or read `GET https://api.stophy.dev/v1/endpoints`.
2. Read its schema. Run `stophy describe <id>` or call `stophy_describe_endpoint`. It shows the required inputs, filters and an example. Unknown fields are rejected.
3. Call it with only the fields the schema lists.
4. Page. When the result has a `cursor`, call again with the same input and that `cursor`.

## Reference

**Base URL and auth.** Every endpoint is `POST https://api.stophy.dev/v1/<source>/<endpoint>` with a JSON body. Send `Authorization: Bearer <key>`.

**Find endpoints.** `GET https://api.stophy.dev/v1/endpoints` lists every endpoint with its input JSON schema, its credit cost, whether it works without a key, and an example input when there is one. Read the schema before you call. Unknown fields are rejected. An endpoint that takes one thing by link or id has two fields named like the response, such as `videoUrl` and `videoId`: send exactly one. The full OpenAPI document is at `https://api.stophy.dev/openapi.json`.

**Responses.** Success is `{ "success": true, "data": ..., "creditsUsed": n, "requestId": "..." }`. `data` is one flat object: lists are `data.results` with `page` or `cursor` for the next page, and related values carry their owner in the name, such as `channelName` or `authorUrl`. Errors are `{ "success": false, "error": { "code", "message", "retryable", "retryAfterSeconds"?, "requestId" } }`.

**Errors and retry.** Retry only when `retryable` is true. Wait for `Retry-After` or `retryAfterSeconds` first when present. A 401 means the key is missing or wrong. A 402 means you are out of credits. A 429 means slow down. A 404 or 400 from a site says what was missing or wrong and what to do next, often the endpoint to call instead.

**Paging.** Each call returns one page, as the site shows it, at one flat price. When an endpoint takes `page`, send the same input with `page: 2` for the next page. An empty `results` list means there are no more matches. When a response has a `cursor`, send the same input again with that `cursor`. There is no `limit`; through MCP, `fields` keeps only the keys you need.

**Limits.** With a key: 600 requests a minute and 10 requests running at once. Every call answers or fails within 25 seconds.

**Credits.** 1,000 credits cost $0.80 to $1.50, less on bigger top-ups. Most calls cost 1 credit and a few cost 2. Long lists that come back in one answer, like top charts and image search, cost 1 credit per 10 results, and take `limit` to return fewer. The price is listed in `/v1/endpoints`. The `x-credits-used` header and `creditsUsed` show what a call cost. Errors and empty results cost nothing. Email calls are charged only when they return a valid email. A 402 response also has `requiredCredits`, `availableCredits`, and `billingUrl`.

## Links

- Docs index for agents: https://docs.stophy.dev/llms.txt
- API reference: https://docs.stophy.dev/api-reference/introduction
- Endpoint catalog: https://api.stophy.dev/v1/endpoints
- OpenAPI: https://api.stophy.dev/openapi.json
- Skills on GitHub: https://github.com/stophydotdev/skills
- SDKs on GitHub: https://github.com/stophydotdev/sdk
- MCP server docs: https://docs.stophy.dev/mcp-server