stophy

Stophy for TypeScript

The web data layer for AI agents, in TypeScript. Live web data as typed JSON. Search, video, social, jobs, places, property and ads behind one key, with a flat price per call. You pay only for answers that come back. Every method and result is typed.

Install

npm install stophy

Try it without a key

import { Stophy } from "stophy";

const result = await new Stophy().web.search({ query: "bun runtime" });
console.log(result.data.results);

Web search works without a key, with a small free allowance. Every other method throws a StophyError with the code unauthorized.

Use an API key

Get a key from the dashboard. Keys start with st_. Set it as STOPHY_API_KEY, or pass it in:

const stophy = new Stophy({ apiKey: "st_..." });

const videos = await stophy.youtube.search({ query: "bun runtime", limit: 5 });
console.log(videos.data.results);

new Stophy("st_...") works too.

Methods follow the source and the command: stophy.maps.search(...), stophy.reddit.subreddit(...), stophy.ads.search({ network: "meta", ... }). Endpoints with a single name are methods on the client, like stophy.transcript(...).

Every response is { success, data, creditsUsed, requestId }. data is one flat object. Lists are in data.results.

More data

A transcript, Reddit posts, Google Maps reviews, a TikTok profile and Meta ads:

const stophy = new Stophy({ apiKey: "st_..." });

const transcript = await stophy.transcript({ video: "https://youtu.be/dQw4w9WgXcQ", includeTimestamps: true });
console.log(transcript.data.text, transcript.data.segments);

const posts = await stophy.reddit.search({ query: "bun runtime", sort: "top", within: "month" });
console.log(posts.data.results);

const places = await stophy.maps.search({ query: "coffee", location: "Austin, TX", limit: 5 });
const placeId = places.data.results[0]?.placeId;
if (placeId) {
  const reviews = await stophy.maps.reviews({ place: placeId, limit: 20 });
  console.log(reviews.data.results);
}

const profile = await stophy.tiktok.profile({ profile: "tiktok", limit: 5 });
console.log(profile.data.followers, profile.data.results);

const ads = await stophy.ads.search({ network: "meta", query: "running shoes" });
console.log(ads.data.results);

ads.search covers several ad networks. Pick one with network. The types follow the choice.

Get the next page

When there are more results, data.cursor is set. Pass it back to get the next page:

const first = await stophy.reddit.search({ query: "bun" });
const next = await stophy.reddit.search({ query: "bun", cursor: first.data.cursor });

Handle errors

import { StophyError } from "stophy";

try {
  await stophy.reddit.search({ query: "bun" });
} catch (error) {
  if (error instanceof StophyError) {
    console.log(error.code, error.retryable, error.retryAfterSeconds);
  }
}

StophyError has code, message, retryable, retryAfterSeconds, status, and requestId.

The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK throws right away with retryAfterSeconds set.

Options

Option	Default	What it does
apiKey	STOPHY_API_KEY	Your API key
baseUrl	STOPHY_BASE_URL, or the Stophy API	The server to call
maxRetries	2	Retries per request. 0 turns retries off.
timeoutMs	30000	Time limit for each attempt. A timed-out attempt is not retried.

Each method also takes signal to cancel the request.

Check your account

const usage = await stophy.usage();
const logs = await stophy.logs({ days: 7, page: 0 });

usage returns your balance and your all-time usage. logs returns your recent requests. Both need an API key.

License

MIT