# Advanced guide
Source: https://docs.stophy.dev/advanced-guide

What to learn after your first Stophy call. Find the right endpoint, page through results, and handle errors and retries.

Three guides take you past your first call.

> **[Find an endpoint](/guides/find-endpoint)**
>
> Search the catalog by keyword, or browse it by category.

> **[Page through results](/guides/paging)**
>
> Send the next `page`, or the `cursor` from the last response.

> **[Errors and retries](/guides/errors-and-retries)**
>
> Read the error code and retry only when it is safe.

Every endpoint is a `POST` to `https://api.stophy.dev/v1/` and its id with dots as slashes. `google.search` is `/v1/google/search`. Send a JSON body and your key as a bearer token.

The [API reference](/api-reference/introduction) has each endpoint's inputs and outputs.


# Build with AI
Source: https://docs.stophy.dev/ai-onboarding

Set up an AI agent with Stophy. Get a key, connect the MCP server, and give it agents.md, llms.txt and the live endpoint catalog.

Give your agent [stophy.dev/agents.md](https://stophy.dev/agents.md). It says how to pick an endpoint and add Stophy to your project.

## Connect over MCP

```bash theme={null}
claude mcp add --transport http stophy https://api.stophy.dev/mcp
```

The free endpoints work right away. Add your key as a bearer token to use every endpoint, or sign in with your browser at `https://mcp.stophy.dev/mcp`.

> **[MCP server](/mcp-server)**
>
> Set up Codex, Claude Code, Cursor, OpenCode or another client.

## Get a key

Sign up in the [dashboard](https://stophy.dev/signup), create a key, and save it as `STOPHY_API_KEY`. Send it with every API request.

## Your agent harness

> **[Codex](/quickstarts/codex)**
>
> Add Stophy to Codex.

> **[Claude Code](/quickstarts/claude-code)**
>
> Add Stophy to Claude Code.

> **[Cursor](/quickstarts/cursor)**
>
> Add Stophy to Cursor.

> **[Claude Desktop](/quickstarts/claude-desktop)**
>
> Add Stophy to Claude Desktop.

OpenCode setup is in [MCP without a key or with one](/mcp-server/keyless).

## Your LLM SDK

> **[OpenAI](/developer-guides/llm-sdks/openai)**
>
> Call Stophy from an OpenAI tool.

> **[Anthropic](/developer-guides/llm-sdks/anthropic)**
>
> Call Stophy from a Claude tool.

> **[Vercel AI SDK](/developer-guides/llm-sdks/vercel-ai-sdk)**
>
> Use Stophy with the AI SDK.

> **[Resources for agents](/resources)**
>
> agents.md, llms.txt, the OpenAPI document and the endpoint catalog.


# Airbnb airbnb Listing API
Source: https://docs.stophy.dev/api-reference/endpoint/airbnb-listing

api-reference/openapi.json POST /v1/airbnb/listing
Scrape an Airbnb listing's details, host, amenities, ratings and price. Call the Airbnb airbnb Listing API for JSON. 1 credit per call.

Scrape an Airbnb listing's details, host, amenities, ratings and price. The listing is identified by its URL or ID.

## Request

Exactly one of `listingUrl` or `listingId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.airbnb.listing({ listingId: "53888412" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.airbnb.listing(listing_id="53888412")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/airbnb/listing \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"listingId":"53888412"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy airbnb listing --listingId 53888412
```

## Response

If successful, the response body contains the standard envelope. `data` contains the listing's details, host, rooms, amenities, ratings and price.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "listingId": "53888412",
    "listingUrl": "https://www.airbnb.com/rooms/53888412",
    "title": "Alfama - Historic Center II",
    "description": "This small and charming apartament fully restored, offers a wonderful view over the old rooftops of Alfama, the most…",
    "propertyType": "Entire rental unit",
    "location": "Lisbon, Portugal",
    "latitude": 38.71262,
    "longitude": -9.12979,
    "hostName": "António",
    "hostIsSuperhost": true,
    "guests": 2,
    "bedrooms": 1,
    "beds": 1,
    "bathrooms": 1,
    "amenities": ["Hair dryer"],
    "rating": 4.88,
    "reviews": 337,
    "isGuestFavorite": true,
    "ratingAccuracy": 4.86,
    "ratingCheckin": 4.89,
    "ratingCleanliness": 4.97,
    "ratingCommunication": 4.98,
    "ratingLocation": 4.8,
    "ratingValue": 4.78,
    "houseRules": ["Check-in after 3:00 PM"],
    "imageUrls": ["https://a0.muscache.com/im/pictures/168469e6-3f70-44d9-b4d2-850195140c0c.jpg"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | Number of reviews Airbnb shows for the stay, the same as total in [Airbnb airbnb Reviews](/api-reference/endpoint/airbnb-reviews). A room in a larger property shares the property's reviews. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `checkIn` | string (date) | First night, as YYYY-MM-DD. Send it with `checkOut` to get the price. Format: `YYYY-MM-DD`. |
| `checkOut` | string (date) | Day you leave, as YYYY-MM-DD. Send it with `checkIn` to get the price. Format: `YYYY-MM-DD`. |
| `guests` | integer | Number of guests. Only stays that fit this many. Must be between 1 and 16. If unset, defaults to `1`. |
| `currency` | string | Currency of every price in the answer and of `minPrice` and `maxPrice`. Acceptable values are `USD`, `EUR`, `GBP`, `JPY`, `CAD`, `AUD`, `CHF`, `MXN` and `BRL`. If unset, defaults to `USD`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Airbnb airbnb Reviews](/api-reference/endpoint/airbnb-reviews): Accepts `listingUrl`. Scrape an Airbnb listing's guest reviews.


# Airbnb airbnb Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/airbnb-reviews

api-reference/openapi.json POST /v1/airbnb/reviews
Scrape an Airbnb listing's guest reviews. Call the Airbnb airbnb Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an Airbnb listing's guest reviews. The listing is identified by its URL or ID.

## Request

Exactly one of `listingUrl` or `listingId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.airbnb.reviews({ listingId: "53888412" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.airbnb.reviews(listing_id="53888412")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/airbnb/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"listingId":"53888412"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy airbnb reviews --listingId 53888412
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the listing's reviews, each with its rating, text and date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "listingId": "53888412",
    "total": 337,
    "results": [
      {
        "reviewId": "1785576510399038758",
        "rating": 5,
        "text": "Très bel appartement. Très bien localisé au cœur du quartier Alfama. Endroit parfait, près des transports et lieux à…",
        "language": "fr",
        "translatedText": "Very nice apartment. Very well located in the heart of the Alfama district. Perfect location, close to public…",
        "createdAt": "2026-09-29T15:01:47.000Z",
        "authorName": "Isabelle",
        "stayNote": "Stayed a few nights"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 200. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 200.

## Related methods

* [Airbnb airbnb Listing](/api-reference/endpoint/airbnb-listing): Accepts `listingId`. Scrape an Airbnb listing's details, host, amenities, ratings and price.


# Airbnb airbnb Search API
Source: https://docs.stophy.dev/api-reference/endpoint/airbnb-search

api-reference/openapi.json POST /v1/airbnb/search
Scrape Airbnb search results with prices. Call the Airbnb airbnb Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Airbnb search results with prices.

## Request

`location`, `checkIn` and `checkOut` are required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.airbnb.search({ location: "Lisbon, Portugal", checkIn: "2026-11-29", checkOut: "2026-12-02", guests: 2, maxPrice: 200, roomType: "entireHome" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.airbnb.search(location="Lisbon, Portugal", check_in="2026-11-29", check_out="2026-12-02", guests=2, max_price=200, room_type="entireHome")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/airbnb/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"location":"Lisbon, Portugal","checkIn":"2026-11-29","checkOut":"2026-12-02","guests":2,"maxPrice":200,"roomType":"entireHome"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy airbnb search --location "Lisbon, Portugal" --checkIn 2026-11-29 --checkOut 2026-12-02 --guests 2 --maxPrice 200 --roomType entireHome
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the stays, each with its total price, price per night, rating and photos.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "location": "Lisbon, Portugal",
    "results": [
      {
        "listingId": "2251675",
        "listingUrl": "https://www.airbnb.com/rooms/2251675",
        "title": "Alfama - Beco do Belo Studio",
        "propertyType": "Apartment",
        "area": "Santa Maria Maior",
        "rating": 4.85,
        "reviews": 651,
        "priceTotal": 321.55,
        "priceBeforeDiscount": 359.81,
        "pricePerNight": 98.22,
        "priceCurrency": "USD",
        "badges": ["Guest favorite"],
        "imageUrls": ["https://a0.muscache.com/im/pictures/hosting/Hosting-U3RheVN1cHBseUxpc3Rpbmc6MjI1MTY3NQ%3D%3D/original/995699a0-d358-4cc…", "https://a0.muscache.com/im/pictures/hosting/Hosting-U3RheVN1cHBseUxpc3Rpbmc6MjI1MTY3NQ%3D%3D/original/25bd02a7-7327-40c…"],
        "latitude": 38.7117,
        "longitude": -9.12667
      }
    ],
    "cursor": "adlnUFS6eyJzZWN0aW9uX29mZnNldCI6MCwiaXRlbXNfb2Zmc2V0IjoxOCwidmVyc2lvbiI6MX0=~179a7970-cffb-43bf-9319-0a7b28091a6a~17916…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | Number of reviews Airbnb shows for the stay, the same as total in [Airbnb airbnb Reviews](/api-reference/endpoint/airbnb-reviews). A room in a larger property shares the property's reviews. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `guests` | integer | Number of guests. Only stays that fit this many. Must be between 1 and 16. If unset, defaults to `1`. |
| `minPrice` | integer | Airbnb's own price range minimum: the nightly price after discounts and before taxes, in currency. |
| `maxPrice` | integer | Airbnb's own price range maximum: the nightly price after discounts and before taxes, in currency. |
| `roomType` | string | Airbnb's own Type of place filter: `entireHome` (Entire home) or `privateRoom` (Room). Acceptable values are `entireHome` and `privateRoom`. |
| `currency` | string | Currency of every price in the answer and of `minPrice` and `maxPrice`. Acceptable values are `USD`, `EUR`, `GBP`, `JPY`, `CAD`, `AUD`, `CHF`, `MXN` and `BRL`. If unset, defaults to `USD`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Airbnb airbnb Listing](/api-reference/endpoint/airbnb-listing): Accepts `listingUrl`. Scrape an Airbnb listing's details, host, amenities, ratings and price.
* [Airbnb airbnb Reviews](/api-reference/endpoint/airbnb-reviews): Accepts `listingUrl`. Scrape an Airbnb listing's guest reviews.


# Amazon amazon Best Sellers API
Source: https://docs.stophy.dev/api-reference/endpoint/amazon-bestsellers

api-reference/openapi.json POST /v1/amazon/bestsellers
Scrape Amazon Best Sellers lists. Call the Amazon amazon Best Sellers API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape Amazon Best Sellers lists.

## Request

`category` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.bestsellers({ category: "electronics" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.bestsellers(category="electronics")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/bestsellers \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"category":"electronics"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy amazon bestsellers electronics
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the best sellers in the category, in rank order.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "category": "Electronics",
    "results": [
      {
        "rank": 1,
        "productId": "B08JHCVHTY",
        "productUrl": "https://www.amazon.com/dp/B08JHCVHTY",
        "title": "blink plus plan with monthly auto-renewal",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/31YHGbJsldL._AC_UL300_SR300,200_.png",
        "price": 11.99,
        "priceCurrency": "USD",
        "rating": 4.4,
        "reviews": 280840
      }
    ],
    "page": 1
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `rank` | integer | The 1-based position of the entry in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 21 values, such as `us`, `gb` and `de`. If unset, defaults to `us`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 2. If unset, defaults to `1`. |

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 2.

## Related methods

* [Amazon amazon Product](/api-reference/endpoint/amazon-product): Accepts `productUrl`. Scrape an Amazon product page.
* [Amazon amazon Reviews](/api-reference/endpoint/amazon-reviews): Accepts `productUrl`. Scrape an Amazon product's US reviews.


# Amazon amazon Product API
Source: https://docs.stophy.dev/api-reference/endpoint/amazon-product

api-reference/openapi.json POST /v1/amazon/product
Scrape an Amazon product page. Call the Amazon amazon Product API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape an Amazon product page. The product is identified by its URL or ID.

## Request

Exactly one of `productUrl` or `productId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.product({ productUrl: "https://www.amazon.com/dp/B0CX23V2ZK" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.product(product_url="https://www.amazon.com/dp/B0CX23V2ZK")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/product \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://www.amazon.com/dp/B0CX23V2ZK"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy amazon product --productUrl https://www.amazon.com/dp/B0CX23V2ZK
```

## Response

If successful, the response body contains the standard envelope. `data` contains the product's price, rating, description points, images, variants and seller.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "productId": "B0HDB41H28",
    "productUrl": "https://www.amazon.com/dp/B0HDB41H28",
    "title": "Wireless Earbuds, Bluetooth 5.3 Headphones HiFi Stereo 50H Playback LED Digital Display Ear Buds with ENC Noise…",
    "brand": "Fhumsh",
    "price": 18.98,
    "originalPrice": 249.99,
    "priceCurrency": "USD",
    "availability": "In Stock",
    "rating": 4.6,
    "reviews": 270,
    "bullets": ["Ergonomic Wireless Earbuds for All-Day Wear:3-size medical-grade gel tips (S/M/L) conform to 99% ear contours,…"],
    "imageUrls": ["https://m.media-amazon.com/images/I/618n7fFdFXL._AC_SL1500_.jpg"],
    "variants": [
      {
        "productId": "B0HDHBQ98Q",
        "options": "Color: Rosegold"
      }
    ],
    "sellerName": "Fhumsh-JW US",
    "sellerId": "A2ZKWS9M1UYYSZ",
    "sellerShipsFrom": "Amazon",
    "categories": ["Electronics"],
    "bestSellersRank": [
      {
        "rank": 48,
        "category": "Electronics"
      }
    ],
    "specs": [
      {
        "name": "Brand",
        "value": "Fhumsh"
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rank` | integer | The product's rank among the best sellers in that category. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 21 values, such as `us`, `gb` and `de`. |

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Amazon amazon Search](/api-reference/endpoint/amazon-search): Accepts the product's `title` as `query`. Scrape Amazon search results.
* [Amazon amazon Reviews](/api-reference/endpoint/amazon-reviews): Accepts `productUrl`. Scrape an Amazon product's US reviews.


# Amazon amazon Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/amazon-reviews

api-reference/openapi.json POST /v1/amazon/reviews
Scrape an Amazon product's US reviews. Call the Amazon amazon Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an Amazon product's US reviews. The product is identified by its URL or ID.

## Request

Exactly one of `productUrl` or `productId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.reviews({ productUrl: "https://www.amazon.com/dp/B0CX23V2ZK" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.reviews(product_url="https://www.amazon.com/dp/B0CX23V2ZK")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://www.amazon.com/dp/B0CX23V2ZK"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy amazon reviews --productUrl https://www.amazon.com/dp/B0CX23V2ZK
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the reviews, each with its rating, text and whether the purchase is verified.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "productId": "B0CX23V2ZK",
    "results": [
      {
        "authorName": "MWW",
        "rating": 1,
        "title": "Trash",
        "text": "Apple has really gone down hill. They will eventually intentionally stop supporting the latest operating system, which…",
        "publishedAt": "2026-07-23T00:00:00.000Z",
        "country": "United States",
        "isVerified": true,
        "isVine": false,
        "helpfulVotes": 0
      }
    ],
    "cursor": "9XB9OW7DMjAyNi0xMC0xOFQyMDowMDo1MC43NDc5NjM0MTRaADEw"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The day the review was written, at midnight UTC. Amazon gives no time of day. |
| `rating` | integer | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Returns Amazon's US reviews newest first, 10 per page and up to 100 for each star rating.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `rating` | integer | Restricts results to reviews with this star rating. Must be between 1 and 5. |
| `verifiedOnly` | boolean | Restricts results to reviews from verified purchases. If unset, defaults to `false`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Amazon amazon Product](/api-reference/endpoint/amazon-product): Accepts `productId`. Scrape an Amazon product page.


# Amazon amazon Search API
Source: https://docs.stophy.dev/api-reference/endpoint/amazon-search

api-reference/openapi.json POST /v1/amazon/search
Scrape Amazon search results. Call the Amazon amazon Search API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape Amazon search results.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.search({ query: "wireless earbuds" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.search(query="wireless earbuds")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"wireless earbuds"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy amazon search "wireless earbuds"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the products, each with its price, rating and review count.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "productId": "B0HDB41H28",
        "productUrl": "https://www.amazon.com/dp/B0HDB41H28",
        "title": "Wireless Earbuds, Bluetooth 5.3 Headphones HiFi Stereo 50H Playback LED Digital Display Ear Buds with ENC Noise…",
        "imageUrl": "https://m.media-amazon.com/images/I/618n7fFdFXL._AC_UY218_.jpg",
        "price": 18.98,
        "originalPrice": 249.99,
        "priceCurrency": "USD",
        "rating": 4.6,
        "reviews": 270,
        "boughtPastMonth": 4000,
        "isSponsored": false
      }
    ],
    "total": 27654,
    "page": 1
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `category` | string | The category to search in, by name or id. |
| `minPrice` | number | The minimum price. |
| `maxPrice` | number | The maximum price. |
| `minRating` | number | Restricts results to products rated at least this high. |
| `brand` | string | Restricts results to products from this brand. |
| `sort` | string | Specifies the order of the products. `avgCustomerReview` puts the highest rated first, not the most reviewed. Acceptable values are `relevance`, `priceLow`, `priceHigh`, `avgCustomerReview`, `newest` and `bestSelling`. If unset, defaults to `relevance`. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 21 values, such as `us`, `gb` and `de`. If unset, defaults to `us`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 20. If unset, defaults to `1`. |

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 20.

## Related methods

* [Amazon amazon Product](/api-reference/endpoint/amazon-product): Accepts `productUrl`. Scrape an Amazon product page.
* [Amazon amazon Reviews](/api-reference/endpoint/amazon-reviews): Accepts `productUrl`. Scrape an Amazon product's US reviews.


# Amazon amazon Suggestions API
Source: https://docs.stophy.dev/api-reference/endpoint/amazon-suggest

api-reference/openapi.json POST /v1/amazon/suggest
Scrape Amazon search suggestions. Call the Amazon amazon Suggestions API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Amazon search suggestions.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.suggest({ query: "best running shoes" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.suggest(query="best running shoes")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/suggest \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best running shoes"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy amazon suggest "best running shoes"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the suggestions, best first.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "keyword": "best running shoes for women",
        "rank": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rank` | integer | The 1-based position of the entry in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 21 values, such as `us`, `ca` and `mx`. If unset, defaults to `us`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Amazon amazon Search](/api-reference/endpoint/amazon-search): Accepts a suggestion as `query`. Scrape Amazon search results.


# App Store app Store App API
Source: https://docs.stophy.dev/api-reference/endpoint/appstore-app

api-reference/openapi.json POST /v1/appstore/app
Scrape an App Store app page. Call the App Store app Store App API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an App Store app page. The app is identified by its URL or ID.

## Request

Exactly one of `appUrl` or `appId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.app({ appId: "284882215" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.app(app_id="284882215")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/app \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"appId":"284882215"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore app --appId 284882215
```

## Response

If successful, the response body contains the standard envelope. `data` contains the app's description, developer, price, ratings, version and screenshots.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "appId": "284882215",
    "appUrl": "https://apps.apple.com/us/app/facebook/id284882215",
    "bundleId": "com.facebook.Facebook",
    "name": "Facebook",
    "subtitle": "Connection starts here",
    "developerId": "284882218",
    "developerName": "Meta Platforms, Inc.",
    "developerUrl": "https://apps.apple.com/us/developer/meta-platforms-inc/id284882218",
    "seller": "Meta Platforms, Inc.",
    "website": "http://www.facebook.com/mobile",
    "price": 0,
    "priceCurrency": "USD",
    "priceText": "Free",
    "hasInAppPurchases": true,
    "genres": ["Social Networking"],
    "primaryGenreId": "6005",
    "primaryGenre": "Social Networking",
    "contentRating": "12+",
    "description": "Where real people propel your curiosity. Whether you’re thrifting gear, showing reels to that group who gets it, or…",
    "releaseNotes": "Our teams have solved many crashes, fixed issues you’ve reported and made the app faster.",
    "version": "581.0.0",
    "releasedAt": "2019-02-05T08:00:00.000Z",
    "updatedAt": "2026-09-30T11:45:51.000Z",
    "minimumOsVersion": "15.1",
    "sizeBytes": 506663936,
    "languages": ["AR"],
    "rating": 4.52602,
    "ratings": 28613672,
    "ratingsOne": 1966781,
    "ratingsTwo": 434356,
    "ratingsThree": 1028701,
    "ratingsFour": 2339531,
    "ratingsFive": 22855070,
    "chartName": "top-free",
    "chartGenre": "Social Networking",
    "chartPosition": 3,
    "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/83/71/5e/83715e23-3e26-c24e-a948-47a168921d0b/Icon-Production-0-0…",
    "screenshotUrls": ["https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/e2/c0/fa/e2c0faf7-2613-0ead-3c3a-193d992e3930/f254967c-6ef9…"],
    "ipadScreenshotUrls": ["https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b1/01/cc/b101cce5-ea5d-e1d4-a038-31060001418e/3d69f402-0570-4aa0-…"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `ratings` | integer | The number of ratings the app has received. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [App Store app Store Reviews](/api-reference/endpoint/appstore-reviews): Accepts `appUrl`. Scrape an App Store app's reviews.


# App Store app Store Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/appstore-reviews

api-reference/openapi.json POST /v1/appstore/reviews
Scrape an App Store app's reviews. Call the App Store app Store Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an App Store app's reviews. The app is identified by its URL or ID.

## Request

Exactly one of `appUrl` or `appId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.reviews({ appId: "284882215", sort: "lowest" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.reviews(app_id="284882215", sort="lowest")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"appId":"284882215","sort":"lowest"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore reviews --appId 284882215 --sort lowest
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the app's reviews.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "reviewId": "14626635924",
        "rating": 1,
        "title": "Junk",
        "text": "Way too many adds, shows more posts from people that i don’t know than the people im friends with. Oh and did i…",
        "authorName": "JmichaelA1981",
        "publishedAt": "2026-10-04T12:57:24.000Z",
        "isEdited": false
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `rating` | integer | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `sort` | string | Specifies which reviews are returned first. Acceptable values are `newest`, `helpful`, `highest` and `lowest`. If unset, defaults to `newest`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 500. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 500.

## Related methods

* [App Store app Store App](/api-reference/endpoint/appstore-app): Accepts the same `appId`. Scrape an App Store app page.


# App Store app Store Search API
Source: https://docs.stophy.dev/api-reference/endpoint/appstore-search

api-reference/openapi.json POST /v1/appstore/search
Scrape App Store search results. Call the App Store app Store Search API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape App Store search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.search({ query: "notes", country: "gb", device: "ipad" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.search(query="notes", country="gb", device="ipad")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"notes","country":"gb","device":"ipad"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore search notes --country gb --device ipad
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the matching apps, each with its developer, price and rating.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "appId": "1110145109",
        "appUrl": "https://apps.apple.com/gb/app/notes/id1110145109",
        "bundleId": "com.apple.mobilenotes",
        "name": "Notes",
        "developerId": "284417353",
        "developerName": "Apple",
        "developerUrl": "https://apps.apple.com/gb/developer/apple/id284417353",
        "seller": "Apple Distribution International",
        "price": 0,
        "priceCurrency": "GBP",
        "priceText": "Free",
        "genres": ["Productivity"],
        "primaryGenreId": "6007",
        "primaryGenre": "Productivity",
        "contentRating": "4+",
        "description": "Notes is the best place to jot down quick thoughts or to save longer notes filled with checklists, images, web links,…",
        "releaseNotes": "Bug Fixes and Feature Enhancements",
        "version": "2.6",
        "releasedAt": "2016-05-23T21:11:44.000Z",
        "updatedAt": "2026-09-14T20:09:43.000Z",
        "minimumOsVersion": "15.0",
        "sizeBytes": 6054912,
        "languages": ["AR", "CA"],
        "rating": 4.78604,
        "ratings": 68400,
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/bc/b1/1c/bcb11c9d-ea61-089f-3b84-0f8911dd175d/notesCalistoga-0-0-…",
        "screenshotUrls": ["https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/04/16/68/041668d9-0672-cb3c-2e98-a9bf013e5594/1_Notes_scree…", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/6e/6f/21/6e6f2140-71b0-4545-6ad6-0e87b1401418/2_Notes_PDF_S…"],
        "ipadScreenshotUrls": ["https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/02/f6/94/02f69477-9ea2-56ee-4fb5-53aea34b17f5/1_Notes_iPad_…", "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/1f/ba/f4/1fbaf44d-ab61-8bdf-647e-999381c5bf74/2_Notes_iPad_…"]
      }
    ]
  },
  "creditsUsed": 5,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `ratings` | integer | The number of ratings the app has received. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `device` | string | The device the apps must run on, iphone, ipad or mac. An `iPhone` app can also run on an `iPad` or a Mac, so it can show under more than one. Acceptable values are `iphone`, `ipad` and `mac`. If unset, defaults to `iphone`. |
| `limit` | integer | The maximum number of apps to return. Billed at 1 credit per 10 returned. Must be between 1 and 50. |

## Billing

A successful request consumes 1 credit per 10 apps, up to 5 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [App Store app Store App](/api-reference/endpoint/appstore-app): Accepts `appUrl`. Scrape an App Store app page.
* [App Store app Store Reviews](/api-reference/endpoint/appstore-reviews): Accepts `appUrl`. Scrape an App Store app's reviews.


# App Store app Store Top Charts API
Source: https://docs.stophy.dev/api-reference/endpoint/appstore-top

api-reference/openapi.json POST /v1/appstore/top
Scrape App Store top charts. Call the App Store app Store Top Charts API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape App Store top charts.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.top({});
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.top()
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/top \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore top
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the apps on the chart, in rank order.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "rank": 1,
        "appId": "6760173601",
        "appUrl": "https://apps.apple.com/us/app/muse-from-meta/id6760173601",
        "bundleId": "com.facebook.hatch",
        "name": "Muse from Meta",
        "developerId": "284882218",
        "developerName": "Meta Platforms, Inc.",
        "developerUrl": "https://apps.apple.com/us/developer/meta-platforms-inc/id284882218",
        "price": 0,
        "priceCurrency": "USD",
        "genreId": "6007",
        "genre": "Productivity",
        "releasedAt": "2026-09-08T07:00:00.000Z",
        "summary": "Muse is your personal AI agent that gets things done, always working on what matters to you. It manages email, books…",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/14/f4/82/14f482a9-e97f-ae33-f898-253dea69396b/HatchAppIconPublic-…"
      }
    ]
  },
  "creditsUsed": 10,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rank` | integer | The 1-based position of the entry in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `chart` | string | Specifies which chart to read. Acceptable values are `free`, `paid` and `grossing`. If unset, defaults to `free`. |
| `device` | string | The device the apps must run on, iphone, ipad or mac. An `iPhone` app can also run on an `iPad` or a Mac, so it can show under more than one. Acceptable values are `iphone`, `ipad` and `mac`. If unset, defaults to `iphone`. |
| `genre` | string | Restricts results to apps in this genre. Accepts one of 24 values, such as `business`, `weather` and `utilities`. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `limit` | integer | The maximum number of apps to return. Billed at 1 credit per 10 returned. Must be between 1 and 100. |

## Billing

A successful request consumes 1 credit per 10 apps, up to 10 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [App Store app Store App](/api-reference/endpoint/appstore-app): Accepts `appUrl`. Scrape an App Store app page.
* [App Store app Store Reviews](/api-reference/endpoint/appstore-reviews): Accepts `appUrl`. Scrape an App Store app's reviews.


# Booking.com booking.com Hotel API
Source: https://docs.stophy.dev/api-reference/endpoint/booking-hotel

api-reference/openapi.json POST /v1/booking/hotel
Scrape a Booking.com hotel page. Call the Booking.com booking.com Hotel API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Booking.com hotel page. The hotel is identified by its URL or ID.

## Request

Exactly one of `hotelUrl` or `hotelId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.booking.hotel({ hotelId: "15781550" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.booking.hotel(hotel_id="15781550")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/booking/hotel \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hotelId":"15781550"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy booking hotel --hotelId 15781550
```

## Response

If successful, the response body contains the standard envelope. `data` contains the hotel's stars, review score, category scores, description and address.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "hotelId": "15781550",
    "hotelUrl": "https://www.booking.com/hotel/pt/olympia-lis-boutique.html",
    "name": "Olympia Lis Baixa Hotel",
    "type": "hotel",
    "stars": 4,
    "reviewScore": 9.6,
    "reviews": 431,
    "description": "Attractively located in the center of Lisbon, Olympia Lis Baixa Hotel has air-conditioned rooms, a restaurant, free…",
    "scores": [
      {
        "category": "Staff",
        "score": 9.9
      }
    ],
    "addressFull": "Rua dos Condes 17, Santa Maria Maior, 1150-110 Lisbon, Portugal",
    "addressStreet": "Rua dos Condes 17",
    "addressCity": "Lisbon",
    "addressCountryCode": "pt",
    "latitude": 38.7166656,
    "longitude": -9.1414034,
    "checkInFrom": "3:00 PM",
    "checkOutUntil": "12:00 PM",
    "facilities": [
      {
        "group": "General",
        "name": "Air conditioning"
      }
    ],
    "rooms": [
      {
        "roomId": "1578155002",
        "name": "Cozy Double Room",
        "sizeSquareMeters": 17,
        "description": "The double room offers air conditioning, soundproof walls, as well as a private bathroom boasting a shower and a…"
      }
    ],
    "imageUrls": ["https://cf.bstatic.com/xdata/images/hotel/max1024x768/894944500.jpg?k=799f689fa4d58b8a56979879db4550c4022f063d3fdcfe8c6…"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `score` | number | Upvotes minus downvotes. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Booking.com booking.com Hotel Reviews](/api-reference/endpoint/booking-hotel-reviews): Accepts `hotelUrl`. Scrape a Booking.com hotel's guest reviews.


# Booking.com booking.com Hotel Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/booking-hotel-reviews

api-reference/openapi.json POST /v1/booking/hotel/reviews
Scrape a Booking.com hotel's guest reviews. Call the Booking.com booking.com Hotel Reviews API for JSON. 1 credit per call.

Scrape a Booking.com hotel's guest reviews. The hotel is identified by its URL or ID.

## Request

Exactly one of `hotelUrl` or `hotelId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.booking.hotel.reviews({ hotelId: "15781550" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.booking.hotel.reviews(hotel_id="15781550")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/booking/hotel/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hotelId":"15781550"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy booking hotel reviews --hotelId 15781550
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the hotel's reviews, each with its score, what the guest liked and disliked, room and dates.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "hotelId": "15781550",
    "total": 431,
    "results": [
      {
        "reviewId": "0b8a3b075c0a095a",
        "score": 10,
        "title": "Très bon séjour",
        "positiveText": "Tout était parfait",
        "negativeText": "L’emplacement \nLa propreté\nLes équipements\nLe personnel",
        "language": "fr",
        "createdAt": "2026-10-10T07:13:54.000Z",
        "travelerType": "Couple",
        "authorCountryCode": "fr",
        "roomName": "Superior Twin Room",
        "nights": 5,
        "checkIn": "2026-10-04",
        "checkOut": "2026-10-09"
      }
    ],
    "cursor": "HqSo8b3qeyJvZmZzZXQiOjI1LCJzZWVuIjpbIjBiOGEzYjA3NWMiLCI0Mzk2YjI2ZDI1IiwiMDY3OGQyZDg3YSIsImJlZTY4MTNkOWIiLCI4NTc5MTdjY2F…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `total` | integer | The total number of matching results, across all pages. |
| `score` | number | Upvotes minus downvotes. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | Booking.com's own Sort reviews by: newest, `mostRelevant` or `lowestScore` (lowest scores first). Only newest pages without gaps. The other orders change between requests, so a walk through the pages can miss reviews. Acceptable values are `newest`, `mostRelevant` and `lowestScore`. If unset, defaults to `newest`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Booking.com booking.com Hotel](/api-reference/endpoint/booking-hotel): Accepts `hotelId`. Scrape a Booking.com hotel page.


# Booking.com booking.com Search API
Source: https://docs.stophy.dev/api-reference/endpoint/booking-search

api-reference/openapi.json POST /v1/booking/search
Scrape Booking.com search results with prices. Call the Booking.com booking.com Search API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Booking.com search results with prices.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.booking.search({ query: "Lisbon", checkIn: "2026-12-02" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.booking.search(query="Lisbon", check_in="2026-12-02")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/booking/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"Lisbon","checkIn":"2026-12-02"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy booking search Lisbon --checkIn 2026-12-02
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the hotels, each with its price, taxes, review score and address.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "place": "Lisbon",
    "checkIn": "2026-11-23",
    "checkOut": "2026-11-24",
    "total": 1886,
    "results": [
      {
        "position": 1,
        "hotelId": "16673871",
        "hotelUrl": "https://www.booking.com/hotel/pt/varandas-da-bica-room.html",
        "name": "Varandas da Bica room",
        "reviewScore": 7.7,
        "reviews": 40,
        "price": 51.39,
        "taxesAndFees": 8.96,
        "originalPrice": 85.65,
        "priceCurrency": "USD",
        "address": "Travessa da Laranjeira 29",
        "city": "Lisboa",
        "countryCode": "pt",
        "area": "Misericordia, Lisbon",
        "distanceText": "0.5 miles from downtown",
        "latitude": 38.7100533,
        "longitude": -9.1465548,
        "imageUrl": "https://cf.bstatic.com/xdata/images/hotel/square600/886948570.jpg?k=86334b99abc0f00afa920678a67992ab39820df3198e0419842…",
        "hasFreeCancellation": false
      }
    ],
    "cursor": "-VNPCx2jeyJvZmZzZXQiOjI1LCJzZWVuIjpbMTY2NzM4NzEsMzk3MTksNDc4MzgsMTIwNjM1MDksNTA4MjUyMywzMTU0NDIsMTI2MzQ3OSwyMDIxMjMxLDE…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `total` | integer | The total number of matching results, across all pages. |
| `position` | integer | The 1-based position of the result in the list. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `checkIn` | string (date) | The check-in date. Defaults to tomorrow. Format: `YYYY-MM-DD`. |
| `checkOut` | string (date) | The check-out date. Defaults to one night after `checkIn`. Format: `YYYY-MM-DD`. |
| `adults` | integer | Adults across all rooms. Prices are for the whole group. Must be between 1 and 30. If unset, defaults to `2`. |
| `rooms` | integer | Rooms to book, at most one per adult. Prices are for all rooms together. Must be between 1 and 30. If unset, defaults to `1`. |
| `currency` | string | Three-letter currency code, such as `USD`. If unset, defaults to `USD`. |
| `sort` | string | Booking.com's own Sort by: relevance (Our top picks) or distance (closest to the center of the place first). Acceptable values are `relevance` and `distance`. If unset, defaults to `relevance`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Booking.com booking.com Hotel](/api-reference/endpoint/booking-hotel): Accepts `hotelUrl`. Scrape a Booking.com hotel page.
* [Booking.com booking.com Hotel Reviews](/api-reference/endpoint/booking-hotel-reviews): Accepts `hotelUrl`. Scrape a Booking.com hotel's guest reviews.


# Company careers careers Job API
Source: https://docs.stophy.dev/api-reference/endpoint/careers-job

api-reference/openapi.json POST /v1/careers/job
Scrape one job from a company's careers page. Call the Company careers careers Job API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape one job from a company's careers page.

## Request

`jobUrl` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.careers.job({ jobUrl: "https://boards.greenhouse.io/figma/jobs/5813967004" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.careers.job(job_url="https://boards.greenhouse.io/figma/jobs/5813967004")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/careers/job \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobUrl":"https://boards.greenhouse.io/figma/jobs/5813967004"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy careers job https://boards.greenhouse.io/figma/jobs/5813967004
```

## Response

If successful, the response body contains the standard envelope. `data` contains the job's title, department, location, description, pay range when the company shows one, and apply link.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "5813967004",
    "jobUrl": "https://boards.greenhouse.io/figma/jobs/5813967004",
    "title": "Distribution Partner Manager",
    "department": "Business Development",
    "location": "San Francisco, CA • New York, NY • United States",
    "publishedAt": "2026-02-28T00:00:43.000Z",
    "updatedAt": "2026-07-22T09:37:08.000Z",
    "description": "Figma is growing our team of passionate creatives and builders on a mission to make design accessible to all. Figma’s…",
    "salaryMin": 140000,
    "salaryMax": 296000,
    "salaryCurrency": "USD",
    "applyUrl": "https://boards.greenhouse.io/figma/jobs/5813967004?gh_jid=5813967004",
    "boardUrl": "https://boards.greenhouse.io/figma"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Company careers careers Jobs](/api-reference/endpoint/careers-jobs): Accepts `boardUrl`. Scrape a company's open jobs from its careers page.


# Company careers careers Jobs API
Source: https://docs.stophy.dev/api-reference/endpoint/careers-jobs

api-reference/openapi.json POST /v1/careers/jobs
Scrape a company's open jobs from its careers page. Call the Company careers careers Jobs API for JSON. 1 credit per call.

Scrape a company's open jobs from its careers page.

## Request

`boardUrl` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.careers.jobs({ boardUrl: "https://boards.greenhouse.io/figma" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.careers.jobs(board_url="https://boards.greenhouse.io/figma")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/careers/jobs \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"boardUrl":"https://boards.greenhouse.io/figma"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy careers jobs https://boards.greenhouse.io/figma
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the company's open jobs, each with its title, department, location and date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "jobId": "5813967004",
        "jobUrl": "https://boards.greenhouse.io/figma/jobs/5813967004",
        "title": "Distribution Partner Manager",
        "department": "Business Development",
        "location": "San Francisco, CA • New York, NY • United States",
        "publishedAt": "2026-02-28T00:00:43.000Z",
        "updatedAt": "2026-07-22T09:37:08.000Z",
        "boardUrl": "https://boards.greenhouse.io/figma"
      }
    ],
    "cursor": "zTzqlR4g20"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

> [!NOTE]
>
> The list can be up to 2 hours old.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Company careers careers Job](/api-reference/endpoint/careers-job): Accepts `jobUrl`. Scrape one job from a company's careers page.


# eBay eBay Item API
Source: https://docs.stophy.dev/api-reference/endpoint/ebay-item

api-reference/openapi.json POST /v1/ebay/item
Scrape an eBay item page. Call the eBay eBay Item API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an eBay item page. The item is identified by its URL or ID.

## Request

Exactly one of `itemUrl` or `itemId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.ebay.item({ itemId: "820221984535" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.ebay.item(item_id="820221984535")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/ebay/item \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"itemId":"820221984535"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy ebay item --itemId 820221984535
```

## Response

If successful, the response body contains the standard envelope. `data` contains the item's price, condition, auction status, brand, model and item specifics.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "itemId": "820221984535",
    "itemUrl": "https://www.ebay.com/itm/820221984535",
    "title": "Nintendo Switch OLED Splatoon 3 Edition Handheld Console Multicolor",
    "price": 5.5,
    "priceCurrency": "USD",
    "condition": "Used",
    "isAuction": true,
    "bids": 3,
    "isEnded": false,
    "isSold": false,
    "isAvailable": true,
    "brand": "Nintendo",
    "model": "Nintendo Switch (OLED Model) Splatoon 3 Edition",
    "specifics": [
      {
        "name": "Brand",
        "value": "Nintendo"
      }
    ],
    "categories": ["Electronics"],
    "sellerName": "Retro Held Games",
    "sellerFeedbackScore": 7656,
    "sellerFeedbackPercent": 99.9,
    "shippingCost": 20,
    "shippingPostalCode": "95119",
    "itemLocation": "San Diego, California, United States",
    "listedAt": "2026-10-09T22:28:48.000Z",
    "imageUrls": ["https://i.ebayimg.com/images/g/mUMAAeSwpvhqxEl6/s-l1600.jpg"],
    "description": "In excellent condition overall! Works great with no issues, includes everything in the photos.\n\nShips Next Business Day!"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# eBay eBay Search API
Source: https://docs.stophy.dev/api-reference/endpoint/ebay-search

api-reference/openapi.json POST /v1/ebay/search
Scrape eBay search results. Call the eBay eBay Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape eBay search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.ebay.search({ query: "nintendo switch oled" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.ebay.search(query="nintendo switch oled")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/ebay/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nintendo switch oled"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy ebay search "nintendo switch oled"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the items, each with its price, shipping cost, total price, condition and location.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "total": 6400,
    "results": [
      {
        "itemId": "326350933758",
        "itemUrl": "https://www.ebay.com/itm/326350933758",
        "title": "Nintendo Switch OLED 64GB White Joy-Con 2021 Newest - Japan Import with US plug",
        "imageUrl": "https://i.ebayimg.com/images/g/Z94AAOSwTTJnQ-Bl/s-l500.jpg",
        "price": 350.99,
        "isPriceHidden": false,
        "priceCurrency": "USD",
        "shippingCost": 0,
        "isPickupOnly": false,
        "totalPrice": 350.99,
        "condition": "Brand New",
        "isAuction": false,
        "hasBestOffer": false,
        "itemLocation": "United States",
        "quantitySold": 71,
        "sellerName": "bestsellerssince1977",
        "sellerFeedbackPercent": 99.7,
        "sellerFeedbackScore": 4800
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `condition` | string | Restricts results to `new` or only `used` items. Acceptable values are `new` and `used`. |
| `auctionsOnly` | boolean | Restricts results to auctions. With sort `endingSoonest` this lists auctions about to end; [eBay eBay Item](/api-reference/endpoint/ebay-item) then returns what each one sold for. If unset, defaults to `false`. |
| `minPrice` | number | The minimum price. |
| `maxPrice` | number | The maximum price. |
| `sort` | string | `priceLow` and `priceHigh` return each page in order of `totalPrice`: price plus shipping to New York 10001. Across pages the order is `eBay`'s, so a listing can belong on the neighbouring page. Listings with no `totalPrice` come last on their page: the price is hidden (`isPriceHidden`), the variation range is outside the price filter, or it is pickup only outside the United States. Acceptable values are `bestMatch`, `priceLow`, `priceHigh` and `endingSoonest`. If unset, defaults to `bestMatch`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.

## Related methods

* [eBay eBay Item](/api-reference/endpoint/ebay-item): Accepts `itemUrl`. Scrape an eBay item page.


# Endpoint catalog API
Source: https://docs.stophy.dev/api-reference/endpoint/endpoints

api-reference/openapi.json GET /v1/endpoints
List every Stophy endpoint with its input schema, credit cost, and whether it works without a key. Use it to pick the right call.

List every endpoint with its cost and input schema.


# Facebook facebook Marketplace Search API
Source: https://docs.stophy.dev/api-reference/endpoint/facebook-marketplace-search

api-reference/openapi.json POST /v1/facebook/marketplace/search
Scrape Facebook Marketplace search results. Call the Facebook facebook Marketplace Search API for JSON. 1 credit per call.

Scrape Facebook Marketplace search results.

## Request

`query` and `location` are required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.facebook.marketplace.search({ query: "bike", location: "Austin, Texas" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.facebook.marketplace.search(query="bike", location="Austin, Texas")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/facebook/marketplace/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"bike","location":"Austin, Texas"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy facebook marketplace search --query bike --location "Austin, Texas"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the listings, each with its title, price, city and photo.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "location": "Austin, Texas",
    "latitude": 30.2677,
    "longitude": -97.7475,
    "results": [
      {
        "listingId": "2057184859004190",
        "listingUrl": "https://www.facebook.com/marketplace/item/2057184859004190/",
        "title": "Bike",
        "price": 120,
        "priceText": "$120",
        "city": "Austin",
        "state": "TX",
        "imageUrl": "https://scontent.fsac1-1.fna.fbcdn.net/v/t39.84726-6/841923752_927136586881159_8879530617452165642_n.jpg?stp=c0.152.261…",
        "publishedAt": "2026-10-09T18:24:37.000Z",
        "isPending": false
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `minPrice` | integer | The minimum price in local currency (e.g., 50). Must be between 0 and 1000000000. |
| `maxPrice` | integer | The maximum price in local currency (e.g., 500). Must be between 0 and 1000000000. |
| `sort` | string | Sort order (newest, `priceLow` or `priceHigh`), relevance by default. Acceptable values are `newest`, `priceLow` and `priceHigh`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Facebook facebook Page API
Source: https://docs.stophy.dev/api-reference/endpoint/facebook-page

api-reference/openapi.json POST /v1/facebook/page
Scrape a public Facebook page's details. Call the Facebook facebook Page API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a public Facebook page's details. The page or user is identified by its URL or username.

## Request

Exactly one of `pageUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.facebook.page({ username: "NASA" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.facebook.page(username="NASA")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/facebook/page \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"NASA"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy facebook page --username NASA
```

## Response

If successful, the response body contains the standard envelope. `data` contains the page's name, category, followers, bio and public contact details.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "pageId": "54971236771",
    "username": "NASA",
    "pageUrl": "https://www.facebook.com/NASA",
    "name": "NASA - National Aeronautics and Space Administration",
    "category": "Government organization",
    "isVerified": true,
    "followers": 28717285,
    "talkingAboutThis": 77407,
    "bio": "Explore the universe and discover our home planet. \nThere's space for everybody. ✨",
    "email": "name@example.com",
    "websites": ["https://www.nasa.gov/nasa-app/"],
    "avatarUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png&cstp…",
    "coverUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.99422-6/809146614_4484013928506139_3181913787670602881_n.png?stp=dst-jpg_tt6…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Facebook facebook Page Posts](/api-reference/endpoint/facebook-page-posts): Accepts `pageUrl`. Scrape a public Facebook page's posts.


# Facebook facebook Page Posts API
Source: https://docs.stophy.dev/api-reference/endpoint/facebook-page-posts

api-reference/openapi.json POST /v1/facebook/page/posts
Scrape a public Facebook page's posts. Call the Facebook facebook Page Posts API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a public Facebook page's posts. The page or user is identified by its URL or username.

## Request

Exactly one of `pageUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.facebook.page.posts({ username: "NASA" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.facebook.page.posts(username="NASA")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/facebook/page/posts \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"NASA"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy facebook page posts --username NASA
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the page's posts, each with its text, media, reactions, comments and shares.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "postId": "1652244896270880",
        "postUrl": "https://www.facebook.com/NASA/posts/pfbid0dPToN66CzcAHGMoaNe3jszH4FfBKvqkE5gogCNJkTxXDPsSGYrGvcVwsLgByyMQQl",
        "text": "Brewing up baby stars ⭐\n\nNASA's James Webb Space Telescope's unique view reveals many previously hidden stars in this…",
        "publishedAt": "2026-10-09T20:54:33.000Z",
        "authorId": "100044561550831",
        "authorName": "NASA - National Aeronautics and Space Administration",
        "authorUrl": "https://www.facebook.com/NASA",
        "media": [
          {
            "type": "photo",
            "url": "https://www.facebook.com/photo.php?fbid=1652244872937549&set=a.416661013162614&type=3",
            "imageUrl": "https://scontent-mia5-1.xx.fbcdn.net/v/t39.30808-6/840103313_1652244876270882_2189477774608873541_n.jpg?stp=dst-jpg_p55…",
            "width": 552,
            "height": 515,
            "altText": "A young star cluster filled with many stars that display Webb’s unique eight-pronged diffraction pattern. At its…"
          }
        ],
        "reactions": {
          "total": 4038,
          "like": 2355,
          "love": 1529,
          "care": 82,
          "haha": 11,
          "wow": 60,
          "sad": 0,
          "angry": 1
        },
        "comments": 76,
        "shares": 436
      }
    ],
    "cursor": "2IyIBTao100044561550831~Cg8Ob3JnYW5pY19jdXJzb3IJAAACREFRSFR0X1R0YktfTWhXbWFmT05xMzd2M0R2MUE3VDBxMmx3ZWFsOUcxTmJHd29SNUJ…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Facebook facebook Post](/api-reference/endpoint/facebook-post): Accepts `postUrl`. Scrape a public Facebook post, reel or video.
* [Facebook facebook Post Comments](/api-reference/endpoint/facebook-post-comments): Accepts `postUrl`. Scrape the comments of a public Facebook post.


# Facebook facebook Post API
Source: https://docs.stophy.dev/api-reference/endpoint/facebook-post

api-reference/openapi.json POST /v1/facebook/post
Scrape a public Facebook post, reel or video. Call the Facebook facebook Post API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a public Facebook post, reel or video. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.facebook.post({ postId: "1652244896270880" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.facebook.post(post_id="1652244896270880")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/facebook/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postId":"1652244896270880"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy facebook post --postId 1652244896270880
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post's text, media, author, reactions, comments and shares.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "1652244896270880",
    "postUrl": "https://www.facebook.com/NASA/posts/pfbid0dPToN66CzcAHGMoaNe3jszH4FfBKvqkE5gogCNJkTxXDPsSGYrGvcVwsLgByyMQQl",
    "text": "Brewing up baby stars ⭐\n\nNASA's James Webb Space Telescope's unique view reveals many previously hidden stars in this…",
    "publishedAt": "2026-10-09T20:54:33.000Z",
    "authorId": "100044561550831",
    "authorName": "NASA - National Aeronautics and Space Administration",
    "authorUrl": "https://www.facebook.com/NASA",
    "media": [
      {
        "type": "photo",
        "url": "https://www.facebook.com/photo/?fbid=1652244872937549&set=a.416661013162614",
        "imageUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.99422-6/841844892_1454330573225436_3520855839134390984_n.png?stp=dst-jpg_tt6…",
        "width": 552,
        "height": 515,
        "altText": "A young star cluster filled with many stars that display Webb’s unique eight-pronged diffraction pattern. At its…"
      }
    ],
    "reactions": {
      "total": 4111,
      "like": 2401,
      "love": 1550,
      "care": 86,
      "haha": 11,
      "wow": 62,
      "sad": 0,
      "angry": 1
    },
    "comments": 79,
    "shares": 443
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The kind of item: `photo` or `video`. |
| `total` | integer | The total number of matching results, across all pages. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Facebook facebook Post Comments](/api-reference/endpoint/facebook-post-comments): Accepts `postUrl`. Scrape the comments of a public Facebook post.


# Facebook facebook Post Comments API
Source: https://docs.stophy.dev/api-reference/endpoint/facebook-post-comments

api-reference/openapi.json POST /v1/facebook/post/comments
Scrape the comments of a public Facebook post. Call the Facebook facebook Post Comments API for JSON. 1 credit per call.

Scrape the comments of a public Facebook post. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.facebook.post.comments({ postId: "1652244896270880" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.facebook.post.comments(post_id="1652244896270880")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/facebook/post/comments \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postId":"1652244896270880"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy facebook post comments --postId 1652244896270880
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the post's comments, each with its author, likes and replies.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "commentId": "1088640414090126",
        "commentUrl": "https://www.facebook.com/NASA/posts/pfbid0dPToN66CzcAHGMoaNe3jszH4FfBKvqkE5gogCNJkTxXDPsSGYrGvcVwsLgByyMQQl?comment_id=…",
        "text": "Those camera filters are a true blessing. These photos are great.",
        "publishedAt": "2026-10-10T11:09:33.000Z",
        "authorId": "pfbid02hBdTdSjh9urvTN8rU5zYe2JwBxpdh1Jsfqo7PNASbM2ksWjpBSDWzyPkyefRvdA2l",
        "authorName": "Dona Rawson",
        "likes": 0,
        "replies": 0
      }
    ],
    "cursor": "hLkxq5-WZmVlZGJhY2s6MTY1MjI0NDg5NjI3MDg4MA==~MToxNzkxNjMwNzE5OgF_dXkdu8GqltoQs4YaAt3ZlvNGZFdhJGh9UfvaTyqUxrTPWLxLinA5nd…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.


# Glassdoor glassdoor Company API
Source: https://docs.stophy.dev/api-reference/endpoint/glassdoor-company

api-reference/openapi.json POST /v1/glassdoor/company
Scrape a Glassdoor company's ratings and details. Call the Glassdoor glassdoor Company API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a Glassdoor company's ratings and details. The company or companyName is identified by its URL, ID or companyName.

## Request

Exactly one of `companyUrl`, `companyId` or `companyName` is required. A request that sets more than one, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.glassdoor.company({ companyName: "Google" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.glassdoor.company(company_name="Google")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/glassdoor/company \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyName":"Google"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy glassdoor company --companyName Google
```

## Response

If successful, the response body contains the standard envelope. `data` contains the company's ratings, size, industry and headquarters.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyId": "9079",
    "companyUrl": "https://www.glassdoor.com/Overview/Working-at-Google-EI_IE9079.11,17.htm",
    "name": "Google",
    "rating": 4.4,
    "reviews": 71507,
    "cultureRating": 4.2,
    "workLifeBalanceRating": 4.2,
    "payRating": 4.5,
    "managementRating": 3.9,
    "careerOpportunitiesRating": 4.2,
    "recommendPercent": 88,
    "ceoApprovalPercent": 84,
    "size": "10000+ Employees",
    "industry": "Internet & Web Services",
    "headquarters": "Mountain View, CA",
    "website": "https://goo.gle/4ehVuXi"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | Reviews in every language. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Glassdoor glassdoor Company Reviews](/api-reference/endpoint/glassdoor-company-reviews): Accepts `companyUrl`. Scrape a Glassdoor company's employee reviews.
* [Glassdoor glassdoor Company Salaries](/api-reference/endpoint/glassdoor-company-salaries): Accepts `companyUrl`. Scrape a Glassdoor company's salaries by job title.


# Glassdoor glassdoor Company Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/glassdoor-company-reviews

api-reference/openapi.json POST /v1/glassdoor/company/reviews
Scrape a Glassdoor company's employee reviews. Call the Glassdoor glassdoor Company Reviews API for JSON. 1 credit per call.

Scrape a Glassdoor company's employee reviews. The company is identified by its URL or ID.

## Request

Exactly one of `companyUrl` or `companyId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.glassdoor.company.reviews({ companyId: "9079" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.glassdoor.company.reviews(company_id="9079")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/glassdoor/company/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyId":"9079"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy glassdoor company reviews --companyId 9079
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the reviews, each with its rating, pros, cons and the reviewer's job title.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyId": "9079",
    "total": 66022,
    "totalAllLanguages": 71507,
    "results": [
      {
        "reviewId": "106005473",
        "rating": 5,
        "title": "Good place to work at",
        "pros": "Pay and benefits are good, WLB is good.",
        "cons": "Some bureaucracy, report chain is long.",
        "jobTitle": "Software Engineer",
        "location": "Waterloo, ON",
        "employmentStatus": "regular",
        "createdDate": "2026-10-17"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | Reviews written in English. These are the ones this endpoint lists. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 500. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 500.

## Related methods

* [Glassdoor glassdoor Company](/api-reference/endpoint/glassdoor-company): Accepts `companyId`. Scrape a Glassdoor company's ratings and details.
* [Glassdoor glassdoor Company Salaries](/api-reference/endpoint/glassdoor-company-salaries): Accepts `companyId`. Scrape a Glassdoor company's salaries by job title.


# Glassdoor glassdoor Company Salaries API
Source: https://docs.stophy.dev/api-reference/endpoint/glassdoor-company-salaries

api-reference/openapi.json POST /v1/glassdoor/company/salaries
Scrape a Glassdoor company's salaries by job title. Call the Glassdoor glassdoor Company Salaries API for JSON. 1 credit per call.

Scrape a Glassdoor company's salaries by job title. The company is identified by its URL or ID.

## Request

Exactly one of `companyUrl` or `companyId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.glassdoor.company.salaries({ companyId: "9079" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.glassdoor.company.salaries(company_id="9079")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/glassdoor/company/salaries \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyId":"9079"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy glassdoor company salaries --companyId 9079
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains pay by job title, with the low, median and high total and base pay.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyId": "9079",
    "country": "United States",
    "total": 9187,
    "results": [
      {
        "jobTitle": "Software Engineer",
        "reports": 51206,
        "totalPayMin": 251389,
        "totalPayMedian": 311696,
        "totalPayMax": 396274,
        "basePayMin": 156159,
        "basePayMedian": 184723,
        "basePayMax": 218512,
        "payCurrency": "USD",
        "payPeriod": "year"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | Job titles with pay reports in this country. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | Country the pay is reported for, as its English name like India or Germany. Defaults to the United States. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.

## Related methods

* [Glassdoor glassdoor Company](/api-reference/endpoint/glassdoor-company): Accepts `companyId`. Scrape a Glassdoor company's ratings and details.
* [Glassdoor glassdoor Company Reviews](/api-reference/endpoint/glassdoor-company-reviews): Accepts `companyId`. Scrape a Glassdoor company's employee reviews.


# Google google Ad API
Source: https://docs.stophy.dev/api-reference/endpoint/google-ads-ad

api-reference/openapi.json POST /v1/google/ads/ad
Scrape a Google ad's details. Call the Google google Ad API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Google ad's details. The ad is identified by its URL or ID.

## Request

Exactly one of `adUrl` or `adId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.ad({ adUrl: "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.ad(ad_url="https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"adUrl":"https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google ads ad --adUrl https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR12345678901234567890
```

## Response

If successful, the response body contains the standard envelope. `data` contains the ad's advertiser, format and creative, and the countries it ran in.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "adId": "CR00462730911658541057",
    "adUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR00462730911658541057",
    "advertiserId": "AR16735076323512287233",
    "advertiserName": "Nike, Inc.",
    "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233",
    "format": "text",
    "lastShownAt": "2026-10-05T20:27:35.000Z",
    "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/5743239130676952852",
    "advertiserCountry": "US",
    "advertiserIsVerified": true,
    "paidBy": "Nike, Inc.",
    "variations": [
      {
        "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/5743239130676952852"
      }
    ],
    "regions": [
      {
        "country": "US",
        "lastShownAt": "2026-09-01T00:00:00.000Z"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `lastShownAt` | string (ISO 8601) | The last day Google shows the ad in this country, as the start of that day in UTC. |
| `paidBy` | string | The entity that paid for the ad. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `advertiserId` | string | Advertiser id, such as `AR18378488041124659201`. Requires `adId`. A link already has it. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google ads search](/api-reference/endpoint/google-ads-search): Accepts the `advertiserId` as `advertiser`. Scrape ads from the Google ads library.


# Google google Ads Advertisers API
Source: https://docs.stophy.dev/api-reference/endpoint/google-ads-advertisers

api-reference/openapi.json POST /v1/google/ads/advertisers
Scrape advertisers from the Google ads library. Call the Google google Ads Advertisers API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape advertisers from the Google ads library.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.advertisers({ query: "nike" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.advertisers(query="nike")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/ads/advertisers \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google ads advertisers nike
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the advertisers that match, each with a range for how many ads it runs.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "advertiserId": "AR06641858037806006273",
        "advertiserName": "Nike",
        "advertiserCountry": "KE",
        "advertiserUrl": "https://adstransparency.google.com/advertiser/AR06641858037806006273",
        "isVerified": false,
        "adsMin": 1,
        "adsMax": 1
      }
    ],
    "domains": ["nike.sk"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `adsMin` | integer | With `adsMax`, the range for how many ads the advertiser runs. |
| `domains` | string\[] | Domains that match the query. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | Country code like de. Advertisers are matched on ads shown in this country, wherever the advertiser is based, and `adsMin` and `adsMax` count only the ads shown there. |
| `limit` | integer | The number of advertisers to ask Google for, 1 to 100. Google ranks the list for the count you ask, so a larger limit is not the same list with more rows added, and there are no further pages. Fewer come back when Google has fewer matches. Must be between 1 and 100. If unset, defaults to `10`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google ads search](/api-reference/endpoint/google-ads-search): Accepts an `advertiserId` as `advertiser`, or a domain from `domains` as `domain`,. Scrape ads from the Google ads library.


# Google google Ads Search API
Source: https://docs.stophy.dev/api-reference/endpoint/google-ads-search

api-reference/openapi.json POST /v1/google/ads/search
Scrape ads from the Google ads library. Call the Google google Ads Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape ads from the Google ads library.

## Request

At least one of `query`, `advertiser` or `domain` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.search({ domain: "nike.com" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.search(domain="nike.com")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"nike.com"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google ads search --domain nike.com
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the ads, each with its advertiser and the days it ran.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "CR00462730911658541057",
        "adUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR00462730911658541057",
        "advertiserId": "AR16735076323512287233",
        "advertiserName": "Nike, Inc.",
        "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233",
        "domain": "nike.com",
        "format": "text",
        "firstShownAt": "2022-11-30T14:47:52.000Z",
        "lastShownAt": "2026-10-05T20:27:35.000Z",
        "daysShown": 1350,
        "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/5743239130676952852"
      }
    ],
    "totalMin": 100000,
    "totalMax": 200000,
    "cursor": "CgoAP7zmi4ohfCUHEhBNRhEc0rwv/RRMIVUAAAAAGgn8+Ghj+Osc6yI="
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `totalMin` | integer | With `totalMax`, the range for the number of matching ads. |
| `firstShownAt` | string (ISO 8601) | When Google first showed the ad. |
| `lastShownAt` | string (ISO 8601) | The last day the ad was shown. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | A domain such as `nike.com`. |
| `advertiser` | string | An advertiser id from Google ads advertisers. |
| `domain` | string | A domain such as `nike.com`. |
| `country` | string | Two-letter country code, such as `de`. Only ads shown there are returned. |
| `mediaType` | string | Restricts results to ads of this type. Acceptable values are `text`, `image` and `video`. |
| `platform` | string | Google's own Platform filter: where the ad was shown. Google leaves out ads shown before 4 September 2023 when it is set. Acceptable values are `search`, `youtube`, `play`, `maps` and `shopping`. |
| `shownFrom` | string (date) | Restricts results to ads shown on or after this day. Format: `YYYY-MM-DD`. |
| `shownTo` | string (date) | Restricts results to ads shown on or before this day. Format: `YYYY-MM-DD`. |
| `cursor` | string | The pagination token from the previous response. |

> [!NOTE]
>
> The Google ad library does not support keyword search. To search by advertiser name, first resolve the advertiser ID with [Google advertisers](/api-reference/endpoint/google-ads-advertisers).

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Google ads search](/api-reference/endpoint/google-ads-search): Accepts an `advertiserId` as `advertiser`. Scrape ads from the Google ads library.
* [Google ad details](/api-reference/endpoint/google-ads-ad): Accepts `adUrl`. Scrape a Google ad's details.


# Google google Flights API
Source: https://docs.stophy.dev/api-reference/endpoint/google-flights

api-reference/openapi.json POST /v1/google/flights
Scrape Google Flights results with prices and times. Call the Google google Flights API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Google Flights results with prices and times.

## Request

`origin`, `destination` and `departDate` are required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.flights({ origin: "JFK", destination: "LAX", departDate: "2026-12-02" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.flights(origin="JFK", destination="LAX", depart_date="2026-12-02")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/flights \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"origin":"JFK","destination":"LAX","departDate":"2026-12-02"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google flights --origin JFK --destination LAX --departDate 2026-12-02
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the flight options, each with its price, airlines, stops, times and legs.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "cabin": "economy",
    "tripType": "oneWay",
    "adults": 1,
    "results": [
      {
        "isBest": true,
        "price": 139,
        "priceCurrency": "USD",
        "airlines": ["JetBlue"],
        "stops": 1,
        "durationSeconds": 40440,
        "departureLocalTime": "2026-11-19T15:45",
        "arrivalLocalTime": "2026-11-19T23:59",
        "legs": [
          {
            "flightNumber": "B6 618",
            "airline": "JetBlue",
            "originCode": "JFK",
            "originName": "John F. Kennedy International Airport",
            "destinationCode": "BOS",
            "destinationName": "Boston Logan International Airport",
            "departureLocalTime": "2026-11-19T15:45",
            "arrivalLocalTime": "2026-11-19T17:03",
            "durationSeconds": 4680,
            "aircraft": "Airbus A220-300 Passenger",
            "legroom": "32 inches"
          }
        ],
        "layovers": [
          {
            "airport": "BOS",
            "name": "Boston Logan International Airport",
            "city": "Boston",
            "durationSeconds": 12360
          }
        ],
        "emissionsGrams": 478000,
        "typicalEmissionsGrams": 320000
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `price` | number | Total fare in USD for all adults together. For a round trip it covers both directions. |
| `legs` | object\[] | The outbound journey only, including a return search. |
| `departureLocalTime` | string | Local time at the airport, YYYY-MM-DDTHH:mm, no time zone. |
| `isBest` | boolean | `true` for the options Google marks as best. |
| `durationSeconds` | integer | The duration, in seconds. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `returnDate` | string | The return date. Leave it out for a one-way trip. Format: `YYYY-MM-DD`. |
| `adults` | integer | The number of adults. Must be between 1 and 9. If unset, defaults to `1`. |
| `cabin` | string | The cabin class. Acceptable values are `economy`, `premiumEconomy`, `business` and `first`. If unset, defaults to `economy`. |
| `stops` | string | The number of stops to allow. Acceptable values are `any`, `nonstop`, `oneStopOrFewer` and `twoStopsOrFewer`. If unset, defaults to `any`. |
| `airlines` | string\[] | Restricts results to these airlines, as codes such as `KQ` or `EK`. Accepts up to 10 values. |
| `carryOnBags` | integer | Include this many carry-on bags in the price. Must be between 0 and 1. If unset, defaults to `0`. |
| `checkedBags` | integer | Include this many checked bags in the price. Must be between 0 and 2. If unset, defaults to `0`. |
| `maxPrice` | integer | The maximum price, in USD, for all adults. |
| `departureTime` | object | Limit the outbound departure to these hours of the day. An object with `earliest` and `latest`, each an hour from 0 to 24. |
| `arrivalTime` | object | Limit the outbound arrival to these hours of the day. An object with `earliest` and `latest`, each an hour from 0 to 24. |
| `maxDurationHours` | integer | Longest trip, in hours. Must be between 1 and 48. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Hotels](/api-reference/endpoint/google-hotels): Accepts a leg's `destinationName` as `query`. Scrape Google Hotels results with prices and ratings.


# Google google Hotels API
Source: https://docs.stophy.dev/api-reference/endpoint/google-hotels

api-reference/openapi.json POST /v1/google/hotels
Scrape Google Hotels results with prices and ratings. Call the Google google Hotels API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Google Hotels results with prices and ratings.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.hotels({ query: "Lisbon", checkIn: "2026-12-02" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.hotels(query="Lisbon", check_in="2026-12-02")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/hotels \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"Lisbon","checkIn":"2026-12-02"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google hotels Lisbon --checkIn 2026-12-02
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the hotels, each with its price per night, total price, rating and amenities.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "checkIn": "2026-11-19",
    "checkOut": "2026-11-20",
    "results": [
      {
        "name": "Santa Luzia BB - HOrigem - Double Room, River View",
        "hotelId": "ChkQicjQ0reM7_U9Gg0vZy8xMXo0Y25fNDlzEAI",
        "hotelUrl": "https://www.google.com/travel/hotels/entity/ChkQicjQ0reM7_U9Gg0vZy8xMXo0Y25fNDlzEAI?hl=en&gl=us&curr=USD&ts=CAESCgoCCAM…",
        "price": 76,
        "totalPrice": 80,
        "priceCurrency": "USD",
        "rating": 5,
        "reviews": 8,
        "amenities": ["Sleeps 2", "7 bedrooms"],
        "position": 1
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `price` | number | The minimum price per night. |
| `totalPrice` | number | For the whole stay, with taxes and fees. |
| `page` | string | The page number of this response. |
| `position` | integer | The 1-based position of the result in the list. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `checkIn` | string (date) | The check-in date. Defaults to tomorrow. Format: `YYYY-MM-DD`. |
| `checkOut` | string (date) | The check-out date. Defaults to one night after `checkIn`. Format: `YYYY-MM-DD`. |
| `adults` | integer | The number of adults. Must be between 1 and 12. If unset, defaults to `2`. |
| `childrenAges` | integer\[] | One age for each child, such as `[7, 12]`. Accepts up to 8 values. |
| `currency` | string | Three-letter currency code, such as `USD`. If unset, defaults to `USD`. |
| `minPrice` | integer | The minimum price per night. |
| `maxPrice` | integer | The maximum price per night. |
| `minRating` | string | Restricts results to hotels with at least this guest rating. Acceptable values are `3.5+`, `4+` and `4.5+`. |
| `hotelClass` | integer\[] | Restricts results to hotels with these star ratings, such as `[4, 5]`. Accepts up to 4 values. |
| `amenities` | string\[] | Restricts results to hotels that offer every one of these. Accepts one of 19 values, such as `freeWifi`, `freeBreakfast` and `restaurant`. |
| `propertyTypes` | string\[] | Restricts results to these kinds of property. Acceptable values are `beachHotels`, `boutiqueHotels`, `hostels`, `inns`, `motels`, `resorts`, `spaHotels`, `bedAndBreakfasts`, `other` and `apartmentHotels`. |
| `freeCancellation` | boolean | Restricts results to hotels that offer free cancellation. If unset, defaults to `false`. |
| `specialOffers` | boolean | Restricts results to hotels with special offers. If unset, defaults to `false`. |
| `sort` | string | Specifies the order of the hotels. Acceptable values are `relevance`, `lowestPrice`, `highestRating` and `mostReviewed`. If unset, defaults to `relevance`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Tripadvisor tripadvisor Search](/api-reference/endpoint/tripadvisor-search): Accepts a hotel's `name` as `query`. Scrape Tripadvisor search results.


# Google google Images API
Source: https://docs.stophy.dev/api-reference/endpoint/google-images

api-reference/openapi.json POST /v1/google/images
Scrape Google Images results. Call the Google google Images API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape Google Images results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.images({ query: "golden retriever puppy" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.images(query="golden retriever puppy")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/images \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"golden retriever puppy"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google images "golden retriever puppy"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the images, each with its full-size link and the page it comes from.

The following example is illustrative.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "imageUrl": "https://images.example.com/golden-retriever-puppy.jpg",
        "title": "Golden retriever puppy in the grass",
        "pageUrl": "https://www.example.com/dog-breeds/golden-retriever",
        "source": "example.com",
        "width": 1600,
        "height": 1067,
        "thumbnailUrl": "https://images.example.com/thumbs/golden-retriever-puppy.jpg",
        "position": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `position` | integer | The 1-based position of the result in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `language` | string | The language of the results, as a two-letter ISO 639-1 code such as `en`. |
| `size` | string | Restricts results to images of this size. Acceptable values are `large`, `medium` and `icon`. |
| `type` | string | The kind of image. Acceptable values are `clipArt`, `lineDrawing` and `gif`. |
| `time` | string | Restricts results to images from this period. Acceptable values are `past24Hours` and `pastWeek`. |
| `usageRights` | string | Restricts results to images with this license. Acceptable values are `creativeCommons` and `commercial`. |
| `limit` | integer | The maximum number of images to return. Billed at 1 credit per 10 returned. Must be between 1 and 100. |

## Billing

A successful request consumes 1 credit per 10 images, up to 10 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Google google Maps Place API
Source: https://docs.stophy.dev/api-reference/endpoint/google-maps-place

api-reference/openapi.json POST /v1/google/maps/place
Scrape a Google Maps place's details. Call the Google google Maps Place API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Google Maps place's details. The place is identified by its URL or ID.

## Request

Exactly one of `placeUrl` or `placeId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.maps.place({ placeId: "ChIJN1t_tDeuEmsRUsoyG83frY4" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.maps.place(place_id="ChIJN1t_tDeuEmsRUsoyG83frY4")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/maps/place \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"placeId":"ChIJN1t_tDeuEmsRUsoyG83frY4"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google maps place --placeId ChIJN1t_tDeuEmsRUsoyG83frY4
```

## Response

If successful, the response body contains the standard envelope. `data` contains the place's address, rating, hours and contact details.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "placeId": "0x865b33ee6a9856e5:0x5064d03fde124e36",
    "googlePlaceId": "ChIJ5VaYau4zW4YRNk4S3j_QZFA",
    "placeUrl": "https://www.google.com/maps?cid=5792983993432559158",
    "name": "Mojo Coffee Lakeline",
    "categories": ["Coffee shop"],
    "address": "12206 Ranch Rd 620 N, Austin, TX 78750",
    "latitude": 30.462303,
    "longitude": -97.817188,
    "rating": 4.7,
    "photos": 268,
    "phone": "+1 555 0100",
    "website": "http://www.mojodrivethru.com/",
    "description": "Mojo Coffee - Where Love Brews",
    "hours": [
      {
        "days": "Monday",
        "times": ["5:30 AM–8 PM"]
      }
    ],
    "hoursToday": "5:30 AM–8 PM",
    "openStatus": "Open · Closes 8 PM",
    "timezone": "America/Chicago",
    "plusCode": "8624F56M+W4",
    "thumbnailUrl": "https://lh3.googleusercontent.com/gps-cs-s/ANWiy9T_f8uieZ56cfKjTf64azsc12ETycEiGzT98fcYD0nQ-7CkNIabcVnorFv2IXcDxlYvhOER…",
    "attributes": ["Wheelchair accessible entrance"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `openStatus` | string | The current opening status, as displayed by Google. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Maps Reviews](/api-reference/endpoint/google-maps-reviews): Accepts `placeUrl`. Scrape a Google Maps place's reviews.


# Google google Maps Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/google-maps-reviews

api-reference/openapi.json POST /v1/google/maps/reviews
Scrape a Google Maps place's reviews. Call the Google google Maps Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Google Maps place's reviews. The place is identified by its URL or ID.

## Request

Exactly one of `placeUrl` or `placeId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.maps.reviews({ placeId: "ChIJN1t_tDeuEmsRUsoyG83frY4" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.maps.reviews(place_id="ChIJN1t_tDeuEmsRUsoyG83frY4")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/maps/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"placeId":"ChIJN1t_tDeuEmsRUsoyG83frY4"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google maps reviews --placeId ChIJN1t_tDeuEmsRUsoyG83frY4
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the reviews, each with its rating, date and author.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "reviewId": "Ci9DQUlRQUNvZENodHljRjlvT2xReFMxQjFNSEpwUnpkSVJUbDZTelZTYjJZNFRGRRAB",
        "reviewUrl": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2xReFMxQjFNSEpwUnpkSVJUbDZTelZTYj…",
        "rating": 5,
        "publishedAt": "2026-09-24T19:49:30.325Z",
        "authorName": "Alton Moore",
        "authorUrl": "https://www.google.com/maps/contrib/108868827445789346381/reviews?hl=en-CA",
        "authorAvatarUrl": "https://lh3.googleusercontent.com/a-/ALV-UjW4AifL23vbwfQfHWPbxzK6Y4w41VSQL1Ky8g_wpkE0JY4IwyS1tQ=s64-c-rp-mo-ba12-br100",
        "authorReviews": 9,
        "authorPhotos": 50,
        "authorIsLocalGuide": true,
        "details": [
          {
            "label": "Food",
            "rating": 5
          }
        ],
        "ownerReplyText": "Thank you for your 5-star review!",
        "ownerReplyAt": "2026-09-28T20:46:54.000Z"
      }
    ],
    "cursor": "CjEIARIpCgoAP72F_57WE0__EhATtqsDjOaMQiv7QAQAAAAAGgn92p0CX_ntYTQYACIA"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `rating` | integer | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | Specifies which reviews are returned first. Acceptable values are `relevance`, `newest`, `highest` and `lowest`. If unset, defaults to `newest`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Google google Maps Place](/api-reference/endpoint/google-maps-place): Accepts the same `placeUrl`. Scrape a Google Maps place's details.


# Google google Maps Search API
Source: https://docs.stophy.dev/api-reference/endpoint/google-maps-search

api-reference/openapi.json POST /v1/google/maps/search
Scrape Google Maps search results. Call the Google google Maps Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google Maps search results.

## Request

`query` and `location` are required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.maps.search({ query: "coffee", location: "Austin, TX", openNow: true });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.maps.search(query="coffee", location="Austin, TX", open_now=True)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/maps/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"coffee","location":"Austin, TX","openNow":true}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google maps search --query coffee --location "Austin, TX" --openNow
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the places, each with its rating, address, contact details and opening hours.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "placeId": "0x865b33ee6a9856e5:0x5064d03fde124e36",
        "googlePlaceId": "ChIJ5VaYau4zW4YRNk4S3j_QZFA",
        "placeUrl": "https://www.google.com/maps?cid=5792983993432559158",
        "name": "Mojo Coffee Lakeline",
        "categories": ["Coffee shop"],
        "address": "12206 Ranch Rd 620 N, Austin, TX 78750",
        "latitude": 30.462303,
        "longitude": -97.817188,
        "rating": 4.7,
        "reviews": 679,
        "photos": 268,
        "phone": "+1 555 0100",
        "website": "http://www.mojodrivethru.com/",
        "hours": [
          {
            "days": "Monday",
            "times": ["5:30 AM–8 PM"]
          }
        ],
        "hoursToday": "5:30 AM–8 PM",
        "openStatus": "Open · Closes 8 PM",
        "timezone": "America/Chicago",
        "thumbnailUrl": "https://lh3.googleusercontent.com/gps-cs-s/AHRPTWlPKARR4YyKDk76jDBsFhgsqjIvxLr7sKpLPhAnAWtgf2_0l9wx3yKJUF1vlNqaEE0Ao_eQ…",
        "attributes": ["Wheelchair accessible entrance", "Wheelchair accessible parking lot"]
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `openStatus` | string | The current opening status, as displayed by Google. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `minRating` | number | Restricts results to places rated at least this high. Acceptable values are `2`, `2.5`, `3`, `3.5`, `4` and `4.5`. |
| `openNow` | boolean | Restricts results to places open at the time of the search. If unset, defaults to `false`. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 10. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 10.

## Related methods

* [Google google Maps Place](/api-reference/endpoint/google-maps-place): Accepts `placeUrl`. Scrape a Google Maps place's details.
* [Google google Maps Reviews](/api-reference/endpoint/google-maps-reviews): Accepts `placeUrl`. Scrape a Google Maps place's reviews.


# Google google News API
Source: https://docs.stophy.dev/api-reference/endpoint/google-news

api-reference/openapi.json POST /v1/google/news
Scrape Google News results and headlines. Call the Google google News API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google News results and headlines.

## Request

Exactly one of `query` or `topic` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.news({ query: "nvidia" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.news(query="nvidia")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/news \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nvidia"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google news nvidia
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the articles, each with its publisher and time.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://www.reuters.com/business/nvidia-broadcom-shielded-ai-power-crunch-hits-chip-supply-chain-says-morgan-2026-10-05/",
        "title": "Nvidia, Broadcom shielded as AI power crunch hits chip supply chain, says Morgan Stanley",
        "source": "Reuters",
        "description": "Nvidia and Broadcom are relatively insulated from a worsening US data-center power crunch, but any ​resultant delay in…",
        "publishedAt": "2026-10-05T14:15:59.000Z",
        "position": 1
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `source` | string | Publication that ran the article. |
| `page` | integer | The page number of this response. |
| `position` | integer | The 1-based position of the result in the list. |
| `publishedAt` | string (ISO 8601) | When the article was published. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. Mutually exclusive: set either `query` or `topic`. |
| `topic` | string | The top 10 headlines in one section, instead of a search. Mutually exclusive: set either `query` or `topic`. Acceptable values are `world`, `nation`, `business`, `technology`, `entertainment`, `sports`, `science` and `health`. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `language` | string | The language of the results, as a two-letter ISO 639-1 code such as `en`. |
| `includeDomains` | string\[] | Restricts results to results from these domains. Accepts up to 10 values. |
| `excludeDomains` | string\[] | Leave out results from these domains. Accepts up to 10 values. |
| `time` | string | Restricts results to results from this period. Leave it out for any time. Acceptable values are `pastHour`, `past24Hours`, `pastWeek`, `pastMonth` and `pastYear`. |
| `sort` | string | By relevance, or newest first. Acceptable values are `relevance` and `newest`. If unset, defaults to `relevance`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 10. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 10.


# Google google Patents API
Source: https://docs.stophy.dev/api-reference/endpoint/google-patents

api-reference/openapi.json POST /v1/google/patents
Scrape Google Patents search results. Call the Google google Patents API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google Patents search results.

## Request

This method has no required parameters.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.patents({ query: "solid state battery" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.patents(query="solid state battery")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/patents \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"solid state battery"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google patents "solid state battery"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the patents, each with its owner, inventor, dates and link.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "patentId": "WO2013104046A1",
        "title": "A system and method for assuring operational readiness of a mission critical …",
        "snippet": "A SYSTEM AND METHOD FOR ASSURING OPERATIONAL READINESS OF A MISSION CRITICAL BATTERY HAVING A LONG STORAGE PERIOD…",
        "assignee": "Panacis Inc.",
        "inventor": "Steve Carkner",
        "priorityDate": "2012-01-09",
        "filingDate": "2012-12-19",
        "publicationDate": "2013-07-18",
        "language": "en",
        "patentUrl": "https://patents.google.com/patent/WO2013104046A1/en",
        "pdfUrl": "https://patentimages.storage.googleapis.com/4f/16/c5/b5bc207e6ec556/WO2013104046A1.pdf",
        "thumbnailUrl": "https://patentimages.storage.googleapis.com/c6/b7/47/f2e1e172e74da8/pctca2012050916-appb-P000004-000001.png",
        "position": 1
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `patentId` | string | Publication number, such as US11993294B2. |
| `page` | integer | The page number of this response. |
| `position` | integer | The 1-based position of the result in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `inventor` | string | Restricts results to patents by this inventor. |
| `assignee` | string | Restricts results to patents owned by this company or person. |
| `office` | string | Patent office, such as `US`, `EP`, `WO`, `CN` or `JP`. |
| `language` | string | The language of the patents. Accepts one of 16 values, such as `english`, `german` and `chinese`. |
| `dateType` | string | Specifies the date that `before` and `after` are compared against. Acceptable values are `priority`, `filing` and `publication`. If unset, defaults to `priority`. |
| `after` | string (date) | Restricts results to patents dated after this day. `dateType` picks which date counts. Format: `YYYY-MM-DD`. |
| `before` | string (date) | Restricts results to patents dated before this day. `dateType` picks which date counts. Format: `YYYY-MM-DD`. |
| `status` | string | Granted patents or applications. Acceptable values are `grant` and `application`. |
| `type` | string | Patents or designs. Acceptable values are `patent` and `design`. |
| `litigation` | string | Restricts results to patents with related litigation (`has`), or with none known (`none`). Acceptable values are `has` and `none`. |
| `sort` | string | Specifies the order of the patents. Acceptable values are `relevance`, `newest` and `oldest`. If unset, defaults to `relevance`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.

## Related methods

* [Google google Patents](/api-reference/endpoint/google-patents): Accepts an `assignee` or `inventor` from `results`. Scrape Google Patents search results.


# Google google Play App API
Source: https://docs.stophy.dev/api-reference/endpoint/google-play-app

api-reference/openapi.json POST /v1/google/play/app
Scrape a Google Play app page. Call the Google google Play App API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Google Play app page. The app is identified by its URL or ID.

## Request

Exactly one of `appUrl` or `appId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.play.app({ appId: "com.mojang.minecraftpe", country: "de", language: "de" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.play.app(app_id="com.mojang.minecraftpe", country="de", language="de")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/play/app \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"appId":"com.mojang.minecraftpe","country":"de","language":"de"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google play app --appId com.mojang.minecraftpe --country de --language de
```

## Response

If successful, the response body contains the standard envelope. `data` contains the app's description, developer, installs, ratings, price and version.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "appId": "com.mojang.minecraftpe",
    "appUrl": "https://play.google.com/store/apps/details?id=com.mojang.minecraftpe",
    "name": "Minecraft",
    "summary": "In Minecraft geht es um das Bauen mit Blöcken und das Erleben von Abenteuern!",
    "description": "ERSCHAFFEN\nBaue alles, was du dir vorstellen kannst, in deiner eigenen unendlichen Welt, die in jedem Spieldurchgang…",
    "developerId": "4772240228547998649",
    "developerName": "Mojang",
    "developerWebsite": "http://help.mojang.com",
    "developerAddress": "1 Microsoft Way\nRedmond, WA 98052\nUnited States",
    "privacyPolicyUrl": "http://go.microsoft.com/fwlink/?LinkId=521839",
    "genreId": "GAME_ARCADE",
    "genre": "Arcade",
    "contentRating": "USK ab 6 Jahren",
    "installsText": "50.000.000+",
    "installsMin": 50000000,
    "installsExact": 98343356,
    "rating": 4.37416,
    "ratings": 5852261,
    "reviews": 138916,
    "ratingsOne": 602037,
    "ratingsTwo": 137295,
    "ratingsThree": 202138,
    "ratingsFour": 438142,
    "ratingsFive": 4472586,
    "price": 6.99,
    "priceCurrency": "EUR",
    "hasInAppPurchases": true,
    "inAppPriceText": "0,50 €–49,99 € bei Abrechnung über Google Play",
    "hasAds": false,
    "version": "1.26.52.3",
    "recentChanges": "Neuigkeiten in 26.52\nVerschiedene Fehlerbehebungen",
    "releasedAt": "2011-08-16T06:17:21.000Z",
    "updatedAt": "2026-09-25T17:26:28.000Z",
    "iconUrl": "https://play-lh.googleusercontent.com/tI4StRSPVhpGJH5R013naszLUawOjao1ya8FvyaNO7XY_cJFHFqo1EFaEJv_7zz3rRJ5lEpLiw14ZqQLC…",
    "bannerUrl": "https://play-lh.googleusercontent.com/S_Z7YSNVWWd3BNh3AwV0iVv0hNqJ8zvn-HwLTlYqVLU4uxSohpwKpIa-EmwwwoxOlSw8voqu5CsxQGboj…",
    "screenshotUrls": ["https://play-lh.googleusercontent.com/LvTKBBIfy3RLmCk_EpXDnYMP3NV3MaAOQWnQ1Feuyym2QcmX3sooTLRgkP5KvNp-zGaUyQZ1t11T9YaDe…"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `ratings` | integer | The number of ratings the app has received. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Play Reviews](/api-reference/endpoint/google-play-reviews): Accepts `appUrl`. Scrape a Google Play app's reviews.


# Google google Play Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/google-play-reviews

api-reference/openapi.json POST /v1/google/play/reviews
Scrape a Google Play app's reviews. Call the Google google Play Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Google Play app's reviews. The app is identified by its URL or ID.

## Request

Exactly one of `appUrl` or `appId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.play.reviews({ appId: "com.spotify.music" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.play.reviews(app_id="com.spotify.music")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/play/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"appId":"com.spotify.music"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google play reviews --appId com.spotify.music
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the app's reviews, each with its rating, text and app version.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "reviewId": "1a4c762b-2485-43c9-b650-26f156a0bb8e",
        "reviewUrl": "https://play.google.com/store/apps/details?id=com.spotify.music&reviewId=1a4c762b-2485-43c9-b650-26f156a0bb8e",
        "rating": 5,
        "text": "wonderful",
        "authorName": "Catherine Karnes",
        "authorAvatarUrl": "https://play-lh.googleusercontent.com/a-/ALV-UjVTvMvluNuCMD5by8WaWKHREjxco1xFbkGxTiAYWQR56WM3NQ",
        "publishedAt": "2026-10-04T20:41:00.000Z",
        "likes": 0,
        "appVersion": "9.1.88.2204"
      }
    ],
    "cursor": "Cs4BIsUBAV8d1P1XyJzoCkS2MkuhVw8-kSz5Novn3dcOEAaUonNI3-AUKSEanOvKpDWreoUnFQ5wxw35brKzwAbyPz1gFz18G5S5_YzCDNXUNJ7H9NAofms…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `rating` | integer | The average star rating, on a scale of 1 to 5. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |
| `sort` | string | Specifies which reviews are returned first. Acceptable values are `newest`, `relevance` and `highest`. If unset, defaults to `newest`. |
| `rating` | integer | Restricts results to reviews with this many stars. Must be between 1 and 5. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Google google Play App](/api-reference/endpoint/google-play-app): Accepts the same `appId`. Scrape a Google Play app page.


# Google google Play Search API
Source: https://docs.stophy.dev/api-reference/endpoint/google-play-search

api-reference/openapi.json POST /v1/google/play/search
Scrape Google Play search results. Call the Google google Play Search API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape Google Play search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.play.search({ query: "photo editor" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.play.search(query="photo editor")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/play/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"photo editor"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google play search "photo editor"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the matching apps, each with its developer, installs and rating.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "appId": "photo.editor.photoeditor.photoeditorpro",
        "appUrl": "https://play.google.com/store/apps/details?id=photo.editor.photoeditor.photoeditorpro",
        "name": "Photo Editor - Polish",
        "developerName": "InShot Inc.",
        "summary": "✨ Powerful Photo Editor for Every Moment 🎉 Looking for an easy photo editor to transform your pictures in seconds?",
        "genre": "Photography",
        "installsText": "100,000,000+",
        "installsMin": 100000000,
        "rating": 4.8010755,
        "price": 0,
        "priceCurrency": "USD",
        "iconUrl": "https://play-lh.googleusercontent.com/q-z-Sbn2WLCUb4MSmmdhVr9KRfJ4qTlgoQEUGEKsnfVEEMNPxsabpr-yngqQ15o5b6gLhaBOhGZNv6oBW…"
      }
    ]
  },
  "creditsUsed": 3,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |
| `limit` | integer | The maximum number of apps to return. Billed at 1 credit per 10 returned. Must be between 1 and 50. |

## Billing

A successful request consumes 1 credit per 10 apps, up to 5 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Play App](/api-reference/endpoint/google-play-app): Accepts `appUrl`. Scrape a Google Play app page.
* [Google google Play Reviews](/api-reference/endpoint/google-play-reviews): Accepts `appUrl`. Scrape a Google Play app's reviews.


# Google google Scholar API
Source: https://docs.stophy.dev/api-reference/endpoint/google-scholar

api-reference/openapi.json POST /v1/google/scholar
Scrape Google Scholar search results. Call the Google google Scholar API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google Scholar search results.

## Request

At least one of `query` or `citesId` is required. Set `citesId` to list the works that cite a result.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.scholar({ query: "malaria vaccine efficacy" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.scholar(query="malaria vaccine efficacy")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/scholar \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"malaria vaccine efficacy"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google scholar "malaria vaccine efficacy"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the papers, books and cases, each with its authors, year and the number of works that cite it.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "title": "Seven-year efficacy of RTS, S/AS01 malaria vaccine among young African children",
        "url": "https://www.nejm.org/doi/abs/10.1056/NEJMoa1515257",
        "format": "pdf",
        "authors": ["A Olotu", "G Fegan"],
        "publication": "England Journal of …",
        "year": 2016,
        "publisher": "Mass Medical Soc",
        "snippet": "… In an analysis that was not prespecified, the malaria exposure of each child was estimated … of malaria among…",
        "citations": 618,
        "citesId": "15871362944033457094",
        "versions": 14,
        "pdfUrl": "https://www.nejm.org/doi/pdf/10.1056/NEJMoa1515257",
        "position": 1
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `citesId` | string | Pass it as `citesId` to list the works that cite this one. |
| `citations` | integer | The number of works cite this one. |
| `format` | string | Scholar's tag, such as \[PDF] or \[BOOK]. |
| `publication` | string | Journal or venue; the case citation for case law. |
| `page` | integer | The page number of this response. |
| `position` | integer | The 1-based position of the result in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `citesId` | string | A result's `citesId`. Lists the works that cite it. |
| `yearFrom` | integer | Restricts results to works from this year on. Must be between 1700 and 2027. |
| `yearTo` | integer | Restricts results to works up to this year. Must be between 1700 and 2027. |
| `sort` | string | Specifies the order of the results. `newest` lists recent additions first. Acceptable values are `relevance` and `newest`. If unset, defaults to `relevance`. |
| `type` | string | Any type, review articles or case law. Acceptable values are `any`, `reviewArticles` and `caseLaw`. If unset, defaults to `any`. |
| `includePatents` | boolean | Include patents in the results. If unset, defaults to `false`. |
| `includeCitations` | boolean | Include works that Scholar knows only from citations. If unset, defaults to `true`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 20. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 20.

## Related methods

* [Google google Scholar](/api-reference/endpoint/google-scholar): Accepts a result's `citesId` as `citesId`. Scrape Google Scholar search results.


# Google google Search API
Source: https://docs.stophy.dev/api-reference/endpoint/google-search

api-reference/openapi.json POST /v1/google/search
Scrape Google Search results. Call the Google google Search API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape Google Search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.search({ query: "best project management software" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.search(query="best project management software")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best project management software"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google search "best project management software"
```

## Response

If successful, the response body contains the standard envelope. `data` contains the web results in `results`, Google's AI Overview when it shows one, related questions and related searches.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "aiOverview": {
      "text": "The best project management software depends on your team's specific workflow, size, and goals, with top platforms…"
    },
    "results": [
      {
        "type": "web",
        "url": "https://www.reddit.com/r/projectmanagement/comments/1dogwhv/looking_for_a_project_management_software_with/",
        "title": "Looking for a project management software with specific ...",
        "description": "Microsoft Access, Smartsuite, NocoDB, Fibery, Zoho Creator, Baserow), Asana is capable of this. Use Monday.com. Look…",
        "position": 1
      },
      {
        "type": "post",
        "url": "https://www.linkedin.com/pulse/12-must-have-tools-project-managers-successful-project-managers-sszdf",
        "text": "12 Must-Have Tools for Project Managers",
        "site": "LinkedIn",
        "authorName": "Successful Project Managers",
        "publishedAt": "2026-09-17T07:00:00.000Z",
        "position": 5
      }
    ],
    "peopleAlsoAsk": [
      {
        "question": "Which is the most popular project management software?"
      }
    ],
    "relatedSearches": ["Best project management software reddit"],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The kind of item: `web`, `news`, `video` or `post`. |
| `site` | string | Where the result was found, such as YouTube or Reddit. |
| `publishedAt` | string (ISO 8601) | When it was published. For videos it is approximate, because Google shows only how long ago. |
| `page` | integer | The page number of this response. |
| `position` | integer | The 1-based position of the result in the list. |
| `aiOverview` | object | The Google AI Overview. Omitted when Google does not display one. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Turn on scrapeResults to get the text of the top pages in the same call.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `language` | string | The language of the results, as a two-letter ISO 639-1 code such as `en`. |
| `includeDomains` | string\[] | Restricts results to results from these domains. Accepts up to 10 values. |
| `excludeDomains` | string\[] | Leave out results from these domains. Accepts up to 10 values. |
| `time` | string | Restricts results to results from this period. Leave it out for any time. Acceptable values are `pastHour`, `past24Hours`, `pastWeek`, `pastMonth` and `pastYear`. |
| `safeSearch` | boolean | Hide explicit results. If unset, defaults to `false`. |
| `scrapeResults` | boolean | Also read the top results and add each page's text as markdown. Costs 1 more credit for each result that comes back with its text. If unset, defaults to `false`. |
| `scrapeLimit` | integer | The number of of the top results to read when `scrapeResults` is on. Must be between 1 and 5. If unset, defaults to `3`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

A successful request consumes 1 credit per call, plus 1 credit for each result that comes back with its page text when scrapeResults is on, up to 6 credits. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100. Requests without an API key return the first page only.

## Related methods

* [Google google Search](/api-reference/endpoint/google-search): Accepts an entry from `relatedSearches` as `query`. Scrape Google Search results.


# Google google Suggestions API
Source: https://docs.stophy.dev/api-reference/endpoint/google-suggest

api-reference/openapi.json POST /v1/google/suggest
Scrape Google search suggestions. Call the Google google Suggestions API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google search suggestions.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.suggest({ query: "best running shoes" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.suggest(query="best running shoes")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/suggest \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best running shoes"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google suggest "best running shoes"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the suggestions, best first.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "keyword": "best running shoes for men",
        "rank": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rank` | integer | The 1-based position of the entry in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Search](/api-reference/endpoint/google-search): Accepts a suggestion as `query`. Scrape Google Search results.
* [Google google News](/api-reference/endpoint/google-news): Accepts a suggestion as `query`. Scrape Google News results and headlines.
* [Google Trends interest over time](/api-reference/endpoint/google-trends-interest): Accepts a suggestion as `queries`. Scrape Google Trends interest over time.


# Google google Trends Interest API
Source: https://docs.stophy.dev/api-reference/endpoint/google-trends-interest

api-reference/openapi.json POST /v1/google/trends/interest
Scrape Google Trends interest over time. Call the Google google Trends Interest API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Google Trends interest over time.

## Request

`queries` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.trends.interest({ queries: ["bitcoin", "ethereum"] });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.trends.interest(queries=["bitcoin", "ethereum"])
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/trends/interest \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"queries":["bitcoin","ethereum"]}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google trends interest --queries bitcoin,ethereum
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains search interest over time, newest first, with one value for each query.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "recordedAt": "2026-10-04T00:00:00.000Z",
        "values": {
          "bitcoin": 22,
          "ethereum": 3
        },
        "isPartial": true
      }
    ],
    "averages": {
      "bitcoin": 44,
      "ethereum": 7
    }
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `values` | object | Search interest for each query, relative to the peak value of 100. |
| `isPartial` | boolean | `true` if the period has not ended. |
| `averages` | object | The mean interest for each query over the full range. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `time` | string | Specifies the time range. Acceptable values are `pastHour`, `past4Hours`, `pastDay`, `past7Days`, `past30Days`, `past90Days`, `past12Months`, `past5Years` and `since2004`. If unset, defaults to `past12Months`. |
| `searchType` | string | Specifies the Google property the searches were made on. Acceptable values are `web`, `images`, `news`, `shopping` and `youtube`. If unset, defaults to `web`. |
| `category` | string | Restricts results to searches in this category. Accepts one of 25 values, such as `artsEntertainment`, `autosVehicles` and `beautyFitness`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google Trends by region](/api-reference/endpoint/google-trends-regions): Accepts the same `queries`. Scrape Google Trends interest by region.
* [Google Trends related searches](/api-reference/endpoint/google-trends-related): Accepts one of the same queries as `query`. Scrape Google Trends related searches.


# Google google Trends Regions API
Source: https://docs.stophy.dev/api-reference/endpoint/google-trends-regions

api-reference/openapi.json POST /v1/google/trends/regions
Scrape Google Trends interest by region. Call the Google google Trends Regions API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Google Trends interest by region.

## Request

`queries` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.trends.regions({ queries: ["bitcoin"] });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.trends.regions(queries=["bitcoin"])
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/trends/regions \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"queries":["bitcoin"]}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google trends regions --queries bitcoin
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the regions, each with one value for each query.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "code": "CH",
        "name": "Switzerland",
        "values": {
          "bitcoin": 100
        }
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `values` | object | Search interest for each query, relative to the peak value of 100. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `time` | string | Specifies the time range. Acceptable values are `pastHour`, `past4Hours`, `pastDay`, `past7Days`, `past30Days`, `past90Days`, `past12Months`, `past5Years` and `since2004`. If unset, defaults to `past12Months`. |
| `searchType` | string | Specifies the Google property the searches were made on. Acceptable values are `web`, `images`, `news`, `shopping` and `youtube`. If unset, defaults to `web`. |
| `category` | string | Restricts results to searches in this category. Accepts one of 25 values, such as `artsEntertainment`, `autosVehicles` and `beautyFitness`. |
| `resolution` | string | Specifies the granularity of the regional breakdown. Acceptable values are `country`, `region` and `metro`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google Trends interest over time](/api-reference/endpoint/google-trends-interest): Accepts the same `queries`. Scrape Google Trends interest over time.
* [Google Trends related searches](/api-reference/endpoint/google-trends-related): Accepts one of the same queries as `query`. Scrape Google Trends related searches.


# Google google Trends Related API
Source: https://docs.stophy.dev/api-reference/endpoint/google-trends-related

api-reference/openapi.json POST /v1/google/trends/related
Scrape Google Trends related searches. Call the Google google Trends Related API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Google Trends related searches.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.trends.related({ query: "bitcoin" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.trends.related(query="bitcoin")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/trends/related \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"bitcoin"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google trends related bitcoin
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the related searches, each with a score.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "query": "bitcoin price",
        "value": 100
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `value` | number | The relative popularity of the related search. The maximum is 100. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `time` | string | Specifies the time range. Acceptable values are `pastHour`, `past4Hours`, `pastDay`, `past7Days`, `past30Days`, `past90Days`, `past12Months`, `past5Years` and `since2004`. If unset, defaults to `past12Months`. |
| `searchType` | string | Specifies the Google property the searches were made on. Acceptable values are `web`, `images`, `news`, `shopping` and `youtube`. If unset, defaults to `web`. |
| `category` | string | Restricts results to searches in this category. Accepts one of 25 values, such as `artsEntertainment`, `autosVehicles` and `beautyFitness`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google Trends interest over time](/api-reference/endpoint/google-trends-interest): Accepts queries from `results` as `queries`. Scrape Google Trends interest over time.
* [Google Trends by region](/api-reference/endpoint/google-trends-regions): Accepts queries from `results` as `queries`. Scrape Google Trends interest by region.
* [Google google Search](/api-reference/endpoint/google-search): Accepts a related search as `query`. Scrape Google Search results.


# Google google Trends Trending API
Source: https://docs.stophy.dev/api-reference/endpoint/google-trends-trending

api-reference/openapi.json POST /v1/google/trends/trending
Scrape what is trending on Google now. Call the Google google Trends Trending API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape what is trending on Google now.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.trends.trending({ country: "us" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.trends.trending(country="us")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/trends/trending \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"country":"us"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google trends trending --country us
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains what is trending, each with its search volume and start time.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "query": "france vs belgium",
        "volume": 100000,
        "increasePercent": 1000,
        "startedAt": "2026-10-05T17:50:00.000Z",
        "isActive": true,
        "related": ["france vs belgium", "france national football team"],
        "categories": ["sports"],
        "trendUrl": "https://trends.google.com/trends/explore?q=france+vs+belgium&geo=US&date=now+1-d"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `volume` | number | The search volume of the trend. |
| `increasePercent` | number | The growth in search volume, as a percentage. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. If unset, defaults to `us`. |
| `time` | string | Specifies the time range. Acceptable values are `past4Hours`, `past24Hours`, `past48Hours` and `past7Days`. If unset, defaults to `past24Hours`. |
| `category` | string | Restricts results to trends in this category. Accepts one of 19 values, such as `autos`, `beautyFashion` and `business`. |
| `status` | string | All trends, or only the ones still rising. Acceptable values are `all` and `active`. If unset, defaults to `all`. |
| `sort` | string | Specifies the order of the trends. Acceptable values are `relevance`, `searchVolume`, `recency` and `title`. If unset, defaults to `relevance`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Google google Search](/api-reference/endpoint/google-search): Accepts a trend's `query`. Scrape Google Search results.
* [Google google News](/api-reference/endpoint/google-news): Accepts a trend's `query`. Scrape Google News results and headlines.
* [Google Trends interest over time](/api-reference/endpoint/google-trends-interest): Accepts a trend's `query` as `queries`. Scrape Google Trends interest over time.


# Indeed indeed Job API
Source: https://docs.stophy.dev/api-reference/endpoint/indeed-job

api-reference/openapi.json POST /v1/indeed/job
Scrape an Indeed job page. Call the Indeed indeed Job API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an Indeed job page. The job is identified by its URL or ID.

## Request

Exactly one of `jobUrl` or `jobId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.indeed.job({ jobId: "a1b2c3d4e5f60718" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.indeed.job(job_id="a1b2c3d4e5f60718")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/indeed/job \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobId":"a1b2c3d4e5f60718"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy indeed job --jobId a1b2c3d4e5f60718
```

## Response

If successful, the response body contains the standard envelope. `data` contains the job's company, pay, location and full description.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "57f5b67299fda823",
    "jobUrl": "https://www.indeed.com/viewjob?jk=57f5b67299fda823",
    "title": "Sr. Data Analyst, Customer Analytics (Insurance)",
    "companyName": "CCC Intelligent Solutions",
    "companyUrl": "https://www.indeed.com/cmp/Ccc-Intelligent-Solutions-1",
    "companyAvatarUrl": "https://d2q79iu7y748jz.cloudfront.net/s/_squarelogo/256x256/9b657fd43e3a37b384dcc01be5a555d7",
    "companyWebsite": "http://www.cccis.com",
    "companyEmployeesText": "1,001 to 5,000",
    "companyRevenueText": "Decline to state",
    "companyDescription": "At CCC, we’re all about connectedness - from our people to our products. Our team is truly reshaping the auto and…",
    "addressFull": "Chicago, IL 60607",
    "addressCity": "Chicago",
    "addressRegion": "IL",
    "addressPostalCode": "60607",
    "addressCountry": "US",
    "latitude": 41.885124,
    "longitude": -87.64813,
    "salaryMin": 84724,
    "salaryMax": 120000,
    "salaryPeriod": "year",
    "salaryCurrency": "USD",
    "salaryIsEstimate": false,
    "jobTypes": ["fullTime"],
    "isRemote": false,
    "isHybrid": false,
    "experienceLevels": ["senior"],
    "educationLevels": ["bachelor"],
    "attributes": ["AI models"],
    "publishedAt": "2026-10-05T05:00:00.000Z",
    "indexedAt": "2026-10-05T16:08:42.293Z",
    "applyUrl": "https://cccis.wd1.myworkdayjobs.com/broadbean_external/job/Chicago-Green-St-IL/Sr-Data-Analyst--Customer-Analytics--Ins…",
    "isEasyApply": true,
    "isUrgent": false,
    "source": "CCC Information Services Inc.",
    "description": "CCC Intelligent Solutions Inc. (CCC) is a leading cloud platform for the multi-trillion-dollar insurance economy,…",
    "descriptionHtml": "<div><p>CCC Intelligent Solutions Inc. (CCC) is a leading cloud platform for the multi-trillion-dollar insurance…",
    "isExpired": false,
    "language": "en"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 62 values, such as `us`, `gb` and `ca`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Indeed indeed Search](/api-reference/endpoint/indeed-search): Accepts the job's `title` as `query`. Scrape Indeed job search results.


# Indeed indeed Search API
Source: https://docs.stophy.dev/api-reference/endpoint/indeed-search

api-reference/openapi.json POST /v1/indeed/search
Scrape Indeed job search results. Call the Indeed indeed Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Indeed job search results.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.indeed.search({ query: "data analyst", location: "Chicago, IL", datePosted: "last7Days" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.indeed.search(query="data analyst", location="Chicago, IL", date_posted="last7Days")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/indeed/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"data analyst","location":"Chicago, IL","datePosted":"last7Days"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy indeed search "data analyst" --location "Chicago, IL" --datePosted last7Days
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the jobs, each with its company, pay, location and posting date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "jobId": "57f5b67299fda823",
        "jobUrl": "https://www.indeed.com/viewjob?jk=57f5b67299fda823",
        "title": "Sr. Data Analyst, Customer Analytics (Insurance)",
        "companyName": "CCC Intelligent Solutions",
        "companyUrl": "https://www.indeed.com/cmp/Ccc-Intelligent-Solutions-1",
        "companyAvatarUrl": "https://d2q79iu7y748jz.cloudfront.net/s/_squarelogo/256x256/9b657fd43e3a37b384dcc01be5a555d7",
        "companyWebsite": "http://www.cccis.com",
        "companyEmployeesText": "1,001 to 5,000",
        "companyRevenueText": "Decline to state",
        "companyDescription": "At CCC, we’re all about connectedness - from our people to our products. Our team is truly reshaping the auto and…",
        "addressFull": "Chicago, IL 60607",
        "addressCity": "Chicago",
        "addressRegion": "IL",
        "addressPostalCode": "60607",
        "addressCountry": "US",
        "latitude": 41.885124,
        "longitude": -87.64813,
        "salaryMin": 84724,
        "salaryMax": 120000,
        "salaryPeriod": "year",
        "salaryCurrency": "USD",
        "salaryIsEstimate": false,
        "jobTypes": ["fullTime"],
        "isRemote": false,
        "isHybrid": false,
        "experienceLevels": ["senior"],
        "educationLevels": ["bachelor"],
        "attributes": ["AI models", "Optimizing workflow processes"],
        "publishedAt": "2026-10-05T05:00:00.000Z",
        "indexedAt": "2026-10-05T16:08:42.293Z",
        "applyUrl": "https://cccis.wd1.myworkdayjobs.com/broadbean_external/job/Chicago-Green-St-IL/Sr-Data-Analyst--Customer-Analytics--Ins…",
        "isEasyApply": true,
        "isUrgent": false,
        "source": "CCC Information Services Inc.",
        "description": "CCC Intelligent Solutions Inc. (CCC) is a leading cloud platform for the multi-trillion-dollar insurance economy,…"
      }
    ],
    "cursor": "ABkAAQAZAAAAAAAAAAAAAAACZRQ9vgEBAQh6SP1ejTvdtRgDInsCYE/ygA=="
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `location` | string | City, region or postal code, such as Kansas City, MO. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 62 values, such as `us`, `gb` and `ca`. If unset, defaults to `us`. |
| `distanceMiles` | integer | The search radius around `location`, in miles. `0` is the exact location only. Acceptable values are `0`, `5`, `10`, `15`, `25`, `35`, `50` and `100`. If unset, defaults to `25`. |
| `datePosted` | string | Restricts results to jobs posted in this period. A relisted job keeps its first `publishedAt` and shows the new date in `indexedAt`. Acceptable values are `last24Hours`, `last3Days`, `last7Days` and `last14Days`. |
| `remote` | string | Restricts results to remote or hybrid jobs. Acceptable values are `remote` and `hybrid`. |
| `jobType` | string | Restricts results to this type of job. Acceptable values are `fullTime`, `partTime`, `contract`, `temporary` and `internship`. |
| `experienceLevel` | string | Restricts results to jobs for this level. Acceptable values are `noExperience`, `entry`, `mid` and `senior`. |
| `education` | string | Restricts results to jobs that ask for this education. Acceptable values are `highSchool`, `associate`, `bachelor` and `master`. |
| `sort` | string | Specifies the order of the jobs. Acceptable values are `relevance` and `newest`. If unset, defaults to `relevance`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Indeed indeed Job](/api-reference/endpoint/indeed-job): Accepts `jobUrl`. Scrape an Indeed job page.


# Instagram instagram Comments API
Source: https://docs.stophy.dev/api-reference/endpoint/instagram-comments

api-reference/openapi.json POST /v1/instagram/comments
Scrape the comments of an Instagram post. Call the Instagram instagram Comments API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape the comments of an Instagram post. The post is identified by its URL or code.

## Request

Exactly one of `postUrl` or `postCode` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.comments({ postUrl: "https://www.instagram.com/p/DdG4RIxIPyf/" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.comments(post_url="https://www.instagram.com/p/DdG4RIxIPyf/")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/comments \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postUrl":"https://www.instagram.com/p/DdG4RIxIPyf/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram comments --postUrl https://www.instagram.com/p/DdG4RIxIPyf/
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the comments, or the replies when `comment` is set.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "commentId": "18410943604087835",
        "commentUrl": "https://www.instagram.com/p/DdG4RIxIPyf/c/18410943604087835/",
        "authorId": "64735973900",
        "authorUsername": "stirlingboss",
        "authorUrl": "https://www.instagram.com/stirlingboss/",
        "authorAvatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/830572424_17971162935157901_5093138578066260536_n.jpg?stp=dst-j…",
        "authorIsVerified": false,
        "text": "🆘️",
        "replies": 0,
        "publishedAt": "2026-10-05T15:42:33.000Z"
      }
    ],
    "cursor": "{\"server_cursor\": \"QVFBcWhNM3JhbkU1Uk92Zmd0bHZFY1R1Nkg0UVRyb19SaDdheGFJN09vdTVkUXVjSlhPbjlMUThLZDlFejdEQTB6c2oxYmR2Tlo2…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Instagram instagram Profile](/api-reference/endpoint/instagram-profile): Accepts `userUrl`. Scrape an Instagram profile and its posts.
* [Instagram profile reels](/api-reference/endpoint/instagram-profile-reels): Accepts `userUrl`. Scrape an Instagram profile's reels.


# Instagram instagram Post API
Source: https://docs.stophy.dev/api-reference/endpoint/instagram-post

api-reference/openapi.json POST /v1/instagram/post
Scrape an Instagram post or reel. Call the Instagram instagram Post API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an Instagram post or reel. The post is identified by its URL or code.

## Request

Exactly one of `postUrl` or `postCode` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.post({ postUrl: "https://www.instagram.com/p/DdG4RIxIPyf/" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.post(post_url="https://www.instagram.com/p/DdG4RIxIPyf/")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postUrl":"https://www.instagram.com/p/DdG4RIxIPyf/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram post --postUrl https://www.instagram.com/p/DdG4RIxIPyf/
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post or reel, and `results` lists its top comments.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "3983118388705688735",
    "postCode": "DdG4RIxIPyf",
    "postUrl": "https://www.instagram.com/p/DdG4RIxIPyf/",
    "type": "reel",
    "text": "Presented by @Rolex. Welcome to Africa 🌍 Africa Earth’s Wild Home takes you deep into the heart of our wildest…",
    "hashtags": ["Rolex"],
    "mentions": ["rolex"],
    "publishedAt": "2026-09-10T13:00:14.000Z",
    "likes": 78665,
    "views": 870839,
    "thumbnailUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/802503979_18695767555019133_6909214034622416488_n.jpg?stp=dst-j…",
    "imageUrls": ["https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/802503979_18695767555019133_6909214034622416488_n.jpg?stp=dst-j…"],
    "videoUrls": ["https://scontent-xxc1-1.cdninstagram.com/o1/v/t2/f2/m86/AQPDJtVww4K_686Ed9TbciE3dp0nrA4iUd5M8OJJIZKcU-RmkzTGwtpi3CsZY9P…"],
    "imageDescription": "Video by National Geographic on September 10, 2026. May be an image of elephant, rhinoceros, poster, outdoors and text…",
    "isPinned": false,
    "authorId": "787132",
    "authorUsername": "natgeo",
    "authorName": "National Geographic",
    "authorUrl": "https://www.instagram.com/natgeo/",
    "authorAvatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…",
    "authorIsVerified": true,
    "taggedUsers": ["rolex"],
    "coauthors": ["rolex"],
    "audioTitle": "Original audio",
    "audioArtist": "natgeo",
    "audioIsOriginal": true,
    "isPaidPartnership": false,
    "comments": 531,
    "results": [
      {
        "commentId": "18410943604087835",
        "commentUrl": "https://www.instagram.com/p/DdG4RIxIPyf/c/18410943604087835/",
        "authorId": "64735973900",
        "authorUsername": "stirlingboss",
        "authorUrl": "https://www.instagram.com/stirlingboss/",
        "authorAvatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/830572424_17971162935157901_5093138578066260536_n.jpg?stp=dst-j…",
        "authorIsVerified": false,
        "text": "🆘️",
        "likes": 0,
        "publishedAt": "2026-10-05T15:42:33.000Z"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The kind of item: `photo`, `video`, `reel` or `carousel`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> The reply count of a comment can be absent in this response. To retrieve the exact count and the replies, pass the comment ID to [Instagram instagram Comments](/api-reference/endpoint/instagram-comments).

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Instagram instagram Comments](/api-reference/endpoint/instagram-comments): Accepts `postUrl`. Scrape the comments of an Instagram post.
* [Instagram instagram Profile](/api-reference/endpoint/instagram-profile): Accepts `userUrl`. Scrape an Instagram profile and its posts.
* [Instagram profile reels](/api-reference/endpoint/instagram-profile-reels): Accepts `userUrl`. Scrape an Instagram profile's reels.


# Instagram instagram Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/instagram-profile

api-reference/openapi.json POST /v1/instagram/profile
Scrape an Instagram profile and its posts. Call the Instagram instagram Profile API for JSON. 2 credits per call. Every call returns the same flat shape.

Scrape an Instagram profile and its posts. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.profile({ username: "natgeo" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.profile(username="natgeo")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"natgeo"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram profile --username natgeo
```

## Response

If successful, the response body contains the standard envelope. `data` contains the profile's bio and stats, and `results` lists a page of its posts and reels.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "787132",
    "username": "natgeo",
    "userUrl": "https://www.instagram.com/natgeo/",
    "name": "National Geographic",
    "bio": "Step into wonder and find your inner explorer with National Geographic 🌎",
    "bioLinkUrls": ["http://visitstore.bio/natgeo"],
    "isVerified": true,
    "isPrivate": false,
    "followers": 268443252,
    "following": 194,
    "posts": 32045,
    "avatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…",
    "postsAnalyzed": 10,
    "averageLikes": 72875,
    "averageComments": 298,
    "engagementRate": 0.027,
    "postsPerWeek": 22,
    "lastPostAt": "2026-10-05T17:17:36.000Z",
    "results": [
      {
        "postId": "3983118388705688735",
        "postCode": "DdG4RIxIPyf",
        "postUrl": "https://www.instagram.com/p/DdG4RIxIPyf/",
        "type": "reel",
        "text": "Presented by @Rolex. Welcome to Africa 🌍 Africa Earth’s Wild Home takes you deep into the heart of our wildest…",
        "hashtags": ["Rolex", "PerpetualPlanet"],
        "mentions": ["rolex", "wunmimosaku"],
        "publishedAt": "2026-09-10T13:00:14.000Z",
        "likes": 78665,
        "comments": 531,
        "views": 870839,
        "thumbnailUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/802503979_18695767555019133_6909214034622416488_n.jpg?stp=c0.42…",
        "imageUrls": ["https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/802503979_18695767555019133_6909214034622416488_n.jpg?stp=dst-j…"],
        "videoUrls": ["https://scontent-xxc1-1.cdninstagram.com/o1/v/t2/f2/m86/AQPDJtVww4K_686Ed9TbciE3dp0nrA4iUd5M8OJJIZKcU-RmkzTGwtpi3CsZY9P…"],
        "isPinned": true,
        "authorId": "787132",
        "authorUsername": "natgeo",
        "authorName": "National Geographic",
        "authorUrl": "https://www.instagram.com/natgeo/",
        "authorAvatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…",
        "authorIsVerified": true,
        "taggedUsers": ["rolex"],
        "coauthors": ["rolex"],
        "audioTitle": "Original audio",
        "audioArtist": "natgeo",
        "audioIsOriginal": true,
        "isPaidPartnership": true,
        "sponsors": ["rolex"]
      },
      {
        "postId": "4000517920972154463",
        "postCode": "DeEsdp9ISZf",
        "postUrl": "https://www.instagram.com/p/DeEsdp9ISZf/",
        "type": "photo",
        "text": "Presented by @Rolex. Conservation ecologist and Rolex National Geographic Perpetual Planet Explorer Matt Shirley has…",
        "hashtags": ["Rolex", "AfricaEarthsWildHome"],
        "mentions": ["rolex", "hammond_robin"],
        "publishedAt": "2026-10-04T13:02:58.000Z",
        "likes": 28807,
        "comments": 73,
        "thumbnailUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/838090435_18704188369019133_3459482282107908109_n.jpg?stp=c0.16…",
        "imageUrls": ["https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-15/838090435_18704188369019133_3459482282107908109_n.jpg?stp=dst-j…"],
        "isPinned": false,
        "authorId": "787132",
        "authorUsername": "natgeo",
        "authorName": "National Geographic",
        "authorUrl": "https://www.instagram.com/natgeo/",
        "authorAvatarUrl": "https://scontent-xxc1-1.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-j…",
        "authorIsVerified": true,
        "isPaidPartnership": true,
        "sponsors": ["rolex"]
      }
    ],
    "cursor": "3999067523172763307_787132"
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `photo`, `video`, `reel` or `carousel`. |
| `posts` | integer | The number of posts the profile has. Its latest posts are in `results`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Instagram profile reels](/api-reference/endpoint/instagram-profile-reels): Accepts `userUrl`. Scrape an Instagram profile's reels.
* [Instagram instagram Comments](/api-reference/endpoint/instagram-comments): Accepts `postUrl`. Scrape the comments of an Instagram post.
* [Instagram instagram Post](/api-reference/endpoint/instagram-post): Accepts `postUrl`. Scrape an Instagram post or reel.


# Instagram instagram Profile Reels API
Source: https://docs.stophy.dev/api-reference/endpoint/instagram-profile-reels

api-reference/openapi.json POST /v1/instagram/profile/reels
Scrape an Instagram profile's reels. Call the Instagram instagram Profile Reels API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape an Instagram profile's reels. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.profile.reels({ username: "natgeo" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.profile.reels(username="natgeo")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/profile/reels \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"natgeo"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram profile reels --username natgeo
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the profile's reels with their views.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "postId": "4001242265619084177",
        "postCode": "DeHRKQegTOR",
        "postUrl": "https://www.instagram.com/reel/DeHRKQegTOR/",
        "likes": 31000,
        "comments": 102,
        "views": 965380,
        "imageUrl": "https://scontent-lax3-2.cdninstagram.com/v/t51.82787-15/836841474_18704538382019133_959930361101654287_n.jpg?stp=dst-jp…",
        "isPinned": false,
        "authorId": "787132",
        "authorUsername": "natgeo"
      }
    ],
    "cursor": "AQHTriiXVTKLFDkwaf4mYfPAUsCY-pcgmDFoUk9Z8U7PXyvyC1sQ6H9WFnNZkZcQ28FJ-4PWJUOhsaiwvy8-ToNeMw"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> [Instagram instagram Profile](/api-reference/endpoint/instagram-profile) is the mixed grid of posts and reels.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Instagram instagram Comments](/api-reference/endpoint/instagram-comments): Accepts `postUrl`. Scrape the comments of an Instagram post.
* [Instagram instagram Post](/api-reference/endpoint/instagram-post): Accepts `postUrl`. Scrape an Instagram post or reel.
* [Instagram instagram Profile](/api-reference/endpoint/instagram-profile): Accepts `username`. Scrape an Instagram profile and its posts.


# Instagram instagram Transcript API
Source: https://docs.stophy.dev/api-reference/endpoint/instagram-transcript

api-reference/openapi.json POST /v1/instagram/transcript
Scrape an Instagram video's transcript. Call the Instagram instagram Transcript API for JSON. From 1 credit per call. Every call returns the same flat shape.

Scrape an Instagram video's transcript. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.transcript({ videoUrl: "https://www.instagram.com/reel/DdG4RIxIPyf/" });
console.log(result.data.text);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.transcript(video_url="https://www.instagram.com/reel/DdG4RIxIPyf/")
print(result["data"]["text"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/transcript \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoUrl":"https://www.instagram.com/reel/DdG4RIxIPyf/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram transcript --videoUrl https://www.instagram.com/reel/DdG4RIxIPyf/
```

## Response

If successful, the response body contains the standard envelope. `data` contains what the video says as one block of `text`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "videoId": "DdG4RIxIPyf",
    "videoUrl": "https://www.instagram.com/p/DdG4RIxIPyf/",
    "language": "en",
    "isAutoGenerated": true,
    "durationSeconds": 72.584118272,
    "transcribedSeconds": 73,
    "text": "Welcome to Africa. Welcome to Earth's wild home. See a new side to animals you know and meet some you've never seen…"
  },
  "creditsUsed": 10,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `text` | string | The whole transcript as one block. |
| `transcribedSeconds` | number | Seconds of audio that were transcribed when the video had no captions. The price depends on it. |
| `isAutoGenerated` | boolean | `true` if the captions were generated, not written by a person. |
| `durationSeconds` | number | The duration, in seconds. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. |
| `includeTimestamps` | boolean | Return each line with its start and end time, in `segments`. If unset, defaults to `false`. |

## Billing

A successful request consumes 2 credits plus 1 credit for every 10 seconds of audio, up to 30 minutes, up to 182 credits. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Instagram instagram Post](/api-reference/endpoint/instagram-post): Accepts the same code as `postCode`. Scrape an Instagram post or reel.
* [Instagram instagram Comments](/api-reference/endpoint/instagram-comments): Accepts the same code as `postCode`. Scrape the comments of an Instagram post.


# LinkedIn linkedIn Ad API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-ads-ad

api-reference/openapi.json POST /v1/linkedin/ads/ad
Scrape a LinkedIn ad's details. Call the LinkedIn linkedIn Ad API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a LinkedIn ad's details. The ad is identified by its URL or ID.

## Request

Exactly one of `adUrl` or `adId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.ads.ad({ adUrl: "https://www.linkedin.com/ad-library/detail/1234567" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.ads.ad(ad_url="https://www.linkedin.com/ad-library/detail/1234567")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"adUrl":"https://www.linkedin.com/ad-library/detail/1234567"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin ads ad --adUrl https://www.linkedin.com/ad-library/detail/1234567
```

## Response

If successful, the response body contains the standard envelope. `data` contains the ad's advertiser, text and images, and who paid for it.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "adId": "1585529084",
    "adUrl": "https://www.linkedin.com/ad-library/detail/1585529084",
    "creativeType": "SPONSORED_STATUS_UPDATE",
    "format": "Single Image Ad",
    "advertiserName": "SiteChief",
    "advertiserUrl": "https://www.linkedin.com/company/106013271",
    "advertiserAvatarUrl": "https://media.licdn.com/dms/image/v2/D560BAQH_lWh0hAuxAA/company-logo_100_100/B56aDOxwFkIQAI-/0/1790175543945/lifesafet…",
    "text": "We’ve rebranded, LifeSafety.AI is now SiteChief.\nSame team. Same UK-built platform.\nA name that matches what customers…",
    "headline": "AI Health & Safety Software for Workplace | SiteChief UK",
    "imageUrls": ["https://media.licdn.com/dms/image/sync/v2/D4E27AQGrtnvrN16TKA/articleshare-shrink_1280_800/B4EaDEgSaVJoAg-/0/1790003193…"],
    "paidBy": "PODTECH"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `paidBy` | string | The entity that paid for the ad. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Run dates, impressions and who paid show only for ads shown in the EU. Impressions by country show about 2 days after an ad starts, so a new ad has an empty countries list.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [LinkedIn ads search](/api-reference/endpoint/linkedin-ads-search): Accepts the `advertiserName` as `advertiser`. Scrape ads from the LinkedIn ad library.


# LinkedIn linkedIn Ads Search API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-ads-search

api-reference/openapi.json POST /v1/linkedin/ads/search
Scrape ads from the LinkedIn ad library. Call the LinkedIn linkedIn Ads Search API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape ads from the LinkedIn ad library.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.ads.search({ query: "software", country: "de" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.ads.search(query="software", country="de")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"software","country":"de"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin ads search software --country de
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the ads, each with its advertiser, text and images.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "1585529084",
        "adUrl": "https://www.linkedin.com/ad-library/detail/1585529084",
        "creativeType": "SPONSORED_STATUS_UPDATE",
        "format": "Single Image Ad",
        "advertiserName": "SiteChief",
        "advertiserAvatarUrl": "https://media.licdn.com/dms/image/v2/D560BAQH_lWh0hAuxAA/company-logo_100_100/B56aDOxwFkIQAI-/0/1790175543945/lifesafet…",
        "text": "We’ve rebranded, LifeSafety.AI is now SiteChief.\nSame team. Same UK-built platform.\nA name that matches what customers …",
        "headline": "AI Health & Safety Software for Workplace | SiteChief UK",
        "imageUrls": ["https://media.licdn.com/dms/image/sync/v2/D4E27AQGrtnvrN16TKA/articleshare-shrink_1280_800/B4EaDEgSaVJoAg-/0/1790003193…"]
      }
    ],
    "total": 1418027,
    "cursor": "1572358723-1791061893145"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Run dates, impressions and the paying entity are returned only by [LinkedIn ad details](/api-reference/endpoint/linkedin-ads-ad), and only for ads shown in the EU. To retrieve them, set an EU country.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `advertiser` | string | Restricts results to ads from this advertiser. |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `within` | string | Restricts results to ads shown in the last 30 days or the last year. Acceptable values are `month`, `year` and `all`. If unset, defaults to `all`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [LinkedIn ad details](/api-reference/endpoint/linkedin-ads-ad): Accepts `adUrl`. Scrape a LinkedIn ad's details.


# LinkedIn linkedIn Company API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-company

api-reference/openapi.json POST /v1/linkedin/company
Scrape a LinkedIn company page. Call the LinkedIn linkedIn Company API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a LinkedIn company page. The company is identified by its URL or ID.

## Request

Exactly one of `companyUrl` or `companyId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.company({ companyId: "microsoft" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.company(company_id="microsoft")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/company \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyId":"microsoft"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin company --companyId microsoft
```

## Response

If successful, the response body contains the standard envelope. `data` contains the company's industry, size, headquarters, website and description.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyId": "microsoft",
    "companyUrl": "https://www.linkedin.com/company/microsoft",
    "name": "Microsoft",
    "industry": "Software Development",
    "size": "10,001+ employees",
    "employees": 231728,
    "headquarters": "Redmond, Washington",
    "website": "https://news.microsoft.com/",
    "followers": 29232105,
    "description": "Every company has a mission. What's ours? To empower every person and every organization to achieve more. We believe…",
    "specialties": ["Business Software"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `size` | string | The size band LinkedIn shows for the company. |
| `employees` | integer | The employee count LinkedIn shows. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [LinkedIn jobs search](/api-reference/endpoint/linkedin-jobs-search): Accepts the company's `companyId` as `company`. Scrape LinkedIn job search results.
* [LinkedIn linkedIn Posts](/api-reference/endpoint/linkedin-posts): Accepts `companyUrl`. Scrape a person's or company's public LinkedIn posts.


# LinkedIn linkedIn Job API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-jobs-job

api-reference/openapi.json POST /v1/linkedin/jobs/job
Scrape a LinkedIn job page. Call the LinkedIn linkedIn Job API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a LinkedIn job page. The job is identified by its URL or ID.

## Request

Exactly one of `jobUrl` or `jobId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.jobs.job({ jobUrl: "https://www.linkedin.com/jobs/view/4012345678" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.jobs.job(job_url="https://www.linkedin.com/jobs/view/4012345678")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/jobs/job \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobUrl":"https://www.linkedin.com/jobs/view/4012345678"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin jobs job --jobUrl https://www.linkedin.com/jobs/view/4012345678
```

## Response

If successful, the response body contains the standard envelope. `data` contains the job's company, location, pay, seniority and description.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "4471906326",
    "jobUrl": "https://www.linkedin.com/jobs/view/4471906326",
    "title": "Software Engineer III, Foundation Services, Google Cloud",
    "companyName": "Google",
    "companyUrl": "https://www.linkedin.com/company/google",
    "companyAvatarUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQGv3cqOuUMY7g/company-logo_100_100/B4EZmhegXHGcAU-/0/1759350753990/google_lo…",
    "location": "Kirkland, WA",
    "publishedAt": "2026-09-29T00:00:00.000Z",
    "salaryMin": 147000,
    "salaryMax": 210000,
    "salaryCurrency": "USD",
    "salaryPeriod": "year",
    "salaryText": "$147000 - $210000 (USD)",
    "isEasyApply": false,
    "applicants": 80,
    "applicantsText": "80 applicants",
    "seniority": "Not Applicable",
    "employmentType": "Full-time",
    "industries": "Information Services and Technology, Information and Internet",
    "description": "In most instances, this position requires in-person interviews as part of the hiring process.\n\nIn accordance with…",
    "descriptionHtml": "In most instances, this position requires in-person interviews as part of the hiring process.<br><br>In accordance…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [LinkedIn linkedIn Company](/api-reference/endpoint/linkedin-company): Accepts `companyUrl`. Scrape a LinkedIn company page.
* [LinkedIn linkedIn Posts](/api-reference/endpoint/linkedin-posts): Accepts `companyUrl`. Scrape a person's or company's public LinkedIn posts.


# LinkedIn linkedIn Jobs Search API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-jobs-search

api-reference/openapi.json POST /v1/linkedin/jobs/search
Scrape LinkedIn job search results. Call the LinkedIn linkedIn Jobs Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape LinkedIn job search results.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.jobs.search({ query: "software engineer", location: "United States", datePosted: "pastWeek", company: ["1441", "1586"] });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.jobs.search(query="software engineer", location="United States", date_posted="pastWeek", company=["1441", "1586"])
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/jobs/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"software engineer","location":"United States","datePosted":"pastWeek","company":["1441","1586"]}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin jobs search "software engineer" --location "United States" --datePosted pastWeek --company 1441,1586
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the jobs, each with its company, location and posting date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "jobId": "4471906326",
        "jobUrl": "https://www.linkedin.com/jobs/view/4471906326",
        "title": "Software Engineer III, Foundation Services, Google Cloud",
        "companyName": "Google",
        "companyUrl": "https://www.linkedin.com/company/google",
        "companyAvatarUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQGv3cqOuUMY7g/company-logo_100_100/B4EZmhegXHGcAU-/0/1759350753990/google_lo…",
        "location": "Kirkland, WA",
        "publishedAt": "2026-09-29T00:00:00.000Z",
        "insight": "Actively Hiring"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

> [!NOTE]
>
> When nothing matches your words, LinkedIn shows other jobs.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `location` | string | The city or area to search in. |
| `datePosted` | string | Restricts results to jobs posted in this period. Acceptable values are `anyTime`, `pastMonth`, `pastWeek` and `past24Hours`. If unset, defaults to `anyTime`. |
| `company` | object | One company, or up to five. Use LinkedIn links, slugs such as `google`, or company ids. Accepts a string or an array of 1 to 5 strings. |
| `easyApply` | boolean | Restricts results to Easy Apply jobs. If unset, defaults to `false`. |
| `fewApplicants` | boolean | Restricts results to jobs with fewer than 10 applicants. If unset, defaults to `false`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.

## Related methods

* [LinkedIn job](/api-reference/endpoint/linkedin-jobs-job): Accepts `jobUrl`. Scrape a LinkedIn job page.
* [LinkedIn linkedIn Company](/api-reference/endpoint/linkedin-company): Accepts `companyUrl`. Scrape a LinkedIn company page.
* [LinkedIn linkedIn Posts](/api-reference/endpoint/linkedin-posts): Accepts `companyUrl`. Scrape a person's or company's public LinkedIn posts.


# LinkedIn linkedIn Posts API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-posts

api-reference/openapi.json POST /v1/linkedin/posts
Scrape a person's or company's public LinkedIn posts. Call the LinkedIn linkedIn Posts API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a person's or company's public LinkedIn posts. The profile or company is identified by its URL or ID.

## Request

Exactly one of `profileUrl`, `profileId`, `companyUrl` or `companyId` is required. A request that sets more than one, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.posts({ profileId: "satyanadella" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.posts(profile_id="satyanadella")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/posts \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"profileId":"satyanadella"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin posts --profileId satyanadella
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the latest public posts, each with its text, likes and date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "postId": "7509276499837902849",
        "postUrl": "https://www.linkedin.com/posts/satyanadella_the-motivation-behind-the-new-copilot-intelligence-activity-750927649983790…",
        "text": "The motivation behind the new Copilot: intelligence is accelerating fast. Now we need to diffuse it everywhere.",
        "publishedAt": "2026-09-25T15:43:53.171Z",
        "likes": 959,
        "authorName": "Satya Nadella",
        "authorUrl": "https://www.linkedin.com/in/satyanadella"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Returns the most recent public posts that LinkedIn displays for the page, including reposts. This is typically at most 10 posts. Older posts are not available, and this method is not paginated.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [LinkedIn linkedIn Profile](/api-reference/endpoint/linkedin-profile): Accepts the same `profileUrl` or `profileId`. Scrape a public LinkedIn profile.
* [LinkedIn linkedIn Company](/api-reference/endpoint/linkedin-company): Accepts the same `companyUrl` or `companyId`. Scrape a LinkedIn company page.


# LinkedIn linkedIn Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/linkedin-profile

api-reference/openapi.json POST /v1/linkedin/profile
Scrape a public LinkedIn profile. Call the LinkedIn linkedIn Profile API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape a public LinkedIn profile. The profile is identified by its URL or ID.

## Request

Exactly one of `profileUrl` or `profileId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.profile({ profileId: "satyanadella" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.profile(profile_id="satyanadella")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"profileId":"satyanadella"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin profile --profileId satyanadella
```

## Response

If successful, the response body contains the standard envelope. `data` contains the person's headline, location, about text, roles and education.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "profileId": "satyanadella",
    "profileUrl": "https://www.linkedin.com/in/satyanadella",
    "name": "Satya Nadella",
    "headline": "Chairman and CEO at Microsoft",
    "location": "Redmond, Washington, United States",
    "about": "As chairman and CEO of Microsoft, I define my mission and that of my company as empowering every person and every…",
    "followers": 12205170,
    "roles": [
      {
        "title": "Chairman and CEO",
        "companyName": "Microsoft",
        "companyUrl": "https://www.linkedin.com/company/microsoft",
        "from": "Feb 2014",
        "isCurrent": true
      }
    ],
    "education": [
      {
        "school": "The University of Chicago Booth School of Business",
        "schoolUrl": "https://www.linkedin.com/school/universityofchicagoboothschoolofbusiness",
        "from": "1994",
        "to": "1996"
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `roles` | object\[] | The person's jobs. `isCurrent` marks the current one. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [LinkedIn linkedIn Company](/api-reference/endpoint/linkedin-company): Accepts `companyUrl`. Scrape a LinkedIn company page.
* [LinkedIn linkedIn Posts](/api-reference/endpoint/linkedin-posts): Accepts `profileUrl`. Scrape a person's or company's public LinkedIn posts.


# Meta Ads meta Ad API
Source: https://docs.stophy.dev/api-reference/endpoint/meta-ads-ad

api-reference/openapi.json POST /v1/meta/ads/ad
Scrape a Meta ad's details. Call the Meta Ads meta Ad API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Meta ad's details. The ad is identified by its URL or ID.

## Request

Exactly one of `adUrl` or `adId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.meta.ads.ad({ adUrl: "https://www.facebook.com/ads/library/?id=1234567890123456" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.meta.ads.ad(ad_url="https://www.facebook.com/ads/library/?id=1234567890123456")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/meta/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"adUrl":"https://www.facebook.com/ads/library/?id=1234567890123456"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy meta ads ad --adUrl "https://www.facebook.com/ads/library/?id=1234567890123456"
```

## Response

If successful, the response body contains the standard envelope. `data` contains the ad's page, text, format, platforms and the advertiser's details.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "adId": "925321173274919",
    "adUrl": "https://www.facebook.com/ads/library/?id=925321173274919",
    "pageId": "89516513179",
    "pageName": "Nordstrom Rack",
    "pageUrl": "https://facebook.com/NordstromRack",
    "pageAvatarUrl": "https://scontent-mia5-1.xx.fbcdn.net/v/t39.35426-6/764807066_1529917005842224_1129201910993892893_n.jpg?stp=dst-jpg_s60…",
    "pageCategories": ["Clothing (Brand)"],
    "pageLikes": 2518828,
    "isActive": true,
    "firstShownAt": "2026-08-03T07:00:00.000Z",
    "platforms": ["facebook"],
    "format": "video",
    "text": "Buy online and pick up in store for free! Get up to 70% off Nike, Vince, Madewell, adidas and more.",
    "linkUrl": "https://fb.com/canvas_doc/1072291375736811",
    "linkTitle": "Fast & Free Pickup",
    "linkDescription": "Fast & Free Pickup",
    "ctaText": "Learn more",
    "videoUrls": ["https://video-mia5-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQPMHFeiZ7eLWAaUSfl9UjSZ2QaJHkx2VTZvZtGQn2Lri3AqZsR0B4SYnzTlS8BwXd3tu…"],
    "versions": 1,
    "advertiserDescription": "www.youtube.com/@TheNordstromRack\nwww.instagram.com/nordstromrack\nwww.twitter.com/nordstromrack \nwww.",
    "advertiserCategory": "Clothing (Brand)",
    "advertiserVerification": "BLUE_VERIFIED",
    "advertiserInstagram": "nordstromrack",
    "advertiserInstagramFollowers": 1474538
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `firstShownAt` | string (ISO 8601) | The first day the ad was shown. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Meta ads by page](/api-reference/endpoint/meta-ads-page): Accepts the ad's `pageId` as `advertiser`. Scrape the ads a Facebook page runs.


# Meta Ads meta Ads Page API
Source: https://docs.stophy.dev/api-reference/endpoint/meta-ads-page

api-reference/openapi.json POST /v1/meta/ads/page
Scrape the ads a Facebook page runs. Call the Meta Ads meta Ads Page API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape the ads a Facebook page runs.

## Request

`advertiser` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.meta.ads.page({ advertiser: "89516513179", country: "us", status: "active", mediaType: "image" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.meta.ads.page(advertiser="89516513179", country="us", status="active", media_type="image")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/meta/ads/page \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"advertiser":"89516513179","country":"us","status":"active","mediaType":"image"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy meta ads page 89516513179 --country us --status active --mediaType image
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the ads the page runs, each with its text, format and platforms.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "1789492875400267",
        "adUrl": "https://www.facebook.com/ads/library/?id=1789492875400267",
        "pageId": "89516513179",
        "pageName": "Nordstrom Rack",
        "pageUrl": "https://facebook.com/NordstromRack",
        "pageAvatarUrl": "https://scontent-mia3-2.xx.fbcdn.net/v/t39.35426-6/762676880_1995711797802100_2468483212592961094_n.jpg?stp=dst-jpg_s60…",
        "pageCategories": ["Clothing (Brand)"],
        "pageLikes": 2518828,
        "isActive": true,
        "firstShownAt": "2026-08-03T07:00:00.000Z",
        "platforms": ["facebook", "instagram"],
        "format": "dpa",
        "text": "Save up to 70% off top brands.",
        "linkUrl": "https://www.nordstromrack.com/",
        "ctaText": "Shop now",
        "cards": [
          {
            "text": "Save up to 70% off top brands.",
            "linkUrl": "https://www.nordstromrack.com/s/14th-and-union-the-wallin-stretch-twill-trim-fit-chino-pants-30-34-inseam/8925507",
            "linkTitle": "14th & Union The Wallin Stretch Twill Trim Fit Chino Pants - 30-34\" Inseam",
            "ctaText": "Shop Now",
            "imageUrl": "https://scontent-mia3-3.xx.fbcdn.net/v/t39.35426-6/762676781_1036954042308934_4193412466397981962_n.jpg?_nc_cat=107&ccb…"
          }
        ],
        "versions": 1,
        "countries": ["US"]
      }
    ],
    "cursor": "AQHTYm1gog6XNyvJ--FrIKuEKkEAPrxD9q6sGYtVGkuUcpUvlW1kMfUmNB0aT9A-8zoD"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `firstShownAt` | string (ISO 8601) | The first day the ad was shown. |
| `countries` | string\[] | Countries the Ad Library says the ad ran in. Meta sends none for most ads, so an empty list means unknown, not worldwide. It is not the country you searched. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code, or `all`. If unset, defaults to `us`. |
| `status` | string | Active ads, inactive ads or both. Acceptable values are `active`, `inactive` and `all`. If unset, defaults to `active`. |
| `mediaType` | string | Restricts results to ads of this type. `text` means no image or video. Acceptable values are `image`, `video` and `text`. |
| `platforms` | string\[] | Restricts results to ads shown on at least one of these platforms. Acceptable values are `facebook`, `instagram`, `audienceNetwork`, `messenger`, `whatsapp` and `threads`. |
| `language` | string | Restricts results to ads written in this language. Two-letter code, such as `en`. |
| `shownFrom` | string (date) | Restricts results to ads shown on or after this day. Format: `YYYY-MM-DD`. |
| `shownTo` | string (date) | Restricts results to ads shown on or before this day. Format: `YYYY-MM-DD`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Meta ad details](/api-reference/endpoint/meta-ads-ad): Accepts `adUrl`. Scrape a Meta ad's details.


# Meta Ads meta Ads Search API
Source: https://docs.stophy.dev/api-reference/endpoint/meta-ads-search

api-reference/openapi.json POST /v1/meta/ads/search
Scrape ads from the Meta ad library. Call the Meta Ads meta Ads Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape ads from the Meta ad library.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.meta.ads.search({ query: "nike", platforms: ["instagram"], language: "en" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.meta.ads.search(query="nike", platforms=["instagram"], language="en")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/meta/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike","platforms":["instagram"],"language":"en"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy meta ads search nike --platforms instagram --language en
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the ads that match, each with its page, text, format and platforms.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "925321173274919",
        "adUrl": "https://www.facebook.com/ads/library/?id=925321173274919",
        "pageId": "89516513179",
        "pageName": "Nordstrom Rack",
        "pageUrl": "https://facebook.com/NordstromRack",
        "pageAvatarUrl": "https://scontent-mia5-1.xx.fbcdn.net/v/t39.35426-6/764807066_1529917005842224_1129201910993892893_n.jpg?stp=dst-jpg_s60…",
        "pageCategories": ["Clothing (Brand)"],
        "pageLikes": 2518828,
        "isActive": true,
        "firstShownAt": "2026-08-03T07:00:00.000Z",
        "platforms": ["facebook", "instagram"],
        "format": "video",
        "text": "Buy online and pick up in store for free! Get up to 70% off Nike, Vince, Madewell, adidas and more.",
        "linkUrl": "https://fb.com/canvas_doc/1072291375736811",
        "linkTitle": "Fast & Free Pickup",
        "linkDescription": "Fast & Free Pickup",
        "ctaText": "Learn more",
        "videoUrls": ["https://video-mia5-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQPMHFeiZ7eLWAaUSfl9UjSZ2QaJHkx2VTZvZtGQn2Lri3AqZsR0B4SYnzTlS8BwXd3tu…"],
        "versions": 2,
        "countries": ["US"]
      }
    ],
    "cursor": "AQHTwHM-vkpydSiDv773CcWZ17K3G0tZFLBXM2TO_cva3F8YzTvrI9ZkLpDUZtrHRCPc"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `firstShownAt` | string (ISO 8601) | The first day the ad was shown. |
| `countries` | string\[] | Countries the Ad Library says the ad ran in. Meta sends none for most ads, so an empty list means unknown, not worldwide. It is not the country you searched. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code, or `all`. If unset, defaults to `us`. |
| `status` | string | Active ads, inactive ads or both. Acceptable values are `active`, `inactive` and `all`. If unset, defaults to `active`. |
| `mediaType` | string | Restricts results to ads of this type. `text` means no image or video. Acceptable values are `image`, `video` and `text`. |
| `platforms` | string\[] | Restricts results to ads shown on at least one of these platforms. Acceptable values are `facebook`, `instagram`, `audienceNetwork`, `messenger`, `whatsapp` and `threads`. |
| `language` | string | Restricts results to ads written in this language. Two-letter code, such as `en`. |
| `shownFrom` | string (date) | Restricts results to ads shown on or after this day. Format: `YYYY-MM-DD`. |
| `shownTo` | string (date) | Restricts results to ads shown on or before this day. Format: `YYYY-MM-DD`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Meta ads by page](/api-reference/endpoint/meta-ads-page): Accepts an ad's `pageId` as `advertiser`. Scrape the ads a Facebook page runs.
* [Meta ad details](/api-reference/endpoint/meta-ads-ad): Accepts `adUrl`. Scrape a Meta ad's details.


# Pinterest pinterest Board API
Source: https://docs.stophy.dev/api-reference/endpoint/pinterest-board

api-reference/openapi.json POST /v1/pinterest/board
Scrape a Pinterest board and its pins. Call the Pinterest pinterest Board API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Pinterest board and its pins.

## Request

`boardUrl` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.pinterest.board({ boardUrl: "https://www.pinterest.com/marthastewart/kitchen-ideas/" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.pinterest.board(board_url="https://www.pinterest.com/marthastewart/kitchen-ideas/")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/pinterest/board \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"boardUrl":"https://www.pinterest.com/marthastewart/kitchen-ideas/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy pinterest board https://www.pinterest.com/marthastewart/kitchen-ideas/
```

## Response

If successful, the response body contains the standard envelope. `data` contains the board's details, and `results` lists a page of its pins.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "boardId": "49328627107623443",
    "boardUrl": "https://www.pinterest.com/herbacinusa/fresh-fall-ideas/",
    "name": "Fresh Fall Ideas",
    "description": "Ideas for beauty, design, relaxation, and home decor",
    "category": "design",
    "pins": 301,
    "followers": 6163,
    "sections": 0,
    "thumbnailUrl": "https://i.pinimg.com/custom_covers/200x150/49328627107623443_1411083601.jpg",
    "authorId": "49328695826977854",
    "authorUsername": "herbacinusa",
    "authorName": "Herbacin",
    "authorUrl": "https://www.pinterest.com/herbacinusa/",
    "authorAvatarUrl": "https://i.pinimg.com/280x280_RS/54/37/a0/5437a0983226a913dc32d0beb98c1066.jpg",
    "results": [
      {
        "pinId": "49328558401525132",
        "pinUrl": "https://www.pinterest.com/pin/49328558401525132/",
        "text": "Fall Flower Arrangements | Martha Stewart Living - Gather armfuls of vivid leaves and berries from the garden before…",
        "altText": "a vase filled with red and purple flowers on top of a wooden table next to books",
        "linkUrl": "http://martha.ms/64958xCG7",
        "domain": "martha.ms",
        "publishedAt": "2017-08-26T19:52:00.000Z",
        "imageUrl": "https://i.pinimg.com/originals/cd/cb/6b/cdcb6ba072222d490f05c11a98ead99e.jpg",
        "imageWidth": 1040,
        "imageHeight": 1300,
        "dominantColor": "#876f75",
        "saves": 100,
        "reposts": 9,
        "isPromoted": false,
        "authorId": "32088353503445352",
        "authorUsername": "marthastewart",
        "authorName": "Martha Stewart",
        "authorUrl": "https://www.pinterest.com/marthastewart/",
        "authorAvatarUrl": "https://i.pinimg.com/140x140_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg",
        "authorIsVerified": true,
        "boardId": "49328627107623443",
        "boardName": "Fresh Fall Ideas",
        "boardUrl": "https://www.pinterest.com/herbacinusa/fresh-fall-ideas/"
      }
    ],
    "cursor": "Y2JZakk0ZVU1WWR6Qk9SRWswVDBSak5VNUVVWHBQUkdkNlRsUm5NMHRyWkZKVVEzQTRUV3ByZVZsWFZUVk5SR2hwV20xWk0xbFhVVE5PZW14cVRYcEdiRTF…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Pinterest pinterest Pin](/api-reference/endpoint/pinterest-pin): Accepts `pinUrl`. Scrape a Pinterest pin.
* [Pinterest pinterest Profile](/api-reference/endpoint/pinterest-profile): Accepts `userUrl`. Scrape a Pinterest profile and its pins.


# Pinterest pinterest Pin API
Source: https://docs.stophy.dev/api-reference/endpoint/pinterest-pin

api-reference/openapi.json POST /v1/pinterest/pin
Scrape a Pinterest pin. Call the Pinterest pinterest Pin API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Pinterest pin. The pin is identified by its URL or ID.

## Request

Exactly one of `pinUrl` or `pinId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.pinterest.pin({ pinUrl: "https://www.pinterest.com/pin/1234567890123456/" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.pinterest.pin(pin_url="https://www.pinterest.com/pin/1234567890123456/")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/pinterest/pin \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"pinUrl":"https://www.pinterest.com/pin/1234567890123456/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy pinterest pin --pinUrl https://www.pinterest.com/pin/1234567890123456/
```

## Response

If successful, the response body contains the standard envelope. `data` contains the pin's image, link, saves and author.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "pinId": "1009298966511632539",
    "pinUrl": "https://www.pinterest.com/pin/1009298966511632539/",
    "title": "Explore Montauk Gin 2x8 White Ceramic Subway Wall Tile with Mixed Finish",
    "text": "The Montauk Gin 2x8 White Ceramic Wall Tile reimagines the subway format in durable ceramic—with a distinctively…",
    "linkUrl": "https://www.tilebar.com/montauk-gin-2x8-ceramic-wall-tile-satin.html",
    "domain": "tilebar.com",
    "publishedAt": "2026-09-30T17:05:55.000Z",
    "imageUrl": "https://i.pinimg.com/originals/bc/54/e8/bc54e89cd5e3e093314c3349401ec38e.png",
    "imageWidth": 1000,
    "imageHeight": 1600,
    "dominantColor": "#846c4c",
    "saves": 6250,
    "reposts": 11,
    "comments": 3,
    "reactions": 55,
    "isPromoted": false,
    "authorId": "101049722797560631",
    "authorUsername": "TileBar",
    "authorName": "TileBar",
    "authorUrl": "https://www.pinterest.com/TileBar/",
    "authorAvatarUrl": "https://i.pinimg.com/75x75_RS/8f/8a/2c/8f8a2c4d5a9240a454dd99d3703bc0eb.jpg",
    "boardId": "1009299035180023573",
    "boardName": "Guardado rápido",
    "boardUrl": "https://www.pinterest.com/ibanezpereza/_quick_saves/"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Pinterest pinterest Board](/api-reference/endpoint/pinterest-board): Accepts `boardUrl`. Scrape a Pinterest board and its pins.
* [Pinterest pinterest Profile](/api-reference/endpoint/pinterest-profile): Accepts `userUrl`. Scrape a Pinterest profile and its pins.


# Pinterest pinterest Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/pinterest-profile

api-reference/openapi.json POST /v1/pinterest/profile
Scrape a Pinterest profile and its pins. Call the Pinterest pinterest Profile API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a Pinterest profile and its pins. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.pinterest.profile({ username: "marthastewart" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.pinterest.profile(username="marthastewart")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/pinterest/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"marthastewart"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy pinterest profile --username marthastewart
```

## Response

If successful, the response body contains the standard envelope. `data` contains the profile's bio and counts, and `results` lists a page of its pins.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "32088353503445352",
    "username": "marthastewart",
    "userUrl": "https://www.pinterest.com/marthastewart/",
    "name": "Martha Stewart",
    "avatarUrl": "https://i.pinimg.com/280x280_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg",
    "followers": 1868060,
    "bio": "Daily recipes, crafts, and inspiration from Martha Stewart.",
    "website": "http://marthastewart.com",
    "following": 322,
    "pins": 105458,
    "boards": 174,
    "isVerified": true,
    "isPrivate": false,
    "createdAt": "2011-09-15T07:56:17.000Z",
    "results": [
      {
        "pinId": "49328558414951308",
        "pinUrl": "https://www.pinterest.com/pin/49328558414951308/",
        "title": "Do Mums Come Back Every Year? How to Keep Them Blooming Each Fall",
        "text": "Yes, perennial mums will come back every year—if you care for them the right way. Here, gardening experts provide some…",
        "altText": "many pink flowers are growing in the garden",
        "linkUrl": "https://www.marthastewart.com/do-mums-come-back-every-year-12159330?utm_campaign=marthastewart_6ac401c97b1ba300014d59a4…",
        "domain": "marthastewart.com",
        "publishedAt": "2026-10-05T20:00:09.000Z",
        "imageUrl": "https://i.pinimg.com/originals/4f/fa/68/4ffa68ab16dd1768bcb1879e149da1a9.jpg",
        "imageWidth": 1000,
        "imageHeight": 667,
        "dominantColor": "#552626",
        "saves": 1,
        "reposts": 0,
        "comments": 0,
        "isPromoted": false,
        "authorId": "32088353503445352",
        "authorUsername": "marthastewart",
        "authorName": "Martha Stewart",
        "authorUrl": "https://www.pinterest.com/marthastewart/",
        "authorAvatarUrl": "https://i.pinimg.com/140x140_RS/c8/11/4c/c8114c783347e27daef00e5d4a6ac4f3.jpg",
        "authorIsVerified": true,
        "boardId": "49328627107623443",
        "boardName": "Fresh Fall Ideas",
        "boardUrl": "https://www.pinterest.com/herbacinusa/fresh-fall-ideas/"
      }
    ],
    "cursor": "Pz8zMjA4ODIxNjA5OTcwODU1NToxNzkwOTc0ODEyfDEwNDU2ODY4NTYyODM4NzEqR1FMKnxmZjliM2VkOGEzYzE4MjQ0NDAxZjA5ODdjMTg3OWIwYTAyYzZ…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Pinterest pinterest Pin](/api-reference/endpoint/pinterest-pin): Accepts `pinUrl`. Scrape a Pinterest pin.
* [Pinterest pinterest Board](/api-reference/endpoint/pinterest-board): Accepts `boardUrl`. Scrape a Pinterest board and its pins.


# Pinterest pinterest Search API
Source: https://docs.stophy.dev/api-reference/endpoint/pinterest-search

api-reference/openapi.json POST /v1/pinterest/search
Scrape Pinterest search results. Call the Pinterest pinterest Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Pinterest search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.pinterest.search({ query: "kitchen ideas" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.pinterest.search(query="kitchen ideas")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/pinterest/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"kitchen ideas"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy pinterest search "kitchen ideas"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the pins or videos, each with its image, link and author.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "pinId": "1009298966511632539",
        "pinUrl": "https://www.pinterest.com/pin/1009298966511632539/",
        "title": "Explore Montauk Gin 2x8 White Ceramic Subway Wall Tile with Mixed Finish",
        "text": "The Montauk Gin 2x8 White Ceramic Wall Tile reimagines the subway format in durable ceramic—with a distinctively…",
        "altText": "a kitchen with wooden cabinets and white counter tops",
        "linkUrl": "https://www.tilebar.com/montauk-gin-2x8-ceramic-wall-tile-satin.html",
        "domain": "tilebar.com",
        "publishedAt": "2026-09-30T17:05:55.000Z",
        "imageUrl": "https://i.pinimg.com/originals/bc/54/e8/bc54e89cd5e3e093314c3349401ec38e.png",
        "imageWidth": 1000,
        "imageHeight": 1600,
        "dominantColor": "#846c4c",
        "reactions": 55,
        "isPromoted": false,
        "authorId": "1009299103898863825",
        "authorUsername": "ibanezpereza",
        "authorName": "Ibanezperez Ana",
        "authorUrl": "https://www.pinterest.com/ibanezpereza/",
        "authorAvatarUrl": "https://s.pinimg.com/images/user/default_140.png",
        "boardId": "1009299035180023573",
        "boardName": "Guardado rápido",
        "boardUrl": "https://www.pinterest.com/ibanezpereza/_quick_saves/"
      }
    ],
    "cursor": "Y2JVSG81V2sxcmNHRlpWM1J5VFVad1YxWllaR3hpVmtZMldWVlZNV0ZIUlhoV2FscFhVa1ZhVkZWdE1WZFdhekZWVjJ4V1YxSlZjRkZYYkdONFlXMVJlRlZ…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | Pins or videos. Acceptable values are `pins` and `videos`. If unset, defaults to `pins`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Pinterest pinterest Pin](/api-reference/endpoint/pinterest-pin): Accepts `pinUrl`. Scrape a Pinterest pin.
* [Pinterest pinterest Board](/api-reference/endpoint/pinterest-board): Accepts `boardUrl`. Scrape a Pinterest board and its pins.
* [Pinterest pinterest Profile](/api-reference/endpoint/pinterest-profile): Accepts `userUrl`. Scrape a Pinterest profile and its pins.


# Reddit reddit Other Discussions API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-discussions

api-reference/openapi.json POST /v1/reddit/discussions
Scrape where else a link was shared on Reddit. Call the Reddit reddit Other Discussions API for JSON. 1 credit per call.

Scrape where else a link was shared on Reddit. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.discussions({ postUrl: "https://www.reddit.com/r/programming/comments/1abc2de/example_post/" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.discussions(post_url="https://www.reddit.com/r/programming/comments/1abc2de/example_post/")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/discussions \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postUrl":"https://www.reddit.com/r/programming/comments/1abc2de/example_post/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit discussions --postUrl https://www.reddit.com/r/programming/comments/1abc2de/example_post/
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the posts that shared the same link.

The following example is illustrative.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "post",
        "postId": "1abc2de",
        "postUrl": "https://www.reddit.com/r/programming/comments/1abc2de/example_post/",
        "title": "Example article worth reading",
        "authorUsername": "example_user",
        "subreddit": "programming",
        "score": 412,
        "upvotePercent": 96,
        "comments": 58,
        "publishedAt": "2026-10-02T14:20:00.000Z",
        "isNsfw": false,
        "isVideo": false,
        "isPinned": false
      }
    ],
    "cursor": "t3_1abc2de"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `post`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `score` | integer | Upvotes minus downvotes. |
| `upvotePercent` | number | The share of votes that are upvotes, as a percentage. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Post](/api-reference/endpoint/reddit-post): Accepts `postUrl`. Scrape a Reddit post and its comments.
* [Reddit reddit Subreddit](/api-reference/endpoint/reddit-subreddit): Accepts `subreddit`. Scrape a subreddit and its posts.
* [Reddit reddit User](/api-reference/endpoint/reddit-user): Accepts `userUrl`. Scrape a Reddit user's profile, posts and comments.


# Reddit reddit Post API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-post

api-reference/openapi.json POST /v1/reddit/post
Scrape a Reddit post and its comments. Call the Reddit reddit Post API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Reddit post and its comments. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.post({ postUrl: "https://www.reddit.com/r/programming/comments/1abc2de/example_post/" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.post(post_url="https://www.reddit.com/r/programming/comments/1abc2de/example_post/")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postUrl":"https://www.reddit.com/r/programming/comments/1abc2de/example_post/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit post --postUrl https://www.reddit.com/r/programming/comments/1abc2de/example_post/
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post, and `results` lists its comments.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "1wxj3er",
    "postUrl": "https://www.reddit.com/r/AskReddit/comments/1wxj3er/men_whats_one_small_seemingly_insignificant_thing/",
    "title": "Men, what’s one small, seemingly insignificant thing you’ve noticed that can be a telltale sign of the difference…",
    "authorId": "ojjf3gg0x",
    "authorUsername": "AuthorConfident9386",
    "authorUrl": "https://www.reddit.com/user/AuthorConfident9386/",
    "subreddit": "AskReddit",
    "score": 5312,
    "upvotePercent": 89,
    "comments": 2349,
    "publishedAt": "2026-10-04T15:56:50.000Z",
    "isNsfw": false,
    "isVideo": false,
    "isPinned": false,
    "results": [
      {
        "commentId": "pdu7cxe",
        "commentUrl": "https://www.reddit.com/r/AskReddit/comments/1wxj3er/men_whats_one_small_seemingly_insignificant_thing/pdu7cxe/",
        "authorId": "aug9d",
        "authorUsername": "s0ulfire",
        "authorUrl": "https://www.reddit.com/user/s0ulfire/",
        "text": "Ability to admit one’s mistake ",
        "score": 5756,
        "publishedAt": "2026-10-04T16:47:49.000Z",
        "depth": 0,
        "isSubmitter": false,
        "isPinned": false
      }
    ],
    "cursor": "8f1d680b-d686-4b78-a88e-7334dcfa10d1"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | Pass it as `cursor` to retrieve the rest of the comments. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `score` | integer | Upvotes minus downvotes. |
| `upvotePercent` | number | The share of votes that are upvotes, as a percentage. |
| `depth` | integer | The nesting level of the comment in the thread. Top-level comments are 0. |
| `isSubmitter` | boolean | `true` if the commenter is the author of the post. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `comment` | string | A comment id or link. Returns that comment's thread. |
| `sort` | string | Specifies the order of the comments. Acceptable values are `best`, `top`, `newest`, `controversial`, `old` and `qa`. If unset, defaults to `best`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Subreddit](/api-reference/endpoint/reddit-subreddit): Accepts `subreddit`. Scrape a subreddit and its posts.
* [Reddit reddit Other Discussions](/api-reference/endpoint/reddit-discussions): Accepts `postUrl`. Scrape where else a link was shared on Reddit.
* [Reddit reddit User](/api-reference/endpoint/reddit-user): Accepts `userUrl`. Scrape a Reddit user's profile, posts and comments.


# Reddit reddit Search API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-search

api-reference/openapi.json POST /v1/reddit/search
Scrape Reddit search results. Call the Reddit reddit Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Reddit search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.search({ query: "typescript" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.search(query="typescript")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"typescript"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit search typescript
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains posts, subreddits or users, depending on `type`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "post",
        "postId": "1vn2sjm",
        "postUrl": "https://www.reddit.com/r/typescript/comments/1vn2sjm/i_would_like_to_personally_apologize_to_the/",
        "title": "I would like to personally apologize to the creators of TypeScript",
        "text": "When I first started using it for work I hated it and cursed it. The syntax was weird and confusing. Annoying type…",
        "authorId": "klojyedp",
        "authorUsername": "PusheenHater",
        "authorUrl": "https://www.reddit.com/user/PusheenHater/",
        "subreddit": "typescript",
        "score": 236,
        "upvotePercent": 91,
        "comments": 71,
        "publishedAt": "2026-08-13T06:27:01.000Z",
        "isNsfw": false,
        "isVideo": false,
        "isPinned": false
      }
    ],
    "cursor": "t3_1lk2fng"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `post`, `subreddit` or `user`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `score` | integer | Upvotes minus downvotes. |
| `upvotePercent` | number | The share of votes that are upvotes, as a percentage. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | Specifies the kind of result to search for. Acceptable values are `posts`, `subreddits` and `users`. If unset, defaults to `posts`. |
| `subreddit` | string | Search inside one subreddit. |
| `sort` | string | `relevance` matches the words anywhere in a post. The other sorts match the exact phrase. Acceptable values are `relevance`, `hot`, `top`, `newest` and `mostComments`. If unset, defaults to `relevance`. |
| `time` | string | Restricts results to posts from this period. Leave it out for Reddit's default. Acceptable values are `pastHour`, `today`, `pastWeek`, `pastMonth`, `pastYear` and `allTime`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Post](/api-reference/endpoint/reddit-post): Accepts `postUrl`. Scrape a Reddit post and its comments.
* [Reddit reddit Subreddit](/api-reference/endpoint/reddit-subreddit): Accepts `subreddit`. Scrape a subreddit and its posts.
* [Reddit reddit User](/api-reference/endpoint/reddit-user): Accepts `userUrl`. Scrape a Reddit user's profile, posts and comments.
* [Reddit reddit Other Discussions](/api-reference/endpoint/reddit-discussions): Accepts `postUrl`. Scrape where else a link was shared on Reddit.


# Reddit reddit Subreddit API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-subreddit

api-reference/openapi.json POST /v1/reddit/subreddit
Scrape a subreddit and its posts. Call the Reddit reddit Subreddit API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a subreddit and its posts.

## Request

`subreddit` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.subreddit({ subreddit: "AskReddit" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.subreddit(subreddit="AskReddit")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/subreddit \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"subreddit":"AskReddit"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit subreddit AskReddit
```

## Response

If successful, the response body contains the standard envelope. `data` contains the subreddit's details and rules, and `results` lists a page of its posts.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "subredditId": "2qh1i",
    "subredditName": "AskReddit",
    "subredditUrl": "https://www.reddit.com/r/AskReddit/",
    "title": "Ask Reddit...",
    "description": "r/AskReddit is the place to ask and answer thought-provoking questions.",
    "members": 59813591,
    "createdAt": "2008-01-25T03:52:15.000Z",
    "avatarUrl": "https://styles.redditmedia.com/t5_2qh1i/styles/communityIcon_p6kb2m6b185b1.png?width=256&s=c28b9f038c305e139b62739f2133…",
    "isNsfw": false,
    "rules": [
      {
        "title": "Rule 1 - Questions must be clear and direct and may not use the body textbox",
        "description": "* All questions must be clear, written in English, and conclude with a question mark\n* All context in the title must…"
      }
    ],
    "results": [
      {
        "type": "post",
        "postId": "1w6eajz",
        "postUrl": "https://www.reddit.com/r/AskReddit/comments/1w6eajz/askreddit_is_looking_for_new_moderators/",
        "title": "AskReddit is looking for new moderators!",
        "text": "As you can probably imagine, r/AskReddit is very busy with nearly 60 million members, over a million comments posted…",
        "authorId": "ytpt7",
        "authorUsername": "AskRedditModerators",
        "authorUrl": "https://www.reddit.com/user/AskRedditModerators/",
        "subreddit": "AskReddit",
        "score": 208,
        "upvotePercent": 93,
        "comments": 0,
        "publishedAt": "2026-09-03T17:39:04.000Z",
        "flair": "Modpost",
        "isNsfw": false,
        "isVideo": false,
        "isPinned": true
      }
    ],
    "cursor": "t3_1wyi2sl"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `post`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `score` | integer | Upvotes minus downvotes. |
| `upvotePercent` | number | The share of votes that are upvotes, as a percentage. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | Specifies the order of the results. Acceptable values are `hot`, `newest`, `top`, `rising` and `controversial`. If unset, defaults to `hot`. |
| `time` | string | Restricts results to posts from this period. Leave it out for Reddit's default. Acceptable values are `pastHour`, `today`, `pastWeek`, `pastMonth`, `pastYear` and `allTime`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Post](/api-reference/endpoint/reddit-post): Accepts `postUrl`. Scrape a Reddit post and its comments.
* [Reddit reddit Other Discussions](/api-reference/endpoint/reddit-discussions): Accepts `postUrl`. Scrape where else a link was shared on Reddit.
* [Reddit reddit User](/api-reference/endpoint/reddit-user): Accepts `userUrl`. Scrape a Reddit user's profile, posts and comments.


# Reddit reddit Communities API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-subreddits

api-reference/openapi.json POST /v1/reddit/subreddits
Scrape Reddit's popular or newest communities. Call the Reddit reddit Communities API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape Reddit's popular or newest communities.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.subreddits({ sort: "popular" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.subreddits(sort="popular")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/subreddits \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"sort":"popular"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit subreddits --sort popular
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the communities.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "subreddit",
        "subredditId": "2qs0k",
        "subredditName": "Home",
        "subredditUrl": "https://www.reddit.com/r/Home/",
        "title": "Home",
        "members": 432281,
        "createdAt": "2009-01-25T02:25:57.000Z",
        "isNsfw": false
      }
    ],
    "cursor": "t5_2cneq"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `subreddit`. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | Specifies which communities are returned first. Acceptable values are `popular` and `newest`. If unset, defaults to `popular`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Subreddit](/api-reference/endpoint/reddit-subreddit): Accepts `subreddit`. Scrape a subreddit and its posts.


# Reddit reddit User API
Source: https://docs.stophy.dev/api-reference/endpoint/reddit-user

api-reference/openapi.json POST /v1/reddit/user
Scrape a Reddit user's profile, posts and comments. Call the Reddit reddit User API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a Reddit user's profile, posts and comments. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.user({ username: "spez" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.user(username="spez")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/user \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"spez"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit user --username spez
```

## Response

If successful, the response body contains the standard envelope. `data` contains the user's profile and karma, and `results` lists a page of their posts and comments.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "1w72",
    "username": "spez",
    "userUrl": "https://www.reddit.com/user/spez/",
    "postKarma": 184509,
    "commentKarma": 756493,
    "createdAt": "2005-06-06T04:00:00.000Z",
    "avatarUrl": "https://styles.redditmedia.com/t5_3k30p/styles/profileIcon_uj015iwx9s7g1.png?width=256&height=256&crop=256:256,smart&s=…",
    "isVerified": true,
    "results": [
      {
        "type": "comment",
        "commentId": "p1wosm9",
        "commentUrl": "https://www.reddit.com/r/u_spez/comments/1vgbkge/modernizing_reddits_infrastructure_with_you/p1wosm9/",
        "text": "That was the thinking. Otherwise it would be easier to just replicate the UI. ",
        "score": 13,
        "publishedAt": "2026-08-05T18:31:50.000Z",
        "subreddit": "u_spez",
        "postId": "1vgbkge",
        "postTitle": "Modernizing Reddit’s infrastructure with you"
      },
      {
        "type": "post",
        "postId": "1vgbkge",
        "postUrl": "https://www.reddit.com/r/u_spez/comments/1vgbkge/modernizing_reddits_infrastructure_with_you/",
        "title": "Modernizing Reddit’s infrastructure with you",
        "text": "Hi everyone,\n\nLast May, I shared how we were building Reddit for its [next…",
        "authorId": "1w72",
        "authorUsername": "spez",
        "authorUrl": "https://www.reddit.com/user/spez/",
        "subreddit": "u_spez",
        "score": 350,
        "upvotePercent": 84,
        "comments": 472,
        "publishedAt": "2026-08-05T16:03:56.000Z",
        "thumbnailUrl": "https://external-preview.redd.it/-_NM9QKmwnaF7Ti3sXwY6oJD9PVQrQGXBx1288oLFXw.png?auto=webp&s=58d39b335111d200e60a1e6fa3…",
        "isNsfw": false,
        "isVideo": false,
        "isPinned": false
      }
    ],
    "cursor": "t1_opmb76u"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `post` or `comment`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `score` | integer | Upvotes minus downvotes. |
| `upvotePercent` | number | The share of votes that are upvotes, as a percentage. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `tab` | string | Specifies which part of the profile to read. Acceptable values are `overview`, `posts` and `comments`. If unset, defaults to `overview`. |
| `sort` | string | Specifies the order of the results. Acceptable values are `newest`, `hot`, `top` and `controversial`. If unset, defaults to `newest`. |
| `time` | string | Restricts results to posts from this period. Leave it out for Reddit's default. Acceptable values are `pastHour`, `today`, `pastWeek`, `pastMonth`, `pastYear` and `allTime`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Reddit reddit Post](/api-reference/endpoint/reddit-post): Accepts `postUrl`. Scrape a Reddit post and its comments.
* [Reddit reddit Subreddit](/api-reference/endpoint/reddit-subreddit): Accepts `subreddit`. Scrape a subreddit and its posts.
* [Reddit reddit Other Discussions](/api-reference/endpoint/reddit-discussions): Accepts `postUrl`. Scrape where else a link was shared on Reddit.


# Threads threads Post API
Source: https://docs.stophy.dev/api-reference/endpoint/threads-post

api-reference/openapi.json POST /v1/threads/post
Scrape a Threads post and its replies. Call the Threads threads Post API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Threads post and its replies. The post is identified by its URL or code.

## Request

Exactly one of `postUrl` or `postCode` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.threads.post({ postCode: "DeKza99kXKb" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.threads.post(post_code="DeKza99kXKb")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/threads/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postCode":"DeKza99kXKb"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy threads post --postCode DeKza99kXKb
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post, and `results` lists a page of its replies.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "4002237372481761947",
    "postCode": "DeKza99kXKb",
    "postUrl": "https://www.threads.com/@nasa/post/DeKza99kXKb",
    "text": "Incoming: a new image from the cosmos! 🌌NASA's James Webb Space Telescope captured a stellar nursery about 3,300…",
    "publishedAt": "2026-10-06T21:58:15.000Z",
    "likes": 5303,
    "replies": 111,
    "reposts": 454,
    "quotes": 64,
    "shares": 105,
    "imageUrls": ["https://scontent-den2-1.cdninstagram.com/v/t51.82787-15/838249033_18122722672960389_7753548529811430766_n.jpg?stp=dst-j…"],
    "imageDescription": "A young star cluster filled with many stars that display Webb’s unique eight-pronged diffraction pattern. At its…",
    "isPinned": false,
    "authorId": "28829152388",
    "authorUsername": "nasa",
    "authorUrl": "https://www.threads.com/@nasa",
    "authorAvatarUrl": "https://scontent-den2-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?_nc_cat=1&…",
    "authorIsVerified": true,
    "results": [
      {
        "postId": "4002237419869004072",
        "postCode": "DeKzbqGEWEo",
        "postUrl": "https://www.threads.com/@nasa/post/DeKzbqGEWEo",
        "publishedAt": "2026-10-06T21:58:21.000Z",
        "likes": 926,
        "replies": 6,
        "reposts": 24,
        "quotes": 2,
        "shares": 4,
        "linkUrl": "https://science.nasa.gov/missions/webb/nasas-webb-captures-commotion-from-nebulas-stellar-jets/",
        "linkTitle": "NASA's Webb Captures Commotion From Nebula’s Stellar Jets - NASA Science",
        "isPinned": false,
        "authorId": "28829152388",
        "authorUsername": "nasa",
        "authorUrl": "https://www.threads.com/@nasa",
        "authorAvatarUrl": "https://scontent-den2-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?_nc_cat=1&…",
        "authorIsVerified": true
      }
    ],
    "cursor": "rRfO6VJseyJ0IjoiZG93bndhcmRfb3RoZXJfcmVwbGllcyIsInRzIjoxNzkxNjI5MzYyODg0LCJleCI6WzE3OTk0NjY4NDIzODQzMDU4LDE4MDk1NTAwNDE…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> results holds the author's own follow-up posts first, then pinned replies, then the top 5 replies; send cursor for 10 more a page. replies is Threads' own count of direct replies, and paging can return a few fewer. For the replies to a reply, call [Threads threads Post](/api-reference/endpoint/threads-post) with that reply's postCode.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Threads threads Profile](/api-reference/endpoint/threads-profile): Accepts `userUrl`. Scrape a Threads profile.
* [Threads threads Profile Posts](/api-reference/endpoint/threads-profile-posts): Accepts `userUrl`. Scrape a Threads profile's posts.


# Threads threads Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/threads-profile

api-reference/openapi.json POST /v1/threads/profile
Scrape a Threads profile. Call the Threads threads Profile API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Threads profile. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.threads.profile({ username: "nasa" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.threads.profile(username="nasa")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/threads/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"nasa"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy threads profile --username nasa
```

## Response

If successful, the response body contains the standard envelope. `data` contains the profile's bio, followers and post count.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "28829152388",
    "username": "nasa",
    "userUrl": "https://www.threads.com/@nasa",
    "name": "NASA",
    "bio": "Making the seemingly impossible, possible. ✨",
    "isVerified": true,
    "isPrivate": false,
    "followers": 12764861,
    "threads": 144,
    "avatarUrl": "https://scontent-lax3-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?stp=dst-jp…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

> [!NOTE]
>
> followers is exact. threads is the count Threads shows, which it rounds above 1,000 (1.6K comes back as 1600).

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Threads threads Profile Posts](/api-reference/endpoint/threads-profile-posts): Accepts `userUrl`. Scrape a Threads profile's posts.


# Threads threads Profile Posts API
Source: https://docs.stophy.dev/api-reference/endpoint/threads-profile-posts

api-reference/openapi.json POST /v1/threads/profile/posts
Scrape a Threads profile's posts. Call the Threads threads Profile Posts API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Threads profile's posts. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.threads.profile.posts({ username: "nasa" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.threads.profile.posts(username="nasa")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/threads/profile/posts \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"nasa"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy threads profile posts --username nasa
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the profile's posts, each with its text, likes, replies and reposts.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "postId": "4004368993196788713",
        "postCode": "DeSYGIdFUvp",
        "postUrl": "https://www.threads.com/@nasa/post/DeSYGIdFUvp",
        "text": "POV: returning to Earth after spending 237 days living and working in orbit!\n\nNASA’s SpaceX Crew-12 mission safely…",
        "publishedAt": "2026-10-09T20:33:24.000Z",
        "likes": 1457,
        "replies": 21,
        "reposts": 41,
        "quotes": 5,
        "shares": 6,
        "imageUrls": ["https://scontent-lax3-1.cdninstagram.com/v/t51.82787-15/841099539_18123179392960389_3856734489581201321_n.jpg?stp=dst-j…", "https://scontent-lax3-1.cdninstagram.com/v/t51.82787-15/843405192_18123179407960389_7805713510308495406_n.jpg?stp=dst-j…"],
        "imageDescription": "The SpaceX Crew Dragon Freedom spacecraft is seen as it lands with NASA astronauts Jessica Meir, Jack Hathaway, ESA…",
        "isPinned": false,
        "authorId": "28829152388",
        "authorUsername": "nasa",
        "authorUrl": "https://www.threads.com/@nasa",
        "authorAvatarUrl": "https://scontent-lax3-1.cdninstagram.com/v/t51.82787-19/669747085_18089786557960389_922072622069351626_n.jpg?_nc_cat=1&…",
        "authorIsVerified": true
      }
    ],
    "cursor": "4myK9q6Q28829152388.1789935532.AQHTVhSEAsWkwNNv7q4pneTptsGDK39WU0vTSJR5Rm35LpYGhMwGn2I047a_vWyeM0rkDR3os847KqQCxqZijqxQ…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Newest first, with a pinned post on top of the first page. Replies to a post are on [Threads threads Post](/api-reference/endpoint/threads-post).

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [Threads threads Profile](/api-reference/endpoint/threads-profile): Accepts `userUrl`. Scrape a Threads profile.
* [Threads threads Post](/api-reference/endpoint/threads-post): Accepts `postUrl`. Scrape a Threads post and its replies.


# TikTok tikTok Ad API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-ads-ad

api-reference/openapi.json POST /v1/tiktok/ads/ad
Scrape a TikTok ad's details. Call the TikTok tikTok Ad API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a TikTok ad's details. The ad is identified by its URL or ID.

## Request

Exactly one of `adUrl` or `adId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.ads.ad({ adId: "1874222777792674" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.ads.ad(ad_id="1874222777792674")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/ads/ad \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"adId":"1874222777792674"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok ads ad --adId 1874222777792674
```

## Response

If successful, the response body contains the standard envelope. `data` contains the ad's advertiser, dates, reach and the countries it ran in.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "adId": "1871322782235922",
    "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1871322782235922",
    "advertiserName": "adidas AG",
    "headline": "adidas Hyperboost Euphoria",
    "firstShownAt": "2026-07-30T00:00:00.000Z",
    "lastShownAt": "2026-07-30T00:00:00.000Z",
    "reachMin": 0,
    "reachMax": 1000,
    "videoUrl": "https://library.tiktok.com/api/v1/cdn/1791233253/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS9mMWE4ZmZhNTczZjRjZmEwNDk0ZTk4…",
    "thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ocWADVmTAmAiP6zVOz19NgNcBaIZEwYAlBniU~tplv-tiktokx-origin…",
    "imageUrls": ["https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ocWADVmTAmAiP6zVOz19NgNcBaIZEwYAlBniU~tplv-tiktokx-origin…"],
    "advertiserId": "6885261436319171329",
    "advertiserCountry": "United Kingdom",
    "paidBy": "PHD INTERNATIONAL LIMITED",
    "linkUrl": "https://ad.doubleclick.net/ddm/clk/645481797;451468138;a?utm_source=tiktok&utm_medium=paid",
    "ctaText": "Learn more",
    "objective": "Video views",
    "category": "Apparel & Accessories",
    "audienceSizeMin": 2500000,
    "audienceSizeMax": 3000000,
    "impressionsMin": 0,
    "impressionsMax": 1000,
    "countries": ["DE"],
    "interests": "Men's Shoes, Fitness Training Supplies, Exercise & Fitness, Coffee, Gaming Devices, Sports & Fitness, Health &…",
    "regions": [
      {
        "country": "DE",
        "impressionsMin": 0,
        "impressionsMax": 1000,
        "ages": ["18-24"],
        "genders": ["female", "male"]
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `firstShownAt` | string (ISO 8601) | The first day the ad was shown. |
| `lastShownAt` | string (ISO 8601) | The last day the ad was shown. |
| `reachMin` | integer | With `reachMax`, the range for the number of people the ad reached. |
| `impressionsMin` | integer | With `impressionsMax`, the range for the number of times the ad was shown. |
| `paidBy` | string | The entity that paid for the ad. |
| `countries` | string\[] | The countries in which the ad was shown. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [TikTok ads search](/api-reference/endpoint/tiktok-ads-search): Accepts the `advertiserName` as `advertiser`. Scrape ads from the TikTok ad library.


# TikTok tikTok Ads Search API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-ads-search

api-reference/openapi.json POST /v1/tiktok/ads/search
Scrape ads from the TikTok ad library. Call the TikTok tikTok Ads Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape ads from the TikTok ad library.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.ads.search({ query: "adidas" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.ads.search(query="adidas")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"adidas"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok ads search adidas
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the ads, each with its advertiser and how many people it reached.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "1871322782235922",
        "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1871322782235922",
        "advertiserName": "adidas AG",
        "headline": "adidas Hyperboost Euphoria",
        "firstShownAt": "2026-07-30T00:00:00.000Z",
        "lastShownAt": "2026-07-30T00:00:00.000Z",
        "reachMin": 0,
        "reachMax": 1000,
        "videoUrl": "https://library.tiktok.com/api/v1/cdn/1791233250/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS8yYjJmM2I1OTJlZDUzYWUyZTE5NDY1…",
        "thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ocWADVmTAmAiP6zVOz19NgNcBaIZEwYAlBniU~tplv-tiktokx-origin…",
        "imageUrls": ["https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ocWADVmTAmAiP6zVOz19NgNcBaIZEwYAlBniU~tplv-tiktokx-origin…"]
      }
    ],
    "total": 5000,
    "cursor": "eyJsYXN0X3NvcnQiOlsyNy40MjgyOTcsMTc4MzgxNDQwMDAwMF0sIm5leHRfY3Vyc29yIjoxMn0="
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `total` | integer | The number of ads match. Null when TikTok caps the count at 5000 for a large search. |
| `firstShownAt` | string (ISO 8601) | The first day the ad was shown. |
| `lastShownAt` | string (ISO 8601) | The last day the ad was shown. |
| `reachMin` | integer | With `reachMax`, the range for the number of people the ad reached. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | A keyword to find in ads. Send this or advertiser, not both. |
| `advertiser` | string | Restricts results to ads from this advertiser name. |
| `country` | string | Two-letter code of a European country, such as `de`. TikTok shows ads for these countries only. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok ad details](/api-reference/endpoint/tiktok-ads-ad): Accepts `adUrl`. Scrape a TikTok ad's details.


# TikTok tikTok Comments API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-comments

api-reference/openapi.json POST /v1/tiktok/comments
Scrape the comments of a TikTok video. Call the TikTok tikTok Comments API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape the comments of a TikTok video. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.comments({ videoId: "7652012587009215774" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.comments(video_id="7652012587009215774")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/comments \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoId":"7652012587009215774"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok comments --videoId 7652012587009215774
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the comments, or the replies when `comment` is set.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "commentId": "7652752342874718983",
        "text": "the cameraman",
        "authorId": "7642245892504519701",
        "authorUsername": "fatimaart65",
        "authorName": "FatimaArtist 🎨",
        "authorUrl": "https://www.tiktok.com/@fatimaart65",
        "authorAvatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/b3dcfceeddca1dc92f9dfc8ed794539c~tplv-tiktokx-cropcenter:10…",
        "likes": 4560,
        "replies": 19,
        "publishedAt": "2026-06-18T15:07:46.000Z"
      }
    ],
    "cursor": "20"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Replies are best effort: TikTok sometimes shows only some of a comment's replies, so a list can come back shorter than the comment's replies count.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `comment` | string | A comment id from an earlier response. Returns that comment's replies. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts the same `videoId`. Scrape a TikTok video.
* [TikTok tikTok Profile](/api-reference/endpoint/tiktok-profile): Accepts `userUrl`. Scrape a TikTok profile and its videos.


# TikTok tikTok Hashtag API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-hashtag

api-reference/openapi.json POST /v1/tiktok/hashtag
Scrape TikTok videos for a hashtag. Call the TikTok tikTok Hashtag API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape TikTok videos for a hashtag.

## Request

`hashtag` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.hashtag({ hashtag: "booktok" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.hashtag(hashtag="booktok")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/hashtag \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hashtag":"booktok"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok hashtag booktok
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of videos for the hashtag.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "videoId": "7223827494913215786",
        "videoUrl": "https://www.tiktok.com/@jenna_bushhager/video/7223827494913215786",
        "type": "video",
        "text": "#WorldBookDay is 4/23, and I've joined the #BookTok community to share our favorite books with you all! Duet to share…",
        "hashtags": ["worldbookday", "booktok"],
        "publishedAt": "2023-04-19T18:20:30.000Z",
        "durationSeconds": 82,
        "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ce0ee016ff8a483e8271ed4b4faebb3a~tplv-tiktokx-origin.ima…",
        "views": 39100,
        "likes": 997,
        "comments": 32,
        "shares": 36,
        "saves": 134,
        "authorId": "6915876645917082629",
        "authorUsername": "jenna_bushhager",
        "authorName": "Jenna Bush Hager",
        "authorUrl": "https://www.tiktok.com/@jenna_bushhager",
        "authorAvatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0707efff51851e19e5e88f36bd87a298~tplv-tiktokx-cropcen…",
        "authorIsVerified": true,
        "audioId": "7223827501163006766",
        "audioTitle": "original sound",
        "audioArtist": "Jenna Bush Hager",
        "audioIsOriginal": true,
        "isAd": false,
        "isAiGenerated": true
      }
    ],
    "cursor": "53"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video` or `photo`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `durationSeconds` | number | The duration, in seconds. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts `videoUrl`. Scrape a TikTok video.
* [TikTok tikTok Sound](/api-reference/endpoint/tiktok-sound): Accepts `audioId`. Scrape a TikTok sound and its videos.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.
* [TikTok tikTok Transcript](/api-reference/endpoint/tiktok-transcript): Accepts `videoUrl`. Scrape a TikTok video's transcript.


# TikTok tikTok Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-profile

api-reference/openapi.json POST /v1/tiktok/profile
Scrape a TikTok profile and its videos. Call the TikTok tikTok Profile API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a TikTok profile and its videos. The user is identified by its URL or username.

## Request

Exactly one of `userUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.profile({ username: "khaby.lame" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.profile(username="khaby.lame")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"khaby.lame"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok profile --username khaby.lame
```

## Response

If successful, the response body contains the standard envelope. `data` contains the profile's bio and stats, and `results` lists a page of its videos.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "127905465618821121",
    "username": "khaby.lame",
    "userUrl": "https://www.tiktok.com/@khaby.lame",
    "name": "Khabane lame",
    "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎",
    "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…",
    "isVerified": true,
    "isPrivate": false,
    "isOrganization": false,
    "language": "en",
    "createdAt": "2016-08-10T22:02:34.000Z",
    "followers": 162986955,
    "following": 81,
    "likes": 2685369103,
    "videos": 1357,
    "results": [
      {
        "videoId": "7691740195418377502",
        "videoUrl": "https://www.tiktok.com/@khaby.lame/video/7691740195418377502",
        "type": "video",
        "text": "Just give me 5 more minutes 😭#learnfromkhaby #comedy ",
        "hashtags": ["learnfromkhaby", "comedy"],
        "publishedAt": "2026-10-01T16:40:54.000Z",
        "durationSeconds": 34,
        "thumbnailUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0jRDQRMAbfFAlZX8eqGQcARBqerRfAHR7gVSU~tplv-tiktokx-ori…",
        "views": 3100000,
        "likes": 323800,
        "comments": 5782,
        "shares": 21200,
        "saves": 14931,
        "authorId": "127905465618821121",
        "authorUsername": "khaby.lame",
        "authorName": "Khabane lame",
        "authorUrl": "https://www.tiktok.com/@khaby.lame",
        "authorAvatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…",
        "authorIsVerified": true,
        "audioId": "7691740326570019615",
        "audioTitle": "original sound",
        "audioArtist": "Khabane lame",
        "audioIsOriginal": true,
        "isAd": false,
        "isAiGenerated": true
      }
    ],
    "cursor": "1780067181164"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video` or `photo`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `durationSeconds` | number | The duration, in seconds. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |
| `videos` | integer | The number of videos. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts `videoUrl`. Scrape a TikTok video.
* [TikTok tikTok Sound](/api-reference/endpoint/tiktok-sound): Accepts `audioId`. Scrape a TikTok sound and its videos.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.
* [TikTok tikTok Transcript](/api-reference/endpoint/tiktok-transcript): Accepts `videoUrl`. Scrape a TikTok video's transcript.


# TikTok tikTok Search API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-search

api-reference/openapi.json POST /v1/tiktok/search
Scrape TikTok search results. Call the TikTok tikTok Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape TikTok search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.search({ query: "street food" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.search(query="street food")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"street food"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok search "street food"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains videos or users, depending on `type`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "videoId": "7644673074440178966",
        "videoUrl": "https://www.tiktok.com/@streetbiteloop/video/7644673074440178966",
        "type": "video",
        "text": "🌭 Russian-Style Street Hot Dogs Done Right! Loaded Sausages with Ultimate Street Food Vibes 🔥 #HotDog #StreetFood…",
        "publishedAt": "2026-05-28T00:00:00.000Z",
        "durationSeconds": 46,
        "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-no1a-p-0037-no/o0khF1GVTEbtCVPFEq1gpWDfFRfAACZAAIuXAI~tplv-tiktokx-origin.…",
        "views": 25500,
        "likes": 463,
        "comments": 5,
        "shares": 20,
        "saves": 48,
        "authorId": "7643112992573244438",
        "authorUsername": "streetbiteloop",
        "authorName": "Street Bite Loop",
        "authorUrl": "https://www.tiktok.com/@streetbiteloop",
        "authorAvatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8700cf00c8ce94e865b684ac9426ba1c~tplv-tiktokx-cropcenter:7…",
        "authorIsVerified": false,
        "audioId": "7310524134701090818",
        "audioTitle": "Winter in Russia",
        "audioArtist": "Ma1nyyx",
        "audioIsOriginal": false,
        "isAd": false,
        "isAiGenerated": false
      }
    ],
    "cursor": "12:20261005204718B58D77DDAC1301FF9BD8"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video` or `photo`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `durationSeconds` | number | The duration, in seconds. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | Videos or users. Acceptable values are `videos` and `users`. If unset, defaults to `videos`. |
| `sort` | string | Specifies the order of videos. Leave it out for relevance. Acceptable values are `relevance`, `mostLiked` and `datePosted`. |
| `datePosted` | string | Restricts results to videos from this period. Leave it out for all time. Acceptable values are `past24Hours`, `thisWeek`, `thisMonth`, `last3Months` and `last6Months`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok tikTok Profile](/api-reference/endpoint/tiktok-profile): Accepts `userUrl`. Scrape a TikTok profile and its videos.
* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts `videoUrl`. Scrape a TikTok video.
* [TikTok tikTok Sound](/api-reference/endpoint/tiktok-sound): Accepts `audioId`. Scrape a TikTok sound and its videos.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.


# TikTok Shop tikTok Shop Product API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-shop-product

api-reference/openapi.json POST /v1/tiktok/shop/product
Scrape a TikTok Shop product page. Call the TikTok Shop tikTok Shop Product API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a TikTok Shop product page. The product is identified by its URL or ID.

## Request

Exactly one of `productUrl` or `productId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.shop.product({ productUrl: "https://shop.tiktok.com/us/pdp/p/1729592969712207012" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.shop.product(product_url="https://shop.tiktok.com/us/pdp/p/1729592969712207012")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/shop/product \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://shop.tiktok.com/us/pdp/p/1729592969712207012"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok shop product --productUrl https://shop.tiktok.com/us/pdp/p/1729592969712207012
```

## Response

If successful, the response body contains the standard envelope. `data` contains the product's price, stock, seller and images.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "productId": "1732195217319498354",
    "title": "GummyGlow Brand New Upgrade Fruity Wax Gummies, 12oz Party-Ready Pack - 5 Sour Flavors, Crunchy ASMR Sweet Snacks,…",
    "productUrl": "https://shop.tiktok.com/us/pdp/p/1732195217319498354",
    "price": 19.47,
    "originalPrice": 24.98,
    "currency": "USD",
    "sold": 28642,
    "rating": 4,
    "reviews": 2956,
    "stock": 3226,
    "shopId": "7496048947258165874",
    "shopName": "Gummy Glow",
    "shopUrl": "https://shop.tiktok.com/us/store/gummy-glow/7496048947258165874",
    "shopRating": 3.9,
    "shopProducts": 19,
    "shopFollowers": 9393,
    "imageUrls": ["https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/f70c619f11344b7f9b43c50925bc731e~tplv-fhlh96ny…"]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `sold` | integer | The number of units sold. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [TikTok Shop tikTok Shop Products](/api-reference/endpoint/tiktok-shop-products): Accepts `shopUrl`. Scrape a TikTok Shop seller's products.
* [TikTok Shop tikTok Shop Reviews](/api-reference/endpoint/tiktok-shop-reviews): Accepts `productUrl`. Scrape a TikTok Shop product's reviews.


# TikTok Shop tikTok Shop Products API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-shop-products

api-reference/openapi.json POST /v1/tiktok/shop/products
Scrape a TikTok Shop seller's products. Call the TikTok Shop tikTok Shop Products API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a TikTok Shop seller's products. The shop is identified by its URL or ID.

## Request

Exactly one of `shopUrl` or `shopId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.shop.products({ shopUrl: "https://shop.tiktok.com/us/store/shop/7495291731420235534" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.shop.products(shop_url="https://shop.tiktok.com/us/store/shop/7495291731420235534")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/shop/products \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"shopUrl":"https://shop.tiktok.com/us/store/shop/7495291731420235534"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok shop products --shopUrl https://shop.tiktok.com/us/store/shop/7495291731420235534
```

## Response

If successful, the response body contains the standard envelope. `data` contains the shop's name, rating and sales, and `results` lists its products.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "shopId": "7496048947258165874",
    "shopName": "Gummy Glow",
    "rating": 3.9,
    "sold": 65117,
    "products": 19,
    "reviews": 7154,
    "followers": 9393,
    "shopUrl": "https://www.tiktok.com/shop/store/gummy-glow/7496048947258165874",
    "results": [
      {
        "productId": "1732195217319498354",
        "title": "GummyGlow Brand New Upgrade Fruity Wax Gummies, 12oz Party-Ready Pack - 5 Sour Flavors, Crunchy ASMR Sweet Snacks,…",
        "productUrl": "https://shop.tiktok.com/us/pdp/fruitywax-bear-candy-12oz-pack-5-flavors-retro-party-treats/1732195217319498354",
        "price": 19.47,
        "currency": "USD",
        "sold": 28642,
        "rating": 4,
        "reviews": 2956,
        "imageUrl": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/f70c619f11344b7f9b43c50925bc731e~tplv-fhlh96ny…",
        "shopId": "7496048947258165874",
        "shopName": "Gummy Glow"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `sold` | integer | The number of units sold. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok Shop tikTok Shop Product](/api-reference/endpoint/tiktok-shop-product): Accepts `productUrl`. Scrape a TikTok Shop product page.
* [TikTok Shop tikTok Shop Reviews](/api-reference/endpoint/tiktok-shop-reviews): Accepts `productUrl`. Scrape a TikTok Shop product's reviews.


# TikTok Shop tikTok Shop Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-shop-reviews

api-reference/openapi.json POST /v1/tiktok/shop/reviews
Scrape a TikTok Shop product's reviews. Call the TikTok Shop tikTok Shop Reviews API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a TikTok Shop product's reviews. The product is identified by its URL or ID.

## Request

Exactly one of `productUrl` or `productId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.shop.reviews({ productUrl: "https://shop.tiktok.com/us/pdp/p/1729592969712207012" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.shop.reviews(product_url="https://shop.tiktok.com/us/pdp/p/1729592969712207012")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/shop/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://shop.tiktok.com/us/pdp/p/1729592969712207012"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok shop reviews --productUrl https://shop.tiktok.com/us/pdp/p/1729592969712207012
```

## Response

If successful, the response body contains the standard envelope. `data` contains the product's rating, and `results` lists the first page of its reviews.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "rating": 4,
    "reviews": 2956,
    "results": [
      {
        "reviewId": "7689658813176153870",
        "rating": 1,
        "text": "It said it was supposed to be crunchy it was not crunchy and didn’t taste good",
        "authorName": "f**s",
        "isVerified": true,
        "publishedAt": "2026-09-26T02:04:41.569Z",
        "country": "US",
        "imageUrls": ["https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/ca205418263841dba0067240a5eea513~tplv-fhlh96ny…", "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/12ce5ce9ab5142a78b0a816658f3705c~tplv-fhlh96ny…"]
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [TikTok Shop tikTok Shop Product](/api-reference/endpoint/tiktok-shop-product): Accepts the same `productId`. Scrape a TikTok Shop product page.


# TikTok Shop tikTok Shop Search API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-shop-search

api-reference/openapi.json POST /v1/tiktok/shop/search
Scrape TikTok Shop search results. Call the TikTok Shop tikTok Shop Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape TikTok Shop search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.shop.search({ query: "gummies" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.shop.search(query="gummies")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/shop/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"gummies"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok shop search gummies
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the products, each with its price, units sold and shop.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "productId": "1732195217319498354",
        "title": "GummyGlow Brand New Upgrade Fruity Wax Gummies, 12oz Party-Ready Pack - 5 Sour Flavors, Crunchy ASMR Sweet Snacks,…",
        "productUrl": "https://shop.tiktok.com/us/pdp/fruitywax-bear-candy-12oz-pack-5-flavors-retro-party-treats/1732195217319498354",
        "price": 19.47,
        "currency": "USD",
        "sold": 28642,
        "rating": 4,
        "reviews": 2956,
        "imageUrl": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/f70c619f11344b7f9b43c50925bc731e~tplv-fhlh96ny…",
        "shopId": "7496048947258165874",
        "shopName": "Gummy Glow"
      }
    ],
    "cursor": "30::1732195217319498354,1729698659696480903,1729659431304270343,1732017016925885182,1732184216657432914,173206684122117…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |
| `sold` | integer | The number of units sold. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok Shop tikTok Shop Products](/api-reference/endpoint/tiktok-shop-products): Accepts `shopId`. Scrape a TikTok Shop seller's products.
* [TikTok Shop tikTok Shop Product](/api-reference/endpoint/tiktok-shop-product): Accepts `productUrl`. Scrape a TikTok Shop product page.
* [TikTok Shop tikTok Shop Reviews](/api-reference/endpoint/tiktok-shop-reviews): Accepts `productUrl`. Scrape a TikTok Shop product's reviews.


# TikTok tikTok Sound API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-sound

api-reference/openapi.json POST /v1/tiktok/sound
Scrape a TikTok sound and its videos. Call the TikTok tikTok Sound API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a TikTok sound and its videos.

## Request

`audioId` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.sound({ audioId: "7652012548169976607" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.sound(audio_id="7652012548169976607")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/sound \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"audioId":"7652012548169976607"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok sound 7652012548169976607
```

## Response

If successful, the response body contains the standard envelope. `data` contains the sound's details, and `results` lists a page of videos that use it.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "audioId": "7652012548169976607",
    "audioTitle": "original sound",
    "audioArtist": "Khabane lame",
    "audioIsOriginal": true,
    "videos": 415,
    "results": [
      {
        "videoId": "7652012587009215774",
        "videoUrl": "https://www.tiktok.com/@khaby.lame/video/7652012587009215774",
        "type": "video",
        "text": "Bro…. Where is the rest of my rice? 🍚🤨#learnfromkhaby #comedy ",
        "hashtags": ["learnfromkhaby", "comedy"],
        "publishedAt": "2026-06-16T15:17:17.000Z",
        "durationSeconds": 30,
        "thumbnailUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMCUBOFruAxeDj4qAILfYaqGVewvlQtIIIC0xI~tplv-tiktokx-ori…",
        "views": 77300000,
        "likes": 3500000,
        "comments": 53000,
        "shares": 305300,
        "saves": 154244,
        "authorId": "127905465618821121",
        "authorUsername": "khaby.lame",
        "authorName": "Khabane lame",
        "authorUrl": "https://www.tiktok.com/@khaby.lame",
        "authorAvatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…",
        "authorIsVerified": true,
        "audioId": "7652012548169976607",
        "audioTitle": "original sound",
        "audioArtist": "Khabane lame",
        "audioIsOriginal": true,
        "isAd": false,
        "isAiGenerated": true
      }
    ],
    "cursor": "30"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video` or `photo`. |
| `videos` | integer | The number of videos use the sound. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `durationSeconds` | number | The duration, in seconds. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts `videoUrl`. Scrape a TikTok video.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.
* [TikTok tikTok Transcript](/api-reference/endpoint/tiktok-transcript): Accepts `videoUrl`. Scrape a TikTok video's transcript.
* [TikTok tikTok Profile](/api-reference/endpoint/tiktok-profile): Accepts `userUrl`. Scrape a TikTok profile and its videos.


# TikTok tikTok Transcript API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-transcript

api-reference/openapi.json POST /v1/tiktok/transcript
Scrape a TikTok video's transcript. Call the TikTok tikTok Transcript API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape a TikTok video's transcript. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.transcript({ videoUrl: "https://www.tiktok.com/@khaby.lame/video/7137423965982592302" });
console.log(result.data.text);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.transcript(video_url="https://www.tiktok.com/@khaby.lame/video/7137423965982592302")
print(result["data"]["text"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/transcript \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoUrl":"https://www.tiktok.com/@khaby.lame/video/7137423965982592302"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok transcript --videoUrl https://www.tiktok.com/@khaby.lame/video/7137423965982592302
```

## Response

If successful, the response body contains the standard envelope. `data` contains what the video says as one block of `text`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "videoId": "7137423965982592302",
    "videoUrl": "https://www.tiktok.com/@charlidamelio/video/7137423965982592302",
    "language": "en",
    "isAutoGenerated": true,
    "durationSeconds": 11.12093696,
    "transcribedSeconds": 12,
    "text": "First time, first time, first time, look, you'll hear your eyes. What are you willing to do? All I tell you what…"
  },
  "creditsUsed": 4,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `text` | string | The whole transcript as one block. |
| `transcribedSeconds` | number | Seconds of audio that were transcribed when the video had no captions. The price depends on it. |
| `isAutoGenerated` | boolean | `true` if the captions were generated, not written by a person. |
| `durationSeconds` | number | The duration, in seconds. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Without an API key it reads captions only.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. |
| `includeTimestamps` | boolean | Return each line with its start and end time, in `segments`. If unset, defaults to `false`. |

> [!NOTE]
>
> Videos longer than 3 minutes are rejected with `invalidRequest`. Rejected requests are not billed.

## Billing

A successful request consumes 1 credit when the video has captions; otherwise 2 credits plus 1 credit for every 10 seconds of audio, up to 3 minutes, up to 20 credits. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [TikTok tikTok Video](/api-reference/endpoint/tiktok-video): Accepts `videoUrl`. Scrape a TikTok video.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.


# TikTok tikTok Video API
Source: https://docs.stophy.dev/api-reference/endpoint/tiktok-video

api-reference/openapi.json POST /v1/tiktok/video
Scrape a TikTok video. Call the TikTok tikTok Video API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a TikTok video. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.video({ videoId: "7652012587009215774" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.video(video_id="7652012587009215774")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/video \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoId":"7652012587009215774"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok video --videoId 7652012587009215774
```

## Response

If successful, the response body contains the standard envelope. `data` contains the video's caption, stats, author and music.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "videoId": "7652012587009215774",
    "videoUrl": "https://www.tiktok.com/@khaby.lame/video/7652012587009215774",
    "type": "video",
    "text": "Bro…. Where is the rest of my rice? 🍚🤨#learnfromkhaby #comedy ",
    "hashtags": ["learnfromkhaby"],
    "publishedAt": "2026-06-16T15:17:17.000Z",
    "durationSeconds": 30,
    "thumbnailUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMCUBOFruAxeDj4qAILfYaqGVewvlQtIIIC0xI~tplv-tiktokx-ori…",
    "views": 77300000,
    "likes": 3500000,
    "comments": 52800,
    "shares": 305300,
    "saves": 154244,
    "authorId": "127905465618821121",
    "authorUsername": "khaby.lame",
    "authorName": "Khabane lame",
    "authorUrl": "https://www.tiktok.com/@khaby.lame",
    "authorAvatarUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcen…",
    "authorIsVerified": true,
    "audioId": "7652012548169976607",
    "audioTitle": "original sound",
    "audioArtist": "Khabane lame",
    "audioIsOriginal": true,
    "country": "US",
    "isAd": false,
    "isAiGenerated": true
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The kind of item: `video` or `photo`. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `durationSeconds` | number | The duration, in seconds. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [TikTok tikTok Sound](/api-reference/endpoint/tiktok-sound): Accepts `audioId`. Scrape a TikTok sound and its videos.
* [TikTok tikTok Comments](/api-reference/endpoint/tiktok-comments): Accepts `videoUrl`. Scrape the comments of a TikTok video.
* [TikTok tikTok Transcript](/api-reference/endpoint/tiktok-transcript): Accepts `videoUrl`. Scrape a TikTok video's transcript.
* [TikTok tikTok Profile](/api-reference/endpoint/tiktok-profile): Accepts `userUrl`. Scrape a TikTok profile and its videos.


# Tripadvisor tripadvisor Place API
Source: https://docs.stophy.dev/api-reference/endpoint/tripadvisor-place

api-reference/openapi.json POST /v1/tripadvisor/place
Scrape a Tripadvisor place page. Call the Tripadvisor tripadvisor Place API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Tripadvisor place page. The place is identified by its URL or ID.

## Request

Exactly one of `placeUrl` or `placeId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tripadvisor.place({ placeUrl: "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tripadvisor.place(place_url="https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tripadvisor/place \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"placeUrl":"https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tripadvisor place --placeUrl https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html
```

## Response

If successful, the response body contains the standard envelope. `data` contains the place's rating, ranking, price range, address and contact details.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "placeId": "187591",
    "placeUrl": "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html",
    "name": "The Ritz London Hotel",
    "type": "accommodation",
    "subtypes": ["Hotel"],
    "rating": 4.7,
    "reviews": 5407,
    "rankingText": "#137 of 1,363 hotels in London",
    "rankingPosition": 137,
    "rankingOf": 1363,
    "rankingGeo": "London",
    "priceLevel": "$$$$",
    "priceRangeText": "$1,662 - $2,737",
    "hotelClass": 5,
    "description": "Opened in 1906 by hotelier César Ritz, The Ritz London is one of the world’s most iconic hotels, situated on…",
    "addressFull": "150 Piccadilly, London W1J 9BR England",
    "addressStreet": "150 Piccadilly",
    "addressCity": "London",
    "addressCountry": "United Kingdom",
    "addressPostalCode": "W1J 9BR",
    "latitude": 51.507088,
    "longitude": -0.141628,
    "phone": "+1 555 0100",
    "website": "https://www.theritzlondon.com/?scid=45f93f1b-bd77-45c9-8dab-83b6a417f6fe&y_source=1_NDIyOTQyMS03NjktbG9jYXRpb24ud2Vic2l…",
    "email": "name@example.com",
    "neighborhoods": ["St. James's"],
    "parents": [
      {
        "placeId": "186338",
        "name": "London"
      }
    ],
    "tags": ["Luxury"],
    "imageUrl": "https://media-cdn.tripadvisor.com/media/photo-o/0c/1e/94/94/hallways--v13146843.jpg",
    "timezone": "Europe/London",
    "isClosed": false
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Tripadvisor tripadvisor Reviews](/api-reference/endpoint/tripadvisor-reviews): Accepts `placeUrl`. Scrape a Tripadvisor place's reviews.


# Tripadvisor tripadvisor Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/tripadvisor-reviews

api-reference/openapi.json POST /v1/tripadvisor/reviews
Scrape a Tripadvisor place's reviews. Call the Tripadvisor tripadvisor Reviews API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a Tripadvisor place's reviews. The place is identified by its URL or ID.

## Request

Exactly one of `placeUrl` or `placeId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tripadvisor.reviews({ placeUrl: "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tripadvisor.reviews(place_url="https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tripadvisor/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"placeUrl":"https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tripadvisor reviews --placeUrl https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London.html
```

## Response

If successful, the response body contains the standard envelope. `data` contains the place, and `results` lists a page of its reviews.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "placeId": "187591",
    "placeName": "The Ritz London Hotel",
    "placeType": "accommodation",
    "placeUrl": "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html",
    "total": 2099,
    "results": [
      {
        "reviewId": "1062698613",
        "reviewUrl": "https://www.tripadvisor.com/ShowUserReviews-g186338-d187591-r1062698613-The_Ritz_London_Hotel-London_England.html",
        "rating": 5,
        "title": "Luxury At It's Finest",
        "text": "The Ritz is luxury at its finest, blending the highest level of professional service with a sense of comfort and…",
        "language": "en",
        "createdDate": "2026-06-02",
        "stayMonth": "2026-05",
        "tripType": "couples",
        "helpful": 0,
        "subRatings": [
          {
            "name": "Value",
            "rating": 5
          }
        ],
        "authorName": "Michael M",
        "authorUsername": "Michael_MandM",
        "authorUrl": "https://www.tripadvisor.com/Profile/Michael_MandM",
        "authorAddress": "Penrith, Australia",
        "authorContributions": 777,
        "ownerReplyText": "Dear Michael M,\n\nWe are delighted to read that you enjoyed your stay with us. We hope to welcome you back to The Ritz…",
        "ownerReplyDate": "2026-06-05",
        "ownerReplyAuthor": "General Manager"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `language` | string | The language of the reviews, or `all`. If unset, defaults to `en`. |
| `ratings` | integer\[] | Restricts results to reviews with these star ratings, from 1 to 5. Accepts up to 5 values. |
| `travelerTypes` | string\[] | Restricts results to reviews from these travelers. Acceptable values are `families`, `couples`, `solo`, `business` and `friends`. Accepts up to 5 values. |
| `months` | string\[] | Restricts results to reviews written in these months of the year. Acceptable values are `marMay`, `junAug`, `sepNov` and `decFeb`. Accepts up to 4 values. |
| `sort` | string | `mostRecent` puts the newest first. `detailed` orders by recency and by how much a review says. Acceptable values are `mostRecent` and `detailed`. If unset, defaults to `mostRecent`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 500. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 500.

## Related methods

* [Tripadvisor tripadvisor Place](/api-reference/endpoint/tripadvisor-place): Accepts `placeUrl`. Scrape a Tripadvisor place page.


# Tripadvisor tripadvisor Search API
Source: https://docs.stophy.dev/api-reference/endpoint/tripadvisor-search

api-reference/openapi.json POST /v1/tripadvisor/search
Scrape Tripadvisor search results. Call the Tripadvisor tripadvisor Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Tripadvisor search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tripadvisor.search({ query: "Ritz London", type: "hotels" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tripadvisor.search(query="Ritz London", type="hotels")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tripadvisor/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"Ritz London","type":"hotels"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tripadvisor search "Ritz London" --type hotels
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the places, each with its type, address and link.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "placeId": "187591",
        "placeUrl": "https://www.tripadvisor.com/Hotel_Review-g186338-d187591-Reviews-The_Ritz_London_Hotel-London_England.html",
        "name": "The Ritz London Hotel",
        "type": "accommodation",
        "address": "150 Piccadilly",
        "parent": "London, England",
        "latitude": 51.507088,
        "longitude": -0.141628,
        "imageUrl": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/33/be/ef/d4/the-ritz-london-entrance.jpg?w=1200&h=900&s=1"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | The kind of place. |
| `placeUrl` | string (URL) | A token. Pass it as `placeUrl` to retrieve the place's details or reviews. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | The kind of place. Acceptable values are `all`, `hotels`, `restaurants`, `attractions` and `geos`. If unset, defaults to `all`. |
| `location` | string | Narrow the search to this place. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Tripadvisor tripadvisor Place](/api-reference/endpoint/tripadvisor-place): Accepts `placeUrl`. Scrape a Tripadvisor place page.
* [Tripadvisor tripadvisor Reviews](/api-reference/endpoint/tripadvisor-reviews): Accepts `placeUrl`. Scrape a Tripadvisor place's reviews.


# Trustpilot trustpilot Company API
Source: https://docs.stophy.dev/api-reference/endpoint/trustpilot-company

api-reference/openapi.json POST /v1/trustpilot/company
Scrape a Trustpilot company page. Call the Trustpilot trustpilot Company API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Trustpilot company page. The company or companyDomain is identified by its URL or companyDomain.

## Request

Exactly one of `companyUrl` or `companyDomain` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.trustpilot.company({ companyDomain: "stripe.com" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.trustpilot.company(company_domain="stripe.com")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/trustpilot/company \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyDomain":"stripe.com"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy trustpilot company --companyDomain stripe.com
```

## Response

If successful, the response body contains the standard envelope. `data` contains the company's TrustScore, stars, review count and the number of reviews at each star rating.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyId": "50489e6800006400051ae0d6",
    "companyDomain": "stripe.com",
    "companyUrl": "https://www.trustpilot.com/review/stripe.com",
    "name": "Stripe",
    "website": "https://stripe.com",
    "description": "Millions of businesses of all sizes—from startups to large enterprises—use Stripe’s software and APIs to accept…",
    "trustScore": 1.6,
    "stars": 1.5,
    "reviews": 17537,
    "ratingsOne": 9109,
    "ratingsTwo": 512,
    "ratingsThree": 469,
    "ratingsFour": 725,
    "ratingsFive": 6722,
    "categories": ["Payment Service"],
    "isClaimed": true,
    "isClosed": false,
    "email": "https://support.stripe.com/contact",
    "addressStreet": "510 Townsend Street",
    "addressCity": "San Francisco",
    "addressPostalCode": "94103",
    "addressCountry": "United States",
    "negativeReviewsRepliedPercent": 100,
    "averageDaysToReply": 1.91
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Trustpilot trustpilot Company Reviews](/api-reference/endpoint/trustpilot-company-reviews): Accepts `companyUrl`. Scrape a Trustpilot company's reviews.


# Trustpilot trustpilot Company Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/trustpilot-company-reviews

api-reference/openapi.json POST /v1/trustpilot/company/reviews
Scrape a Trustpilot company's reviews. Call the Trustpilot trustpilot Company Reviews API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a Trustpilot company's reviews. The company or companyDomain is identified by its URL or companyDomain.

## Request

Exactly one of `companyUrl` or `companyDomain` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.trustpilot.company.reviews({ companyDomain: "stripe.com", ratings: [1], language: "en" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.trustpilot.company.reviews(company_domain="stripe.com", ratings=[1], language="en")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/trustpilot/company/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"companyDomain":"stripe.com","ratings":[1],"language":"en"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy trustpilot company reviews --companyDomain stripe.com --ratings 1 --language en
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains a page of the company's reviews, each with its rating, title, text and date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "companyDomain": "stripe.com",
    "companyName": "Stripe",
    "total": 7019,
    "results": [
      {
        "reviewId": "6ac9d8b3d55b885799b7fd12",
        "reviewUrl": "https://www.trustpilot.com/reviews/6ac9d8b3d55b885799b7fd12",
        "rating": 1,
        "title": "Worst service ever",
        "text": "Worst service ever! There automated system just suspended my account in two days of creation. No support nothing. I…",
        "language": "en",
        "publishedAt": "2026-10-10T08:18:30.000Z",
        "experiencedDate": "2026-10-10",
        "isVerified": false,
        "authorName": "Sarmad Bashir",
        "authorCountry": "PK"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `rating` | integer | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `ratings` | integer\[] | Restricts results to reviews with these star ratings, 1 to 5. Empty means every rating. Accepts up to 5 values. |
| `language` | string | Restricts results to reviews in this language, as a two-letter code such as `en`. Defaults to `all`. If unset, defaults to `all`. |
| `datePublished` | string | Restricts results to reviews published in the last 30 days, 3, 6 or 12 months. Acceptable values are `last30Days`, `last3Months`, `last6Months` and `last12Months`. |
| `verifiedOnly` | boolean | Restricts results to reviews Trustpilot marks as verified. If unset, defaults to `false`. |
| `search` | string | Restricts results to reviews that mention this word or phrase. |
| `page` | integer | Page number, starting at 1. Trustpilot shows 10 pages of 20 reviews without an account; narrow with ratings, language, `datePublished` or search to reach older reviews. Must be between 1 and 10. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 10.


# Trustpilot trustpilot Search API
Source: https://docs.stophy.dev/api-reference/endpoint/trustpilot-search

api-reference/openapi.json POST /v1/trustpilot/search
Scrape Trustpilot search results. Call the Trustpilot trustpilot Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Trustpilot search results.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.trustpilot.search({ query: "stripe" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.trustpilot.search(query="stripe")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/trustpilot/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"stripe"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy trustpilot search stripe
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the companies, each with its TrustScore, stars, review count and categories.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "total": 212,
    "results": [
      {
        "companyId": "50489e6800006400051ae0d6",
        "companyDomain": "stripe.com",
        "companyUrl": "https://www.trustpilot.com/review/stripe.com",
        "name": "Stripe",
        "website": "https://stripe.com",
        "trustScore": 1.6,
        "stars": 1.5,
        "reviews": 17537,
        "categories": ["Payment Service"],
        "addressStreet": "510 Townsend Street",
        "addressCity": "San Francisco",
        "addressPostalCode": "94103",
        "addressCountry": "United States"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

> [!NOTE]
>
> A domain as the query returns that one company; with a domain, [Trustpilot trustpilot Company](/api-reference/endpoint/trustpilot-company) is the direct way in.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number, starting at 1. Trustpilot shows 10 pages of 10 companies without an account, so one search reaches at most 100 companies even when total is larger. Make the query more specific to reach the rest. Must be between 1 and 10. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 10.

## Related methods

* [Trustpilot trustpilot Company](/api-reference/endpoint/trustpilot-company): Accepts `companyUrl`. Scrape a Trustpilot company page.
* [Trustpilot trustpilot Company Reviews](/api-reference/endpoint/trustpilot-company-reviews): Accepts `companyUrl`. Scrape a Trustpilot company's reviews.


# Upwork upwork Job API
Source: https://docs.stophy.dev/api-reference/endpoint/upwork-job

api-reference/openapi.json POST /v1/upwork/job
Scrape an Upwork job page. Call the Upwork upwork Job API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an Upwork job page. The job is identified by its URL or ID.

## Request

Exactly one of `jobUrl` or `jobId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.upwork.job({ jobUrl: "https://www.upwork.com/jobs/~021234567890123456789" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.upwork.job(job_url="https://www.upwork.com/jobs/~021234567890123456789")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/upwork/job \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobUrl":"https://www.upwork.com/jobs/~021234567890123456789"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy upwork job --jobUrl "https://www.upwork.com/jobs/~021234567890123456789"
```

## Response

If successful, the response body contains the standard envelope. `data` contains the job's description, budget and skills, and what the job page shows about the client.

The following example is illustrative.

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "~021234567890123456789",
    "jobUrl": "https://www.upwork.com/jobs/~021234567890123456789",
    "title": "React developer for a dashboard",
    "description": "We need a React developer to build a reporting dashboard.",
    "skills": ["React", "TypeScript"],
    "type": "hourly",
    "experienceLevel": "intermediate",
    "workload": "partTime",
    "duration": "oneToThreeMonths",
    "hourlyRateMin": 30,
    "hourlyRateMax": 60,
    "publishedAt": "2026-10-05T09:30:00.000Z",
    "applicants": 12,
    "hired": 0,
    "interviewing": 2,
    "invitesSent": 3,
    "positions": 1,
    "clientCountry": "United States",
    "clientTotalSpent": 18000,
    "clientHires": 24,
    "clientReviews": 18,
    "clientRating": 4.9
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | Indicates whether the job pays by the hour (`hourly`) or a fixed price (`fixed`). |
| `workload` | string | Upwork's hours needed. Empty when the job does not say, including fixed-price jobs and clients who are not sure. |
| `duration` | string | Upwork's project length. `underOneMonth` is under one month, `oneToThreeMonths` is one to three months, `threeToSixMonths` is three to six months, and `overSixMonths` is longer. |
| `clientTotalSpent` | number | The amount the client has spent in all. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Upwork upwork Search](/api-reference/endpoint/upwork-search): Accepts the job's `title` as `query`. Scrape Upwork job search results.


# Upwork upwork Search API
Source: https://docs.stophy.dev/api-reference/endpoint/upwork-search

api-reference/openapi.json POST /v1/upwork/search
Scrape Upwork job search results. Call the Upwork upwork Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Upwork job search results.

## Request

This method has no required parameters.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.upwork.search({ query: "react developer" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.upwork.search(query="react developer")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/upwork/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"react developer"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy upwork search "react developer"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the jobs, each with its budget or hourly rate, skills and posting date.

The following example is illustrative.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "jobId": "~021234567890123456789",
        "jobUrl": "https://www.upwork.com/jobs/~021234567890123456789",
        "title": "React developer for a dashboard",
        "description": "We need a React developer to build a reporting dashboard.",
        "skills": ["React", "TypeScript"],
        "type": "hourly",
        "experienceLevel": "intermediate",
        "workload": "partTime",
        "duration": "oneToThreeMonths",
        "hourlyRateMin": 30,
        "hourlyRateMax": 60,
        "publishedAt": "2026-10-05T09:30:00.000Z"
      }
    ],
    "total": 1250,
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `type` | string | Indicates whether the job pays by the hour (`hourly`) or a fixed price (`fixed`). |
| `workload` | string | Upwork's hours needed. Empty when the job does not say, including fixed-price jobs and clients who are not sure. |
| `duration` | string | Upwork's project length. `underOneMonth` is under one month, `oneToThreeMonths` is one to three months, `threeToSixMonths` is three to six months, and `overSixMonths` is longer. |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |

For every field, see the response schema on this page.

> [!NOTE]
>
> `workload`, `duration` and the hourly rate filters apply to hourly jobs only.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Words to search for. |
| `sort` | string | Specifies the order of the jobs. Acceptable values are `newest` and `relevance`. If unset, defaults to `newest`. |
| `jobType` | string | Hourly jobs or fixed-price jobs. Acceptable values are `hourly` and `fixed`. |
| `experienceLevel` | string | Restricts results to jobs that ask for this level. Acceptable values are `entry`, `intermediate` and `expert`. |
| `workload` | string | Hours needed: full time, part time or as needed. Only hourly jobs say this, so the search stays hourly. Acceptable values are `fullTime`, `partTime` and `asNeeded`. |
| `duration` | string | Project length: under one month, one to three months, three to six months or over six months. Only hourly jobs say this, so the search stays hourly. Acceptable values are `underOneMonth`, `oneToThreeMonths`, `threeToSixMonths` and `overSixMonths`. |
| `minHourlyRate` | integer | The minimum hourly rate in USD. A job matches when its posted range overlaps this minimum, so 25 to 50 matches a minimum of 50. The search stays hourly. Must be between 1 and 999. |
| `maxHourlyRate` | integer | The maximum hourly rate in USD. Requires `minHourlyRate`. The job's posted range overlaps both, and the search stays hourly. Must be between 1 and 999. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.

## Related methods

* [Upwork upwork Job](/api-reference/endpoint/upwork-job): Accepts `jobUrl`. Scrape an Upwork job page.


# Web web Batch API
Source: https://docs.stophy.dev/api-reference/endpoint/web-batch

api-reference/openapi.json POST /v1/web/batch
Scrape up to 100 pages in the background. Call the Web web Batch API and get JSON back in one request. From 0 credits per call. Failed calls cost nothing.

Scrape up to 100 pages in the background.

## Request

`urls` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.batch({ urls: ["https://bun.com/docs", "https://bun.com/blog"] });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.batch(urls=["https://bun.com/docs", "https://bun.com/blog"])
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/batch \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"urls":["https://bun.com/docs","https://bun.com/blog"]}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web batch --urls https://bun.com/docs,https://bun.com/blog
```

## Response

If successful, the response body contains the standard envelope. `data` contains the batch's id and status, to follow with `web.batch.status`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_BC0vf8IzmDUA4VeGy9M7tA",
    "status": "queued",
    "total": 2
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

> [!NOTE]
>
> It answers at once with an id; ask [Web web Batch Status](/api-reference/endpoint/web-batch-status) for the pages, or send webhook to be told as each one finishes.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `webhook` | string | A public address that gets a JSON POST when the job starts, for each finished page, and when the job ends. |
| `formats` | object\[] | What to return: markdown (clean page text), html (the cleaned page), `rawHtml` (the page as sent), links (every link on the page) and screenshot (a JPEG of the visible page, as base64). Send `{ "type": "screenshot", "fullPage": true }` for the whole page. A screenshot costs 3 credits, or 15 on the hardest pages to reach. A PDF comes back as markdown only. Accepts up to 5 values. |
| `onlyMainContent` | boolean | Keep only the page's main content, without menus, headers, footers and ads. If unset, defaults to `true`. |
| `includeTags` | string\[] | Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, `onlyMainContent` is not applied. Accepts up to 20 values. |
| `excludeTags` | string\[] | Remove the parts of the page that match these CSS selectors, such as .comments. Accepts up to 20 values. |
| `waitFor` | integer | Extra milliseconds to wait before reading, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 3 credits, or 15 on the hardest pages to reach. Must be between 0 and 10000. |
| `timeout` | integer | How long to keep trying, in milliseconds. Pages behind a bot check can need 10 to 30 seconds the first time. Must be between 10000 and 60000. If unset, defaults to `30000`. |
| `maxAge` | integer | Accept a stored answer up to this many milliseconds old. 0 always reads the page live. metadata.`cacheState` says which one you got. Must be between 0 and 172800000. If unset, defaults to `3600000`. |
| `location` | object | Where to read the page from. The default is the United States. |
| `actions` | object\[] | Steps to run on the page, in order, before reading it: `{ "type": "wait", "milliseconds": 500 }`, `{ "type": "wait", "selector": ".results" }`, `{ "type": "click", "selector": "button.more" }`, `{ "type": "write", "text": "tides" }`, `{ "type": "press", "key": "Enter" }` or `{ "type": "scroll", "direction": "down" }`. A read with actions costs 3 credits, or 15 on the hardest pages to reach. Accepts up to 20 values. |
| `maxChars` | integer | Cut the markdown at this many characters; `isTruncated` says when that happened. Must be between 500 and 1000000. |

## Billing

A successful request consumes 1 credit a page for most pages, 2 or 3 credits when a page takes more work to load, and 15 credits for the hardest pages to reach. A read with a screenshot, actions or waitFor costs 3 credits, or 15 on the hardest pages to reach. An answer from a stored copy costs 1 credit. A page that cannot be read costs nothing. Each page is charged when it finishes. Starting the job is free, up to 1500 credits. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Batch Cancel API
Source: https://docs.stophy.dev/api-reference/endpoint/web-batch-cancel

api-reference/openapi.json POST /v1/web/batch/cancel
Stop a batch scrape and keep the pages already read. Call the Web web Batch Cancel API for JSON. 0 credits per call. Every call returns the same flat shape.

Stop a batch scrape and keep the pages already read.

## Request

`id` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.batch.cancel({ id: "job_Ab3dE5gH7jK9mN1pQ3sT5v" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.batch.cancel(id="job_Ab3dE5gH7jK9mN1pQ3sT5v")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/batch/cancel \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"job_Ab3dE5gH7jK9mN1pQ3sT5v"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web batch cancel job_Ab3dE5gH7jK9mN1pQ3sT5v
```

## Response

If successful, the response body contains the standard envelope. `data` contains the batch's progress and credits used when it stopped.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_BC0vf8IzmDUA4VeGy9M7tA",
    "status": "completed",
    "total": 2,
    "completed": 2,
    "failed": 0,
    "creditsUsed": 2
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 0 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Batch Status API
Source: https://docs.stophy.dev/api-reference/endpoint/web-batch-status

api-reference/openapi.json POST /v1/web/batch/status
Check a batch scrape and read the finished pages. Call the Web web Batch Status API for JSON. 0 credits per call. Every call returns the same flat shape.

Check a batch scrape and read the finished pages.

## Request

`id` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.batch.status({ id: "job_Ab3dE5gH7jK9mN1pQ3sT5v" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.batch.status(id="job_Ab3dE5gH7jK9mN1pQ3sT5v")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/batch/status \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"job_Ab3dE5gH7jK9mN1pQ3sT5v"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web batch status job_Ab3dE5gH7jK9mN1pQ3sT5v
```

## Response

If successful, the response body contains the standard envelope. `data` contains the batch's progress and credits used, and `results` lists the pages read so far.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_BC0vf8IzmDUA4VeGy9M7tA",
    "status": "completed",
    "total": 2,
    "completed": 2,
    "failed": 0,
    "creditsUsed": 2,
    "results": [
      {
        "markdown": "[Bun RuntimeA fast JavaScript runtime designed as a drop-in replacement for Node.jsGet started with `bun…",
        "isTruncated": false,
        "metadata": {
          "title": "Welcome to Bun | Bun Docs",
          "description": "Bun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.",
          "language": "en",
          "ogImage": "https://bun.com/og/docs.png",
          "sourceURL": "https://bun.com/docs",
          "statusCode": 200,
          "contentType": "text/html",
          "cacheState": "miss"
        },
        "url": "https://bun.com/docs"
      }
    ]
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Send the cursor from the last answer to get only the pages finished since. A batch and its pages are kept for 24 hours.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 0 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.


# Web web Contacts API
Source: https://docs.stophy.dev/api-reference/endpoint/web-contacts

api-reference/openapi.json POST /v1/web/contacts
Scrape the emails, phone numbers and social profiles a website publishes. Call the Web web Contacts API for JSON. 1 credit per call.

Scrape the emails, phone numbers and social profiles a website publishes.

## Request

`url` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.contacts({ url: "https://plausible.io" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.contacts(url="https://plausible.io")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/contacts \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://plausible.io"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web contacts https://plausible.io
```

## Response

If successful, the response body contains the standard envelope. `data` contains the emails, phone numbers and social profiles the site publishes.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://plausible.io/",
    "emails": [
      {
        "email": "name@example.com",
        "pages": ["https://plausible.io/contact"]
      }
    ],
    "socials": [
      {
        "network": "x",
        "username": "PlausibleHQ",
        "url": "https://x.com/PlausibleHQ",
        "pages": ["https://plausible.io/", "https://plausible.io/contact"]
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

> [!NOTE]
>
> Reads the page you send and the contact, imprint and about pages it links to. Use [Web web Scrape](/api-reference/endpoint/web-scrape) to read a page in full.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Crawl API
Source: https://docs.stophy.dev/api-reference/endpoint/web-crawl

api-reference/openapi.json POST /v1/web/crawl
Crawl a website and scrape its pages as markdown. Call the Web web Crawl API for JSON. From 1 credit per call. Every call returns the same flat shape.

Crawl a website and scrape its pages as markdown.

## Request

`url` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.crawl({ url: "https://bun.com/docs", goal: "sqlite", maxPages: 4 });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.crawl(url="https://bun.com/docs", goal="sqlite", max_pages=4)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/crawl \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://bun.com/docs","goal":"sqlite","maxPages":4}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web crawl https://bun.com/docs --goal sqlite --maxPages 4
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the pages read, each with its depth and its text as markdown.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "pagesRead": 4,
    "results": [
      {
        "url": "https://bun.com/docs",
        "title": "Welcome to Bun | Bun Docs",
        "depth": 0,
        "markdown": "[Bun RuntimeA fast JavaScript runtime designed as a drop-in replacement for Node.jsGet started with `bun…"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `depth` | integer | The nesting level of the comment in the thread. Top-level comments are 0. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Set goal to read the pages about one topic first and stop when the site has no more about it. Use [Web web Map](/api-reference/endpoint/web-map) to only list pages.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `goal` | string | What you are looking for, such as sqlite performance. Pages about it are read first, and the crawl stops once new pages stop mentioning it. |
| `includePaths` | string\[] | Read only pages whose path matches one of these, such as /blog/\*. Accepts up to 20 values. |
| `excludePaths` | string\[] | Skip pages whose path matches one of these, such as /tag/\*. Accepts up to 20 values. |
| `maxDepth` | integer | The number of links away from the start page to go. Must be between 1 and 10. If unset, defaults to `3`. |
| `maxPages` | integer | Stop after reading this many pages in total, across every call. Must be between 1 and 1000. If unset, defaults to `100`. |
| `entireSite` | boolean | Read the whole site, not only pages under the start page's path. If unset, defaults to `false`. |
| `includeSubdomains` | boolean | Also read pages on subdomains, such as docs.bun.com for bun.com. If unset, defaults to `false`. |
| `onlyMainContent` | boolean | Keep only each page's main content, without menus, headers and footers. If unset, defaults to `true`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

A successful request consumes 1 credit a page for most pages, 2 or 3 credits when a page takes more work to load, and 15 credits for the hardest pages to reach. A page that cannot be read costs nothing. Each call reads up to 4 pages, up to 60 credits. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.


# Web web Crawl Cancel API
Source: https://docs.stophy.dev/api-reference/endpoint/web-crawl-cancel

api-reference/openapi.json POST /v1/web/crawl/cancel
Stop a background crawl and keep the pages already read. Call the Web web Crawl Cancel API for JSON. 0 credits per call.

Stop a background crawl and keep the pages already read.

## Request

`id` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.crawl.cancel({ id: "job_Ab3dE5gH7jK9mN1pQ3sT5v" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.crawl.cancel(id="job_Ab3dE5gH7jK9mN1pQ3sT5v")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/crawl/cancel \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"job_Ab3dE5gH7jK9mN1pQ3sT5v"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web crawl cancel job_Ab3dE5gH7jK9mN1pQ3sT5v
```

## Response

If successful, the response body contains the standard envelope. `data` contains the crawl's progress and credits used when it stopped.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_Qg9km6Ss5DAJktZgPYOUkA",
    "status": "completed",
    "total": 4,
    "completed": 4,
    "failed": 0,
    "creditsUsed": 4
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 0 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Crawl Start API
Source: https://docs.stophy.dev/api-reference/endpoint/web-crawl-start

api-reference/openapi.json POST /v1/web/crawl/start
Crawl a website in the background. Call the Web web Crawl Start API and get JSON back in one request. From 0 credits per call. Failed calls cost nothing.

Crawl a website in the background.

## Request

`url` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.crawl.start({ url: "https://bun.com/docs", goal: "sqlite", maxPages: 4 });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.crawl.start(url="https://bun.com/docs", goal="sqlite", max_pages=4)
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/crawl/start \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://bun.com/docs","goal":"sqlite","maxPages":4}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web crawl start https://bun.com/docs --goal sqlite --maxPages 4
```

## Response

If successful, the response body contains the standard envelope. `data` contains the crawl's id and status, to follow with `web.crawl.status`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_Qg9km6Ss5DAJktZgPYOUkA",
    "status": "queued",
    "total": 1
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |

For every field, see the response schema on this page.

> [!NOTE]
>
> It answers at once with an id; ask [Web web Crawl Status](/api-reference/endpoint/web-crawl-status) for the pages, or send webhook to be told as each one finishes.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `goal` | string | What you are looking for, such as sqlite performance. Pages about it are read first, and the crawl stops once new pages stop mentioning it. |
| `includePaths` | string\[] | Read only pages whose path matches one of these, such as /blog/\*. Accepts up to 20 values. |
| `excludePaths` | string\[] | Skip pages whose path matches one of these, such as /tag/\*. Accepts up to 20 values. |
| `maxDepth` | integer | The number of links away from the start page to go. Must be between 1 and 10. If unset, defaults to `3`. |
| `maxPages` | integer | Stop after reading this many pages in total, across every call. Must be between 1 and 1000. If unset, defaults to `100`. |
| `entireSite` | boolean | Read the whole site, not only pages under the start page's path. If unset, defaults to `false`. |
| `includeSubdomains` | boolean | Also read pages on subdomains, such as docs.bun.com for bun.com. If unset, defaults to `false`. |
| `onlyMainContent` | boolean | Keep only each page's main content, without menus, headers and footers. If unset, defaults to `true`. |
| `webhook` | string | A public address that gets a JSON POST when the job starts, for each finished page, and when the job ends. |

## Billing

A successful request consumes 1 credit a page for most pages, 2 or 3 credits when a page takes more work to load, and 15 credits for the hardest pages to reach. A page that cannot be read costs nothing. Each page is charged when it finishes. Starting the job is free, up to 15000 credits. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Crawl Status API
Source: https://docs.stophy.dev/api-reference/endpoint/web-crawl-status

api-reference/openapi.json POST /v1/web/crawl/status
Check a background crawl and read the finished pages. Call the Web web Crawl Status API for JSON. 0 credits per call. Every call returns the same flat shape.

Check a background crawl and read the finished pages.

## Request

`id` is required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.crawl.status({ id: "job_Ab3dE5gH7jK9mN1pQ3sT5v" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.crawl.status(id="job_Ab3dE5gH7jK9mN1pQ3sT5v")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/crawl/status \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"job_Ab3dE5gH7jK9mN1pQ3sT5v"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web crawl status job_Ab3dE5gH7jK9mN1pQ3sT5v
```

## Response

If successful, the response body contains the standard envelope. `data` contains the crawl's progress and credits used, and `results` lists the pages read so far.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_Qg9km6Ss5DAJktZgPYOUkA",
    "status": "completed",
    "total": 4,
    "completed": 4,
    "failed": 0,
    "creditsUsed": 4,
    "results": [
      {
        "url": "https://bun.com/docs",
        "title": "Welcome to Bun | Bun Docs",
        "depth": 0,
        "markdown": "[Bun RuntimeA fast JavaScript runtime designed as a drop-in replacement for Node.jsGet started with `bun…"
      }
    ]
  },
  "creditsUsed": 0,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `total` | integer | The total number of matching results, across all pages. |
| `depth` | integer | The nesting level of the comment in the thread. Top-level comments are 0. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Send the cursor from the last answer to get only the pages finished since. total is the number of pages found so far and grows while the crawl runs. A crawl and its pages are kept for 24 hours.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 0 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.


# Web web Images API
Source: https://docs.stophy.dev/api-reference/endpoint/web-images

api-reference/openapi.json POST /v1/web/images
Scrape image search results. Call the Web web Images API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape image search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.images({ query: "golden retriever", limit: 20 });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.images(query="golden retriever", limit=20)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/images \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"golden retriever","limit":20}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web images "golden retriever" --limit 20
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the images, each with its size, thumbnail and the page it is on.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "imageUrl": "https://cdn.britannica.com/33/136133-004-3385F6F5/golden-retriever.jpg",
        "title": "Golden retriever with mouth open and tongue out, looking forward against a blurred green background.",
        "pageUrl": "https://www.britannica.com/animal/golden-retriever-dog",
        "source": "britannica.com",
        "width": 548,
        "height": 450,
        "thumbnailUrl": "https://imgs.search.brave.com/ybCZuLmHHiIie1YZ44e-HZSORZ-qb69Y_RMxKlUlGG0/rs:fit:500:0:1:0/g:ce/aHR0cHM6Ly9jZG4u/YnJpdG…",
        "position": 1
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `position` | integer | The 1-based position of the result in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `safeSearch` | boolean | Hide explicit images. If unset, defaults to `false`. |
| `limit` | integer | The maximum number of images to return. Billed at 1 credit per 10 returned. Must be between 1 and 100. If unset, defaults to `10`. |

## Billing

A successful request consumes 1 credit per 10 images, up to 10 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Map API
Source: https://docs.stophy.dev/api-reference/endpoint/web-map

api-reference/openapi.json POST /v1/web/map
Scrape the list of pages on a website. Call the Web web Map API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape the list of pages on a website.

## Request

`url` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.map({ url: "https://bun.com", search: "sqlite" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.map(url="https://bun.com", search="sqlite")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/map \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://bun.com","search":"sqlite"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web map https://bun.com --search sqlite
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the site's pages, each with its address and title.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://bun.com/docs/runtime/sqlite",
        "title": "SQLite | Bun Docs"
      }
    ],
    "page": 1,
    "totalPages": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `totalPages` | integer | The number of pages that match the request. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Add search to rank pages about one topic first.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `search` | string | Keep only addresses that mention these words, best matches first, such as pricing. |
| `includeSubdomains` | boolean | Also list pages on subdomains, such as docs.bun.com for bun.com. If unset, defaults to `false`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 100. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 100.


# Web web News API
Source: https://docs.stophy.dev/api-reference/endpoint/web-news

api-reference/openapi.json POST /v1/web/news
Scrape news search results. Call the Web web News API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape news search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.news({ query: "nvidia earnings", time: "pastWeek" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.news(query="nvidia earnings", time="pastWeek")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/news \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nvidia earnings","time":"pastWeek"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web news "nvidia earnings" --time pastWeek
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the articles, each with its source, description and time.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://finance.yahoo.com/markets/stocks/article/nvidia-stock-trims-losses-as-chip-sell-off-eases-amid-ai-financing-con…",
        "title": "Nvidia stock trims losses as chip sell-off eases amid AI financing concerns",
        "source": "Yahoo! Finance",
        "description": "Nvidia and other big chip stocks pared losses as AI jitters eased on Thursday.",
        "publishedAt": "2026-10-15T20:00:34.000Z",
        "position": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `position` | integer | The 1-based position of the result in the list. |
| `publishedAt` | string (ISO 8601) | When the article was published. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `time` | string | Restricts results to articles from the past week, month or year. Leave out for any time. Acceptable values are `pastWeek`, `pastMonth` and `pastYear`. |
| `limit` | integer | The maximum number of articles to return. Billed at 1 credit per 10 returned. Must be between 1 and 50. If unset, defaults to `10`. |

## Billing

A successful request consumes 1 credit per 10 articles, up to 5 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Parse API
Source: https://docs.stophy.dev/api-reference/endpoint/web-parse

api-reference/openapi.json POST /v1/web/parse
Turn a PDF, Word, Excel, PowerPoint or HTML file into markdown. Call the Web web Parse API for JSON. 1 credit per call. Every call returns the same flat shape.

Turn a PDF, Word, Excel, PowerPoint or HTML file into markdown.

## Request

`file` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.parse({ file: "PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=", filename: "tides.html" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.parse(file="PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=", filename="tides.html")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/parse \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"file":"PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=","filename":"tides.html"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web parse "PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=" --filename tides.html
```

## Response

If successful, the response body contains the standard envelope. `data` contains the file's text as markdown, with its metadata.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# How tides work\n\nThe Moon pulls on the oceans and makes two bulges of water that move around the Earth as it turns,…",
    "isTruncated": false,
    "metadata": {
      "title": "How tides work",
      "contentType": "text/html"
    }
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

> [!NOTE]
>
> To read a page or a PDF by its address, use [Web web Scrape](/api-reference/endpoint/web-scrape).

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `filename` | string | The file's name, such as report.docx. The type is read from the file itself. |
| `maxPages` | integer | Read at most this many PDF pages, sheets or slides; `isTruncated` says when the file had more. Must be between 1 and 100. If unset, defaults to `100`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Scrape API
Source: https://docs.stophy.dev/api-reference/endpoint/web-scrape

api-reference/openapi.json POST /v1/web/scrape
Scrape any public web page as markdown, HTML, links or a screenshot. Call the Web web Scrape API for JSON. From 1 credit per call.

Scrape any public web page as markdown, HTML, links or a screenshot.

## Request

`url` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.scrape({ url: "https://bun.com/docs/runtime/bunfig" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.scrape(url="https://bun.com/docs/runtime/bunfig")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://bun.com/docs/runtime/bunfig"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web scrape https://bun.com/docs/runtime/bunfig
```

## Response

If successful, the response body contains the standard envelope. `data` contains the page in the formats requested, as markdown by default, with its metadata.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "`bunfig.toml` is Bun's configuration file.\n\nBun relies on pre-existing configuration files like `package.json` and…",
    "isTruncated": false,
    "metadata": {
      "title": "bunfig.toml | Bun Docs",
      "description": "Configure Bun's behavior using its configuration file bunfig.toml",
      "language": "en",
      "ogImage": "https://bun.com/og/docs/runtime/bunfig.png",
      "sourceURL": "https://bun.com/docs/runtime/bunfig",
      "statusCode": 200,
      "contentType": "text/html",
      "cacheState": "miss"
    }
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

> [!NOTE]
>
> Social, video, shopping and jobs pages have their own endpoints with structured data.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `formats` | object\[] | What to return: markdown (clean page text), html (the cleaned page), `rawHtml` (the page as sent), links (every link on the page) and screenshot (a JPEG of the visible page, as base64). Send `{ "type": "screenshot", "fullPage": true }` for the whole page. A screenshot costs 3 credits, or 15 on the hardest pages to reach. A PDF comes back as markdown only. Accepts up to 5 values. |
| `onlyMainContent` | boolean | Keep only the page's main content, without menus, headers, footers and ads. If unset, defaults to `true`. |
| `includeTags` | string\[] | Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, `onlyMainContent` is not applied. Accepts up to 20 values. |
| `excludeTags` | string\[] | Remove the parts of the page that match these CSS selectors, such as .comments. Accepts up to 20 values. |
| `waitFor` | integer | Extra milliseconds to wait before reading, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 3 credits, or 15 on the hardest pages to reach. Must be between 0 and 10000. |
| `timeout` | integer | How long to keep trying, in milliseconds. Pages behind a bot check can need 10 to 30 seconds the first time. Must be between 10000 and 60000. If unset, defaults to `30000`. |
| `maxAge` | integer | Accept a stored answer up to this many milliseconds old. 0 always reads the page live. metadata.`cacheState` says which one you got. Must be between 0 and 172800000. If unset, defaults to `3600000`. |
| `location` | object | Where to read the page from. The default is the United States. |
| `actions` | object\[] | Steps to run on the page, in order, before reading it: `{ "type": "wait", "milliseconds": 500 }`, `{ "type": "wait", "selector": ".results" }`, `{ "type": "click", "selector": "button.more" }`, `{ "type": "write", "text": "tides" }`, `{ "type": "press", "key": "Enter" }` or `{ "type": "scroll", "direction": "down" }`. A read with actions costs 3 credits, or 15 on the hardest pages to reach. Accepts up to 20 values. |
| `maxChars` | integer | Cut the markdown at this many characters; `isTruncated` says when that happened. Must be between 500 and 1000000. |

## Billing

A successful request consumes 1 credit for most pages. 2 or 3 credits when a page takes more work to load, and 15 credits for the hardest pages to reach. A read with a screenshot, actions or waitFor costs 3 credits, or 15 on the hardest pages to reach. An answer from a stored copy costs 1 credit. A page that cannot be read costs nothing. creditsUsed shows what the call cost, up to 15 credits. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# Web web Search API
Source: https://docs.stophy.dev/api-reference/endpoint/web-search

api-reference/openapi.json POST /v1/web/search
Scrape web search results. Call the Web web Search API and get JSON back in one request. From 1 credit per call. Failed calls cost nothing.

Scrape web search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.web.search({ query: "best project management software", limit: 20 });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.web.search(query="best project management software", limit=20)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/web/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best project management software","limit":20}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy web search "best project management software" --limit 20
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the pages, each with its title and description, and its text when `scrapeResults` is on.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://www.paymoapp.com/blog/project-management-software/",
        "title": "20+ Best Project Management Software for 2026 • Paymo",
        "description": "3 weeks ago - Jira – best for software engineers & programmers · ProjectManager – a complex PM software geared towards…",
        "position": 1
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `position` | integer | The 1-based position of the result in the list. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Turn on scrapeResults to get the text of the top pages in the same call.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. |
| `includeDomains` | string\[] | Restricts results to results from these domains. Accepts up to 10 values. |
| `excludeDomains` | string\[] | Leave out results from these domains. Accepts up to 10 values. |
| `time` | string | Restricts results to pages from the past week, month or year. Leave out for any time. Acceptable values are `pastWeek`, `pastMonth` and `pastYear`. |
| `safeSearch` | boolean | Hide explicit results. If unset, defaults to `false`. |
| `limit` | integer | The maximum number of results to return. Billed at 1 credit per 10 returned. Must be between 1 and 100. If unset, defaults to `10`. |
| `scrapeResults` | boolean | Also read the top results and add each page's text as markdown. Costs 1 more credit for each result that comes back with its text. If unset, defaults to `false`. |
| `scrapeLimit` | integer | The number of of the top results to read when `scrapeResults` is on. Must be between 1 and 5. If unset, defaults to `3`. |

## Billing

A successful request consumes 1 credit per 10 results, plus 1 credit for each result that comes back with its page text when scrapeResults is on, up to 15 credits. Requests that fail, or that return no items, are not billed. Set `limit` to cap the number of items returned and billed.

## Pagination

This method is not paginated. A single request returns the complete result.


# X X Post API
Source: https://docs.stophy.dev/api-reference/endpoint/x-post

api-reference/openapi.json POST /v1/x/post
Scrape an X post. Call the X X Post API and get JSON back in one request. 1 credit per call. Failed calls cost nothing. Every call returns the same flat shape.

Scrape an X post. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.x.post({ postId: "2107773105779167621" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.x.post(post_id="2107773105779167621")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/x/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postId":"2107773105779167621"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy x post --postId 2107773105779167621
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post's text and author, and its exact likes, replies, reposts, quotes, bookmarks and views.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "2107773105779167621",
    "postUrl": "https://x.com/NASA/status/2107773105779167621",
    "text": "LIVE: After nearly eight months aboard the @Space_Station, it’s time for Crew-12 to come home. Tune in as the…",
    "publishedAt": "2026-10-07T10:00:43.000Z",
    "language": "en",
    "likes": 2021,
    "replies": 106,
    "reposts": 331,
    "quotes": 29,
    "bookmarks": 102,
    "views": 2868815,
    "authorId": "11348282",
    "authorUsername": "NASA",
    "authorName": "NASA",
    "authorUrl": "https://x.com/NASA",
    "authorAvatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
    "authorIsVerified": true,
    "links": ["https://x.com/i/broadcasts/1aKbdEQgXAdJX"],
    "mentions": ["Space_Station"],
    "isEdited": false,
    "isSensitive": false
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [X X Profile](/api-reference/endpoint/x-profile): Accepts `username`. Scrape an X profile.
* [X X Profile Posts](/api-reference/endpoint/x-profile-posts): Accepts `username`. Scrape an X profile's posts.


# X X Profile API
Source: https://docs.stophy.dev/api-reference/endpoint/x-profile

api-reference/openapi.json POST /v1/x/profile
Scrape an X profile. Call the X X Profile API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an X profile. The profile or user is identified by its URL or username.

## Request

Exactly one of `profileUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.x.profile({ username: "nasa" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.x.profile(username="nasa")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/x/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"nasa"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy x profile --username nasa
```

## Response

If successful, the response body contains the standard envelope. `data` contains the profile's bio, followers, following, post count and join date.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "11348282",
    "username": "NASA",
    "profileUrl": "https://x.com/NASA",
    "name": "NASA",
    "bio": "Making the seemingly impossible, possible. ✨",
    "location": "Pale Blue Dot",
    "website": "http://www.nasa.gov/",
    "joinedAt": "2007-12-19T20:20:32.000Z",
    "followers": 92329477,
    "following": 115,
    "posts": 74412,
    "isVerified": true,
    "verifiedType": "Government",
    "isProtected": false,
    "avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
    "bannerUrl": "https://pbs.twimg.com/profile_banners/11348282/1788992290"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `posts` | integer | The number of posts. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [X X Profile Posts](/api-reference/endpoint/x-profile-posts): Accepts `profileUrl`. Scrape an X profile's posts.


# X X Profile Posts API
Source: https://docs.stophy.dev/api-reference/endpoint/x-profile-posts

api-reference/openapi.json POST /v1/x/profile/posts
Scrape an X profile's posts. Call the X X Profile Posts API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape an X profile's posts. The profile or user is identified by its URL or username.

## Request

Exactly one of `profileUrl` or `username` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.x.profile.posts({ username: "nasa" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.x.profile.posts(username="nasa")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/x/profile/posts \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"nasa"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy x profile posts --username nasa
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the account's posts, each with its text, time, likes, replies and reposts.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "order": "newest",
    "results": [
      {
        "postId": "2111180963661435219",
        "postUrl": "https://x.com/NASA/status/2111180963661435219",
        "text": "The aircraft lineup just keeps getting bigger. ✈️\n\nMAX POWER, a new aerospace expo, is set for Nov. 7-8 @NASAKennedy —…",
        "publishedAt": "2026-10-16T19:42:20.000Z",
        "language": "en",
        "likes": 1540,
        "replies": 145,
        "reposts": 211,
        "quotes": 24,
        "bookmarks": 62,
        "views": 359353,
        "authorId": "11348282",
        "authorUsername": "NASA",
        "authorName": "NASA",
        "authorUrl": "https://x.com/NASA",
        "authorAvatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
        "authorIsVerified": true,
        "media": [
          {
            "type": "video",
            "url": "https://video.twimg.com/amplify_video/2111180787802370048/vid/avc1/1080x1920/xLb-yr9GVdddx5sY.mp4?tag=29",
            "thumbnailUrl": "https://pbs.twimg.com/amplify_video_thumb/2111180787802370048/img/0nbyTdS0MRg5JqXk.jpg",
            "width": 1080,
            "height": 1920,
            "durationSeconds": 17.751
          }
        ],
        "links": ["https://www.nasa.gov/maxpower/"],
        "mentions": ["NASAKennedy"],
        "isEdited": false,
        "isSensitive": false,
        "isPinned": false,
        "isRepost": false
      }
    ],
    "cursor": "NDk5Mcxn11348282.DAAHCgABHU8DUlr__-wLAAIAAAATMjEwOTMyMDYyMjg4Mjg3MzQ2NAgAAwAAAAIAAA"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `publishedAt` | string (ISO 8601) | The publication time, in UTC. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

> [!NOTE]
>
> Newest first, about 20 a page, with a pinned post on top of the first page. A repost comes back as the original post with isRepost set. For some profiles X shows about 100 popular posts in one page instead, and order says popular.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [X X Profile](/api-reference/endpoint/x-profile): Accepts `username`. Scrape an X profile.
* [X X Post](/api-reference/endpoint/x-post): Accepts `postUrl`. Scrape an X post.


# Yelp yelp Business API
Source: https://docs.stophy.dev/api-reference/endpoint/yelp-business

api-reference/openapi.json POST /v1/yelp/business
Scrape a Yelp business page. Call the Yelp yelp Business API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Yelp business page. The business is identified by its URL or ID.

## Request

Exactly one of `businessUrl` or `businessId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.yelp.business({ businessUrl: "https://www.yelp.com/biz/franklin-barbecue-austin" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.yelp.business(business_url="https://www.yelp.com/biz/franklin-barbecue-austin")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/yelp/business \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"businessUrl":"https://www.yelp.com/biz/franklin-barbecue-austin"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy yelp business --businessUrl https://www.yelp.com/biz/franklin-barbecue-austin
```

## Response

If successful, the response body contains the standard envelope. `data` contains the business's rating, price level, categories, address, phone, website and hours.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "businessId": "MGzro82Fi4LYvc86acoONQ",
    "businessAlias": "franklin-barbecue-austin",
    "businessUrl": "https://www.yelp.com/biz/franklin-barbecue-austin",
    "name": "Franklin Barbecue",
    "rating": 4.5,
    "reviews": 6492,
    "priceLevel": "$$$",
    "categories": ["Barbeque"],
    "addressFull": "900 E 11th St, Austin, TX 78702",
    "addressStreet": "900 E 11th St",
    "addressCity": "Austin",
    "addressRegion": "TX",
    "addressPostalCode": "78702",
    "addressCountry": "US",
    "neighborhoods": ["East Austin"],
    "latitude": 30.2701348,
    "longitude": -97.73134511,
    "phone": "+1 555 0100",
    "website": "https://franklinbbq.com",
    "hours": [
      {
        "day": "Mon",
        "times": ["Closed"]
      }
    ],
    "photosAndVideos": 8631,
    "isClaimed": true
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Yelp yelp Business Reviews](/api-reference/endpoint/yelp-business-reviews): Accepts `businessUrl`. Scrape a Yelp business's reviews.


# Yelp yelp Business Reviews API
Source: https://docs.stophy.dev/api-reference/endpoint/yelp-business-reviews

api-reference/openapi.json POST /v1/yelp/business/reviews
Scrape a Yelp business's reviews. Call the Yelp yelp Business Reviews API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a Yelp business's reviews. The business is identified by its URL or ID.

## Request

Exactly one of `businessUrl` or `businessId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.yelp.business.reviews({ businessUrl: "https://www.yelp.com/biz/franklin-barbecue-austin" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.yelp.business.reviews(business_url="https://www.yelp.com/biz/franklin-barbecue-austin")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/yelp/business/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"businessUrl":"https://www.yelp.com/biz/franklin-barbecue-austin"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy yelp business reviews --businessUrl https://www.yelp.com/biz/franklin-barbecue-austin
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the reviews, each with its rating, text and any reply from the owner.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "businessId": "MGzro82Fi4LYvc86acoONQ",
    "businessName": "Franklin Barbecue",
    "businessUrl": "https://www.yelp.com/biz/franklin-barbecue-austin",
    "total": 6477,
    "results": [
      {
        "reviewId": "Q1kUFPnl5j3_0xrsLfLRYg",
        "reviewUrl": "https://www.yelp.com/biz/franklin-barbecue-austin?hrid=Q1kUFPnl5j3_0xrsLfLRYg",
        "rating": 5,
        "text": "Finally got back to Franklin bbq. Was here last year for a conference in round rock and made it there now back here…",
        "language": "en",
        "createdAt": "2026-10-04T00:58:20.000Z",
        "authorName": "Mike S."
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `page` | integer | The page number of this response. |
| `total` | integer | The total number of matching results, across all pages. |
| `createdAt` | string (ISO 8601) | The creation time, in UTC. |
| `rating` | number | The average star rating, on a scale of 1 to 5. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | relevance (Yelp Sort), newest, oldest, highest (Highest Rated) or lowest (Lowest Rated), the same as Yelp's own Sort menu. Acceptable values are `relevance`, `newest`, `oldest`, `highest` and `lowest`. If unset, defaults to `relevance`. |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 250. If unset, defaults to `1`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 250.

## Related methods

* [Yelp yelp Business](/api-reference/endpoint/yelp-business): Accepts `businessUrl`. Scrape a Yelp business page.


# Yelp yelp Search API
Source: https://docs.stophy.dev/api-reference/endpoint/yelp-search

api-reference/openapi.json POST /v1/yelp/search
Scrape Yelp search results. Call the Yelp yelp Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape Yelp search results.

## Request

`query` and `location` are required.

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.yelp.search({ query: "plumber", location: "Austin, TX" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.yelp.search(query="plumber", location="Austin, TX")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/yelp/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"plumber","location":"Austin, TX"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null}
stophy yelp search --query plumber --location "Austin, TX"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the businesses, each with its rating, price level, categories and address.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "businessId": "TVHztfQAJUIaJDgdJuke-g",
        "businessAlias": "blue-dragon-plumbing-austin-2",
        "businessUrl": "https://www.yelp.com/biz/blue-dragon-plumbing-austin-2",
        "name": "Blue Dragon Plumbing",
        "rating": 4.9,
        "reviews": 532,
        "categories": ["Plumbing"],
        "addressCity": "Austin"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rating` | number | The average star rating, on a scale of 1 to 5. |
| `reviews` | integer | The number of reviews the rating is based on. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Yelp yelp Business](/api-reference/endpoint/yelp-business): Accepts `businessUrl`. Scrape a Yelp business page.
* [Yelp yelp Business Reviews](/api-reference/endpoint/yelp-business-reviews): Accepts `businessUrl`. Scrape a Yelp business's reviews.


# YouTube youTube Channel API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-channel

api-reference/openapi.json POST /v1/youtube/channel
Scrape a YouTube channel and its videos. Call the YouTube youTube Channel API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a YouTube channel and its videos. The channel is identified by its URL or ID.

## Request

Exactly one of `channelUrl` or `channelId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.channel({ channelId: "@mkbhd" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.channel(channel_id="@mkbhd")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/channel \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"channelId":"@mkbhd"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube channel --channelId @mkbhd
```

## Response

If successful, the response body contains the standard envelope. `data` contains the channel's profile, and `results` lists the items on the tab requested.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "channelId": "UCBJycsmduvYEL83R_U4JriQ",
    "channelUrl": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ",
    "channelName": "Marques Brownlee",
    "channelUsername": "mkbhd",
    "description": "MKBHD: Quality Tech Videos | YouTuber | Geek | Consumer Electronics | Tech Head | Internet Personality!\n…",
    "subscribers": 21300000,
    "videos": 1800,
    "avatarUrl": "https://yt3.googleusercontent.com/qu4TmIaYUlS41-dJ9gZ7DUR3nilvmB5_11i6OKSdvNnBNiyOusZP1bMN6ICnuxtjFBb6ioKgRQ=s900-c-k-c…",
    "bannerUrl": "https://yt3.googleusercontent.com/zi_48HwHU4s0Hnb6tZuvRzTfCPHrLEnrtIMDLzMauDEyDmURh9JZ4wrNd3lKr7m9uVnT4YjYKw=w2560-fcro…",
    "country": "United States",
    "joinedDate": "2008-03-21",
    "totalViews": 5744272029,
    "results": [
      {
        "type": "video",
        "videoId": "3iRUwVzRDZQ",
        "videoUrl": "https://www.youtube.com/watch?v=3iRUwVzRDZQ",
        "title": "Xiaomi 18 Fold: How Does This Happen?",
        "channelId": "UCBJycsmduvYEL83R_U4JriQ",
        "channelName": "Marques Brownlee",
        "channelUrl": "https://www.youtube.com/channel/UCBJycsmduvYEL83R_U4JriQ",
        "channelUsername": "mkbhd",
        "durationSeconds": 647,
        "views": 8100000,
        "thumbnailUrl": "https://i.ytimg.com/vi/3iRUwVzRDZQ/hqdefault.jpg",
        "isShort": false,
        "isLive": false,
        "publishedAt": "2026-10-03T20:46:58.000Z"
      }
    ],
    "cursor": "4qmFsgLZCRIYVUNCSnljc21kdXZZRUw4M1JfVTRKcmlRGrwJOGdhRUJ4cUJCM3ItQmpyN0Jnb2tObUl5TjJJeU5UUXRNREF3TUMweVl6UmpMV0pqTUdVdFp…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video`, `playlist` or `post`. |
| `videos` | integer | The number of videos the channel has. |
| `publishedAt` | string (ISO 8601) | Approximate. YouTube lists show only how long ago a video was published, so this is rounded to that unit, such as a day or a year. [YouTube youTube Video](/api-reference/endpoint/youtube-video) has the exact time. |
| `durationSeconds` | integer | The duration, in seconds. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `tab` | string | Specifies which tab of the channel to read. `releases` are a music channel's albums. Acceptable values are `videos`, `shorts`, `live`, `playlists`, `podcasts`, `releases` and `posts`. If unset, defaults to `videos`. |
| `sort` | string | Specifies the order of the items on the videos, shorts and live tabs. Acceptable values are `latest`, `popular` and `oldest`. If unset, defaults to `latest`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page. A cursor expires 6 hours after it is issued.

## Related methods

* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts `videoUrl`. Scrape a YouTube video's transcript.
* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts `videoUrl`. Scrape a YouTube video page.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoUrl`. Scrape the comments of a YouTube video.
* [YouTube youTube Post](/api-reference/endpoint/youtube-post): Accepts `postUrl`. Scrape a YouTube community post and its comments.


# YouTube youTube Comments API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-comments

api-reference/openapi.json POST /v1/youtube/comments
Scrape the comments of a YouTube video. Call the YouTube youTube Comments API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape the comments of a YouTube video. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.comments({ videoId: "p0fybvFyOlM" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.comments(video_id="p0fybvFyOlM")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/comments \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoId":"p0fybvFyOlM"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube comments --videoId p0fybvFyOlM
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the comments, or the replies when `comment` is set.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "commentId": "UgxzofZjVZTGbGSqq9N4AaABAg",
        "commentUrl": "https://www.youtube.com/watch?v=p0fybvFyOlM&lc=UgxzofZjVZTGbGSqq9N4AaABAg",
        "text": "Sandbox aren't enough. Your agents need a devbox. A full development environment with all your dependencies.…",
        "authorId": "UCUyeluBRhGPCW4rPe_UvBZQ",
        "authorName": "ThePrimeTimeagen",
        "authorUsername": "ThePrimeTimeagen",
        "authorUrl": "https://www.youtube.com/channel/UCUyeluBRhGPCW4rPe_UvBZQ",
        "likes": 33,
        "replies": 8,
        "publishedAt": "2026-10-03T20:46:53.000Z",
        "isPinned": true,
        "isHearted": false,
        "isChannelOwner": true,
        "repliesCursor": "Eg0SC3AwZnlidkZ5T2xNGAYygwEaUBIaVWd4em9mWmpWWlRHYkdTcXE5TjRBYUFCQWciAggAKhhVQ1V5ZWx1QlJoR1BDVzRyUGVfVXZCWlEyC3AwZnlidkZ…"
      }
    ],
    "cursor": "Eg0SC3AwZnlidkZ5T2xNGAYygQMK1wJnZXRfcmFua2VkX3N0cmVhbXMtLUNxWUJDSUFFRlJlMzBUZ2Ftd0VLbGdFSTJGOFFnQVFZQnlLTEFkdDllSzZveXJ…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `repliesCursor` | string | A token. Pass it as `comment` to retrieve this comment's replies. |
| `publishedAt` | string (ISO 8601) | Approximate. YouTube shows only how long ago a comment was written, so this is rounded to that unit, such as a day or a year. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `comment` | string | A comment's `repliesCursor` from an earlier response. Returns that comment's replies. |
| `sort` | string | Specifies which comments are returned first. Acceptable values are `top` and `newest`. If unset, defaults to `top`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts a comment's `repliesCursor` as `comment`. Scrape the comments of a YouTube video.
* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts the same `videoId`. Scrape a YouTube video page.
* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts the same `videoId`. Scrape a YouTube video's transcript.


# YouTube youTube Playlist API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-playlist

api-reference/openapi.json POST /v1/youtube/playlist
Scrape a YouTube playlist and its videos. Call the YouTube youTube Playlist API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a YouTube playlist and its videos. The playlist is identified by its URL or ID.

## Request

Exactly one of `playlistUrl` or `playlistId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.playlist({ playlistId: "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.playlist(playlist_id="PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/playlist \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"playlistId":"PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube playlist --playlistId PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI
```

## Response

If successful, the response body contains the standard envelope. `data` contains the playlist's details, and `results` lists a page of its videos.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "playlistId": "PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI",
    "playlistUrl": "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI",
    "title": "Popular Music Videos",
    "channelId": "UC-9-kyTW8ZkZNDHQJ6FgpwQ",
    "channelName": "Music",
    "channelUrl": "https://www.youtube.com/channel/UC-9-kyTW8ZkZNDHQJ6FgpwQ",
    "videos": 182,
    "views": 1045669467,
    "thumbnailUrl": "https://i.ytimg.com/vi/fOT0BUpITw8/hqdefault.jpg",
    "results": [
      {
        "type": "video",
        "videoId": "fOT0BUpITw8",
        "videoUrl": "https://www.youtube.com/watch?v=fOT0BUpITw8",
        "title": "BELLAKEO (Video Oficial) - Peso Pluma, Anitta",
        "channelId": "UCzrM_068Odho89mTRrrxqbA",
        "channelName": "Peso Pluma",
        "channelUrl": "https://www.youtube.com/channel/UCzrM_068Odho89mTRrrxqbA",
        "durationSeconds": 235,
        "views": 765000000,
        "thumbnailUrl": "https://i.ytimg.com/vi/fOT0BUpITw8/hqdefault.jpg",
        "isShort": false,
        "isLive": false,
        "publishedAt": "2024-10-05T09:08:51.000Z"
      }
    ],
    "cursor": "4qmFsgKBARIkVkxQTEZncXVMbkw1OWFsQ2xfMlRRdk9pRDVWZ20xaENhR1NJGjRDQUY2SGxCVU9rTkhVV2xGUlZrMVVXdGFRazFVWXpOT1JFazFUWHBSZVU…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video`. |
| `publishedAt` | string (ISO 8601) | Approximate. YouTube lists show only how long ago a video was published, so this is rounded to that unit, such as a day or a year. [YouTube youTube Video](/api-reference/endpoint/youtube-video) has the exact time. |
| `durationSeconds` | integer | The duration, in seconds. |
| `videos` | integer | The number of videos. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts `videoUrl`. Scrape a YouTube video's transcript.
* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts `videoUrl`. Scrape a YouTube video page.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoUrl`. Scrape the comments of a YouTube video.
* [YouTube youTube Channel](/api-reference/endpoint/youtube-channel): Accepts `channelUrl`. Scrape a YouTube channel and its videos.


# YouTube youTube Post API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-post

api-reference/openapi.json POST /v1/youtube/post
Scrape a YouTube community post and its comments. Call the YouTube youTube Post API for JSON. 1 credit per call. Every call returns the same flat shape.

Scrape a YouTube community post and its comments. The post is identified by its URL or ID.

## Request

Exactly one of `postUrl` or `postId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.post({ postId: "UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.post(post_id="UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/post \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"postId":"UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube post --postId UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ
```

## Response

If successful, the response body contains the standard envelope. `data` contains the post's text, images and likes, and `results` lists its comments.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "postId": "UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ",
    "postUrl": "https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ",
    "text": "Alright, it's that time: https://vote.mkbhd.com\n\nWelcome to the Blind Smartphone Camera Test 2023! 20 smartphones. 3…",
    "publishedAt": "2024-10-05T09:08:44.000Z",
    "likes": 12000,
    "comments": 1041,
    "imageUrls": ["https://yt3.ggpht.com/zy6PEg0QzlzFe8xfDxpAbe1mGV0pXgc-xV1MvQ7rlf_EWjEj_YqN0Y2b7fiaOCdghICsMxy8tDGDaA=s1516-rw-nd-v1"],
    "results": [
      {
        "commentId": "Ugwy052tBWynxReFHN94AaABAg",
        "commentUrl": "https://www.youtube.com/post/UgkxX6gkDxQ0KRucvyG7NLui0LhjHp0CLlfZ?lc=Ugwy052tBWynxReFHN94AaABAg",
        "text": "waiting for the new video, \"Let's Talk About Vehicular Felonies.\"",
        "authorId": "UCjU-RRrNmxYVD5RpCuaKZBw",
        "authorName": "Kirkenheimer15",
        "authorUsername": "Kirkenheimer15",
        "authorUrl": "https://www.youtube.com/channel/UCjU-RRrNmxYVD5RpCuaKZBw",
        "likes": 201,
        "replies": 2,
        "publishedAt": "2025-10-05T14:57:57.000Z",
        "isPinned": false,
        "isHearted": false,
        "isChannelOwner": false,
        "repliesCursor": "4qmFsgLQAhIrRkVjb21tZW50X3Bvc3RfZGV0YWlsX3BhZ2Vfd2ViX3JlcGxpZXNfcGFnZRqgAkVnVndiM04wYzhvQko3SUJKRlZuYTNoWU5tZHJSSGhSTUV…"
      }
    ],
    "cursor": "4qmFsgKFBRIoRkVjb21tZW50X3Bvc3RfZGV0YWlsX3BhZ2Vfd2ViX3RvcF9sZXZlbBrYBEVnVndiM04wYzZvRHR3TUswd0puWlhSZmNtRnVhMlZrWDNOMGN…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `repliesCursor` | string | Send this as cursor to [YouTube youTube Post](/api-reference/endpoint/youtube-post), with the same `postId`, to read this comment's replies. It does not work with [YouTube youTube Comments](/api-reference/endpoint/youtube-comments). |
| `publishedAt` | string (ISO 8601) | Approximate. YouTube shows only how long ago a post was published, so this is rounded to that unit, such as a day or a year. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `sort` | string | Specifies which comments are returned first. Acceptable values are `top` and `newest`. If unset, defaults to `top`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts `videoId`. Scrape a YouTube video's transcript.
* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts `videoId`. Scrape a YouTube video page.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoId`. Scrape the comments of a YouTube video.


# YouTube youTube Search API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-search

api-reference/openapi.json POST /v1/youtube/search
Scrape YouTube search results. Call the YouTube youTube Search API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape YouTube search results.

## Request

`query` is required.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.search({ query: "rust tutorial" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.search(query="rust tutorial")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"rust tutorial"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube search "rust tutorial"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains videos, channels and playlists, and each row has a `type`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "video",
        "videoId": "Wc0ZJo06oAw",
        "videoUrl": "https://www.youtube.com/watch?v=Wc0ZJo06oAw",
        "title": "The Ultimate Rust Beginners Guide (2026)",
        "channelId": "UCt6XPuD8u3YjvybuT-Xnj5A",
        "channelName": "SBJake",
        "channelUrl": "https://www.youtube.com/channel/UCt6XPuD8u3YjvybuT-Xnj5A",
        "channelUsername": "SBJake",
        "durationSeconds": 422,
        "views": 551049,
        "thumbnailUrl": "https://i.ytimg.com/vi/Wc0ZJo06oAw/hqdefault.jpg",
        "isShort": false,
        "isLive": false,
        "publishedAt": "2025-10-05T14:57:29.000Z"
      },
      {
        "type": "playlist",
        "playlistId": "PLai5B987bZ9CoVR-QEIN9foz4QCJ0H2Y8",
        "playlistUrl": "https://www.youtube.com/playlist?list=PLai5B987bZ9CoVR-QEIN9foz4QCJ0H2Y8",
        "title": "The Rust Lang Book",
        "channelId": "UCSp-OaMpsO8K0KkOqyBl7_w",
        "channelName": "Let's Get Rusty",
        "channelUrl": "https://www.youtube.com/channel/UCSp-OaMpsO8K0KkOqyBl7_w",
        "channelUsername": "letsgetrusty",
        "videos": 44,
        "thumbnailUrl": "https://i.ytimg.com/vi/OX9HJsJUDxA/hq720.jpg?sqp=-oaymwEXCNAFEJQDSFryq4qpAwkIARUAAIhCGAE=&rs=AOn4CLAWZwWdy65d2agorLt2YN…"
      }
    ],
    "cursor": "seen.eyJ0b2tlbiI6IkVzNEVFZzF5ZFhOMElIUjFkRzl5YVdGc0dyd0VVMEpUUTBGUmRGaFpla0poVTIwNGQwNXRPVUprTkVsQ1NXeENUV1ZyTVdwUmEyUn…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `cursor` | string | The pagination token. Pass it as `cursor` to retrieve the next page. Omitted on the last page. |
| `type` | string | The kind of item: `video`, `channel` or `playlist`. |
| `publishedAt` | string (ISO 8601) | Approximate. YouTube lists show only how long ago a video was published, so this is rounded to that unit, such as a day or a year. [YouTube youTube Video](/api-reference/endpoint/youtube-video) has the exact time. |
| `durationSeconds` | integer | The duration, in seconds. |
| `videos` | integer | The number of videos. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | Leave out for videos, channels and playlists. Use shorts for Shorts. Acceptable values are `videos`, `shorts`, `channels`, `playlists` and `movies`. |
| `duration` | string | Restricts results to videos of this length. Acceptable values are `under3Minutes`, `3to20Minutes` and `over20Minutes`. |
| `uploadDate` | string | Restricts results to videos uploaded in this period. Acceptable values are `today`, `thisWeek`, `thisMonth` and `thisYear`. |
| `features` | string\[] | Restricts results to videos with these features. Accepts one of 11 values, such as `360`, `live` and `4k`. Accepts up to 11 values. |
| `prioritize` | string | Specifies how results are ranked. Acceptable values are `relevance` and `popularity`. If unset, defaults to `relevance`. |
| `cursor` | string | The pagination token from the previous response. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, pass the value of `data.cursor` as `cursor` in a subsequent request. A response that omits `cursor` is the last page.

## Related methods

* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts `videoUrl`. Scrape a YouTube video's transcript.
* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts `videoUrl`. Scrape a YouTube video page.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoUrl`. Scrape the comments of a YouTube video.
* [YouTube youTube Channel](/api-reference/endpoint/youtube-channel): Accepts `channelUrl`. Scrape a YouTube channel and its videos.


# YouTube youTube Suggestions API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-suggest

api-reference/openapi.json POST /v1/youtube/suggest
Scrape YouTube search suggestions. Call the YouTube youTube Suggestions API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape YouTube search suggestions.

## Request

`query` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.suggest({ query: "how to learn" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.suggest(query="how to learn")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/suggest \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"how to learn"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube suggest "how to learn"
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the suggestions, best first.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "keyword": "how to learn spanish",
        "rank": 1
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `rank` | integer | The 1-based position of the entry in the list. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `country` | string | The country to query, as a two-letter ISO 3166-1 code such as `us`. Accepts one of 107 values, such as `dz`, `ar` and `au`. If unset, defaults to `us`. |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. If unset, defaults to `en`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [YouTube youTube Search](/api-reference/endpoint/youtube-search): Accepts a suggestion as `query`. Scrape YouTube search results.
* [Google Trends interest over time](/api-reference/endpoint/google-trends-interest): Accepts a suggestion as `queries`. Scrape Google Trends interest over time.


# YouTube youTube Transcript API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-transcript

api-reference/openapi.json POST /v1/youtube/transcript
Scrape a YouTube video's transcript. Call the YouTube youTube Transcript API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a YouTube video's transcript. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.transcript({ videoUrl: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" });
console.log(result.data.text);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.transcript(video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(result["data"]["text"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/transcript \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoUrl":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube transcript --videoUrl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

## Response

If successful, the response body contains the standard envelope. `data` contains what the video says as one block of `text`.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "videoId": "p0fybvFyOlM",
    "videoUrl": "https://www.youtube.com/watch?v=p0fybvFyOlM",
    "language": "ar",
    "isAutoGenerated": true,
    "durationSeconds": 799,
    "text": "يا للهول. شيء جديد على وشك الحدوث. حسناً، سنرى شيئاً جديداً قادماً من OpenAI. هذا صحيح. سنحصل على شيء مذهل. وهل تعرف…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `text` | string | The whole transcript as one block. |
| `isAutoGenerated` | boolean | `true` if YouTube wrote the captions, not a person. |
| `language` | string | The language of the transcript. |
| `durationSeconds` | number | The duration, in seconds. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `language` | string | The language of the results, as a BCP 47 tag such as `en` or `pt-BR`. |
| `includeTimestamps` | boolean | Return each line with its start and end time, in `segments`. If unset, defaults to `false`. |

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [YouTube youTube Video](/api-reference/endpoint/youtube-video): Accepts `videoUrl`. Scrape a YouTube video page.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoUrl`. Scrape the comments of a YouTube video.


# YouTube youTube Video API
Source: https://docs.stophy.dev/api-reference/endpoint/youtube-video

api-reference/openapi.json POST /v1/youtube/video
Scrape a YouTube video page. Call the YouTube youTube Video API and get JSON back in one request. 1 credit per call. Failed calls cost nothing.

Scrape a YouTube video page. The video is identified by its URL or ID.

## Request

Exactly one of `videoUrl` or `videoId` is required. A request that sets both, or none, fails with `invalidRequest`.

> [!NOTE]
>
> This endpoint can be called without an API key, subject to per-address limits. Pagination requires a key.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.video({ videoId: "p0fybvFyOlM" });
console.log(result.data.title);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.video(video_id="p0fybvFyOlM")
print(result["data"]["title"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/video \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoId":"p0fybvFyOlM"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube video --videoId p0fybvFyOlM
```

## Response

If successful, the response body contains the standard envelope. `data` contains the video's title, channel, stats, description and tags, plus chapters and most replayed moments when it has them.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "videoId": "p0fybvFyOlM",
    "videoUrl": "https://www.youtube.com/watch?v=p0fybvFyOlM",
    "title": "A total disaster",
    "channelId": "UCUyeluBRhGPCW4rPe_UvBZQ",
    "channelName": "The PrimeTime",
    "channelUrl": "https://www.youtube.com/channel/UCUyeluBRhGPCW4rPe_UvBZQ",
    "channelUsername": "ThePrimeTimeagen",
    "durationSeconds": 799,
    "views": 699503,
    "thumbnailUrl": "https://i.ytimg.com/vi/p0fybvFyOlM/hqdefault.jpg",
    "isShort": false,
    "isLive": false,
    "publishedAt": "2026-10-03T03:48:31.000Z",
    "description": "Sandbox aren't enough. Your agents need a devbox. A full development environment with all your dependencies.…",
    "likes": 10482,
    "category": "Science & Technology",
    "tags": ["programming"],
    "comments": 1100,
    "channelSubscribers": 1170000
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `publishedAt` | string (ISO 8601) | When the video was published. |
| `durationSeconds` | integer | The duration, in seconds. |
| `likes` | integer | The number of likes. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 1 credit, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [YouTube youTube Transcript](/api-reference/endpoint/youtube-transcript): Accepts `videoUrl`. Scrape a YouTube video's transcript.
* [YouTube youTube Comments](/api-reference/endpoint/youtube-comments): Accepts `videoUrl`. Scrape the comments of a YouTube video.
* [YouTube youTube Channel](/api-reference/endpoint/youtube-channel): Accepts `channelUrl`. Scrape a YouTube channel and its videos.


# Zillow zillow Property API
Source: https://docs.stophy.dev/api-reference/endpoint/zillow-property

api-reference/openapi.json POST /v1/zillow/property
Scrape a Zillow property page. Call the Zillow zillow Property API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape a Zillow property page. The property is identified by its URL or ID.

## Request

Exactly one of `propertyUrl` or `propertyId` is required. A request that sets both, or none, fails with `invalidRequest`.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.zillow.property({ propertyUrl: "https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.zillow.property(property_url="https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/zillow/property \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"propertyUrl":"https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy zillow property --propertyUrl https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/
```

## Response

If successful, the response body contains the standard envelope. `data` contains the home's price, address, size, description, photos and facts.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "propertyId": "29399286",
    "propertyUrl": "https://www.zillow.com/homedetails/106-W-32nd-St-Austin-TX-78705/29399286_zpid/",
    "status": "FOR_SALE",
    "homeType": "SINGLE_FAMILY",
    "price": 2200000,
    "priceCurrency": "USD",
    "addressFull": "106 W 32nd St, Austin, TX 78705",
    "addressStreet": "106 W 32nd St",
    "addressCity": "Austin",
    "addressRegion": "TX",
    "addressPostalCode": "78705",
    "latitude": 30.297354,
    "longitude": -97.736565,
    "bedrooms": 4,
    "bathrooms": 3,
    "sqft": 2911,
    "lotSize": 9801,
    "lotSizeUnit": "Square Feet",
    "yearBuilt": 1925,
    "description": "The Spurgeon Bell House is a designated City of Austin historic landmark located in the Aldridge Place Historic…",
    "imageUrls": ["https://photos.zillowstatic.com/fp/53de2e39052ef79395ed54f9e73dfded-uncropped_scaled_within_1536_1152.jpg"],
    "daysOnZillow": 2,
    "views": 772,
    "saves": 77,
    "propertyTaxRate": 1.46,
    "mlsId": "7637220",
    "mlsName": "Unlock MLS",
    "brokerName": "Kuper Sotheby's Int'l Realty",
    "brokerPhone": "+1 555 0100",
    "facts": [
      {
        "name": "bathrooms",
        "value": "3"
      }
    ]
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `price` | number | Asking price, monthly rent, or the sale price of a sold home. Omitted when Zillow shows none, such as for sold homes in states that keep sale prices private. |
| `daysOnZillow` | integer | The number of days since the home was listed. |

For every field, see the response schema on this page.

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

This method is not paginated. A single request returns the complete result.

## Related methods

* [Zillow zillow Search](/api-reference/endpoint/zillow-search): Accepts the home's `addressCity` and `addressRegion` as `location`. Scrape Zillow search results.


# Zillow zillow Search API
Source: https://docs.stophy.dev/api-reference/endpoint/zillow-search

api-reference/openapi.json POST /v1/zillow/search
Scrape Zillow search results. Call the Zillow zillow Search API and get JSON back in one request. 2 credits per call. Failed calls cost nothing.

Scrape Zillow search results.

## Request

`location` is required.

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.zillow.search({ location: "Austin, TX", daysOnZillow: "30Days", hasPool: true });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.zillow.search(location="Austin, TX", days_on_zillow="30Days", has_pool=True)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/zillow/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"location":"Austin, TX","daysOnZillow":"30Days","hasPool":true}'
```

```bash CLI icon="square-terminal" theme={null}
stophy zillow search "Austin, TX" --daysOnZillow 30Days --hasPool
```

## Response

If successful, the response body contains the standard envelope. `data.results[]` contains the homes, each with its price, address, size and status.

The following example is a real response, truncated: each list shows one item and long strings are cut.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "propertyId": "29399286",
        "propertyUrl": "https://www.zillow.com/homedetails/106-W-32nd-St-Austin-TX-78705/29399286_zpid/",
        "status": "forSale",
        "statusText": "Active",
        "price": 2200000,
        "priceCurrency": "USD",
        "addressFull": "106 W 32nd St, Austin, TX 78705",
        "addressStreet": "106 W 32nd St",
        "addressCity": "Austin",
        "addressRegion": "TX",
        "addressPostalCode": "78705",
        "latitude": 30.297354,
        "longitude": -97.736565,
        "bedrooms": 4,
        "bathrooms": 3,
        "sqft": 2911,
        "homeType": "SINGLE_FAMILY",
        "daysOnZillow": 2,
        "brokerName": "Kuper Sotheby's Int'l Realty",
        "imageUrl": "https://photos.zillowstatic.com/fp/53de2e39052ef79395ed54f9e73dfded-p_e.jpg"
      }
    ],
    "total": 151,
    "page": 1,
    "totalPages": 4
  },
  "creditsUsed": 2,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

| Field | Type | Description |
| - | - | - |
| `price` | number | Asking price, monthly rent, or the sale price of a sold home. Omitted when Zillow shows none, such as for sold homes in states that keep sale prices private. |
| `page` | integer | The page number of this response. |
| `totalPages` | integer | The number of pages that match the request. |
| `total` | integer | The total number of matching results, across all pages. |
| `statusText` | string | The listing status label as displayed by Zillow, such as `Active`. |
| `daysOnZillow` | integer | The number of days since the home was listed. |

For every field, see the response schema on this page.

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Homes for sale, for rent or sold. Acceptable values are `forSale`, `forRent` and `sold`. If unset, defaults to `forSale`. |
| `minPrice` | number | The minimum price. |
| `maxPrice` | number | The maximum price. |
| `minBedrooms` | integer | The minimum number of bedrooms. Must be between 0 and 20. |
| `maxBedrooms` | integer | The maximum number of bedrooms. Must be between 0 and 20. |
| `minBathrooms` | number | The minimum number of bathrooms. Must be between 0 and 20. |
| `minSqft` | integer | The minimum size, in square feet. |
| `maxSqft` | integer | The maximum size, in square feet. |
| `minLotSize` | integer | The minimum lot, in square feet. |
| `maxLotSize` | integer | The maximum lot, in square feet. |
| `minYearBuilt` | integer | Restricts results to homes built in or after this year. Must be between 1600 and 2100. |
| `maxYearBuilt` | integer | Restricts results to homes built in or before this year. Must be between 1600 and 2100. |
| `maxHoa` | number | The maximum monthly HOA fee, in USD. `0` means no HOA fee. |
| `minParkingSpots` | integer | Restricts results to homes with at least this many parking spots. Must be between 1 and 4. |
| `daysOnZillow` | string | Restricts results to homes listed in the last 1, 7, 14, 30 or 90 days, or 6, 12, 24 or 36 months. For sold homes, it means sold in that time. Acceptable values are `1Day`, `7Days`, `14Days`, `30Days`, `90Days`, `6Months`, `12Months`, `24Months` and `36Months`. |
| `hasPool` | boolean | Restricts results to homes with a pool. If unset, defaults to `false`. |
| `hasGarage` | boolean | Restricts results to homes with a garage. If unset, defaults to `false`. |
| `hasAirConditioning` | boolean | Restricts results to homes with air conditioning. If unset, defaults to `false`. |
| `isWaterfront` | boolean | Restricts results to waterfront homes. If unset, defaults to `false`. |
| `singleStory` | boolean | Restricts results to single-story homes. If unset, defaults to `false`. |
| `openHouse` | boolean | Restricts results to homes with an open house. If unset, defaults to `false`. |
| `priceReduced` | boolean | Restricts results to homes with a price cut. If unset, defaults to `false`. |
| `has3dTour` | boolean | Restricts results to homes with a 3D tour. If unset, defaults to `false`. |
| `petsAllowed` | boolean | Restricts results to places that allow pets. Rentals only: set `status` to `forRent`. If unset, defaults to `false`. |
| `homeTypes` | string\[] | Zillow's own Home type filter. On rentals, apartment and condo are one Zillow category (apartments, condos and co-ops), so either one returns both. Acceptable values are `house`, `townhouse`, `multiFamily`, `condo`, `land`, `apartment` and `manufactured`. |
| `sort` | string | Specifies the order of the homes. Acceptable values are `relevance`, `newest`, `priceHigh`, `priceLow`, `bedrooms`, `bathrooms`, `squareFeet` and `lotSize`. If unset, defaults to `relevance`. |
| `keywords` | string | Words the listing must mention, such as "pool" or "fixer upper". |
| `page` | integer | The page to return. Pages are numbered from 1. Must be between 1 and 20. If unset, defaults to `1`. |

## Billing

Each successful request consumes 2 credits, regardless of the number of items returned. Requests that fail, or that return no items, are not billed.

## Pagination

Results are paginated. To retrieve the next page, increment `page`. An empty `data.results` indicates the last page. The maximum value of `page` is 20.

## Related methods

* [Zillow zillow Property](/api-reference/endpoint/zillow-property): Accepts `propertyUrl`. Scrape a Zillow property page.


# Errors
Source: https://docs.stophy.dev/api-reference/errors

Every Stophy API error code with its HTTP status, what it means and whether to retry. A failed call costs nothing. Try the free ones yourself.

Leave out the required field and read the error. No key needed.

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

> **Response**
>
> ```json theme={null}
> {
>   "error": {
>     "code": "invalidRequest",
>     "message": "query: Invalid input: expected string, received undefined",
>     "retryable": false,
>     "requestId": "8667f9a7-7548-41a1-9d68-2a1d81229b91"
>   },
>   "success": false
> }
> ```

The status is `400`. Every error has this shape, and a failed call costs nothing.

| Field | What it is |
| - | - |
| `code` | A stable code from the table below |
| `message` | What went wrong, in plain words |
| `retryable` | `true` when the same request may work later |
| `retryAfterSeconds` | Present when you should wait a set time. The `Retry-After` header has the same value. |
| `requestId` | The ID of this request. Include it when you contact support. |

## Error codes

| Code | Status | Retryable | What it means |
| - | - | - | - |
| `invalidRequest` | 400 | No | The input is not valid. The message names the field. |
| `unauthorized` | 401 | No | The API key is missing or not valid. |
| `insufficientCredits` | 402 | No | Your balance is too low for this call. The error adds `requiredCredits`, `availableCredits` and `billingUrl`. [Add credits](/billing). |
| `notFound` | 404 | No | The endpoint, or the thing you asked for, does not exist. |
| `rateLimited` | 429 | Yes | Too many requests. Wait for `Retry-After`. |
| `internalError` | 500, 503 | Yes | Something went wrong on our side. Try again shortly. |
| `sourceChanged` | 502 | No | The site answered in a shape we could not read. Retrying will not help yet. |
| `sourceUnavailable` | 503 | Yes | The site is not answering right now. Try again in a few seconds. |
| `sourceRefused` | 503 | Yes | The site is refusing requests right now. Try again in a few minutes. |
| `sourceTimeout` | 504 | Yes | The site took too long to answer. Try again. |

## Try the free ones

These calls cost nothing. The first needs no key, and the rest are real responses from today.

**A field the endpoint does not take.** `400 invalidRequest`

```json theme={null}
{ "code": "invalidRequest", "message": "Unknown field `foo`. Fields: query, country, language, includeDomains, excludeDomains, time, safeSearch, page, scrapeResults, scrapeLimit", "retryable": false }
```

**Both of a pair, or neither.** `400 invalidRequest`, from `youtube.transcript` with `videoId` and `videoUrl` together.

```json theme={null}
{ "code": "invalidRequest", "message": "Send exactly one of videoUrl or videoId.", "retryable": false }
```

**A `limit` where the endpoint has none.** `400 invalidRequest`, from `google.search`.

```json theme={null}
{ "code": "invalidRequest", "message": "limit: removed. Each call returns one page from the site; send page for the next one.", "retryable": false }
```

**A cursor that is not from this request.** `400 invalidRequest`, from `reddit.search` with a key.

```json theme={null}
{ "code": "invalidRequest", "message": "cursor: This is not a cursor returned for this request. Send the cursor from the last response to the same request, unchanged, or leave cursor out to start again from page 1 and get a fresh one.", "retryable": false }
```

**Paging with no key.** `400 invalidRequest`, from `google.search` with `page: 2`.

```json theme={null}
{ "code": "invalidRequest", "message": "Paging needs an API key: https://stophy.dev/signup", "retryable": false }
```

**An endpoint that needs a key, with no key.** `401 unauthorized`, from `reddit.post`.

```json theme={null}
{ "code": "unauthorized", "message": "Send an API key as Authorization: Bearer <key>. Get a key: https://stophy.dev/signup", "retryable": false }
```

**A path that is not an endpoint.** `404 notFound`, sent with a key.

```json theme={null}
{ "code": "notFound", "message": "No endpoint at this path. See every endpoint at https://api.stophy.dev/v1/endpoints", "retryable": false }
```

**Something that does not exist.** `404 notFound`, from `youtube.video` with a made-up id.

```json theme={null}
{ "code": "notFound", "message": "YouTube has no playable video with that id. Check videoUrl or videoId; the video may be private, removed or age-restricted.", "retryable": false }
```

## Account codes

These come from your account and the dashboard, not from a data endpoint.

| Code | Status | Retryable | What it means |
| - | - | - | - |
| `forbidden` | 403 | No | This request is not allowed. |
| `unsupportedMediaType` | 415 | No | Send the body as JSON with `content-type: application/json`. |
| `invalidCliSession` | 400 | No | The sign-in session is not valid. |
| `invalidCliVerifier` | 400 | No | The sign-in verifier is not valid. |
| `cliSessionNotFound` | 404 | No | The sign-in session was not found or has expired. |
| `cliSessionExists` | 409 | No | The sign-in session already exists. |
| `cliSessionCompleted` | 409 | No | The sign-in session is no longer pending. |
| `inviteClaimed` | 409 | No | You already claimed this invite. |
| `inviteDisabled` | 410 | No | This invite link was turned off. |
| `inviteExpired` | 410 | No | This invite link has expired. |
| `inviteUsedUp` | 410 | No | This invite link has been used up. |

## Retrying

Retry only when `retryable` is `true`. Wait for `retryAfterSeconds` or `Retry-After` when present, and back off otherwise. The [retry guide](/guides/errors-and-retries) has a loop for Node.js and Python.


# Introduction
Source: https://docs.stophy.dev/api-reference/introduction

Stophy is a web scraping API for AI agents. One base URL, a bearer key, a JSON body for every endpoint, and one response shape for every call.

> [!NOTE]
>
> **For AI agents:** use [llms.txt](https://docs.stophy.dev/llms.txt) for a full index of these docs.

Stophy is a web scraping API for AI agents. Every endpoint is a `POST` to the same base URL with a JSON body. No key needed for this one.

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

You get Google results back with `creditsUsed: 0`. The path is `/v1/` plus the endpoint id with dots as slashes, so `youtube.transcript` is `/v1/youtube/transcript`. A field the endpoint does not take returns `400`.

## What you can get

> **[Search and AI answers](/sources/web)**
>
> Google results, news, images, papers and trends.

> **[Video](/sources/video)**
>
> YouTube, TikTok and Instagram videos, transcripts and comments.

> **[Social](/sources/social)**
>
> Posts, profiles and comments from Reddit, X, Instagram, Facebook, LinkedIn, Threads and Pinterest.

> **[Places and travel](/sources/places-and-travel)**
>
> Google Maps and Tripadvisor places and reviews, hotels and flights.

> **[Jobs](/sources/jobs)**
>
> Job listings from LinkedIn, Indeed and Upwork.

> **[Shopping](/sources/shopping)**
>
> Amazon, eBay and TikTok Shop products and prices.

> **[Apps](/sources/apps)**
>
> App Store and Google Play apps, reviews and charts.

> **[Real estate](/sources/real-estate)**
>
> Homes for sale, for rent and sold from Zillow.

> **[Ads](/sources/ads)**
>
> Ad libraries from Meta, Google, TikTok and LinkedIn.

Every endpoint is in the sidebar, grouped the same way.

## Base URL

```text theme={null}
https://api.stophy.dev
```

## Authentication

Create a key in the [dashboard](https://stophy.dev/signup). Send it with every request:

```text theme={null}
Authorization: Bearer <key>
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"bun runtime"}'
```

```ts TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
const response = await fetch("https://api.stophy.dev/v1/reddit/search", {
  method: "POST",
  headers: {
    authorization: "Bearer " + process.env.STOPHY_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({ query: "bun runtime" }),
});
```

```python Python icon="python" theme={null}
import os
import requests

response = requests.post(
    "https://api.stophy.dev/v1/reddit/search",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"query": "bun runtime"},
    timeout=30,
)
```

A missing or invalid key on an endpoint that needs one returns `401` with code `unauthorized`. The endpoints marked `keyless: true` in the [catalog](https://api.stophy.dev/v1/endpoints) work without a key, with [rate limits](/rate-limits).

## Responses

A successful call returns `success`, `data`, `creditsUsed` and `requestId`.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [{ "title": "Bun", "url": "https://bun.com/", "position": 1 }]
  },
  "creditsUsed": 1,
  "requestId": "7db121ac-d8e6-479a-b17c-59e3fe5fabd8"
}
```

`data` is one object. A list comes back in `data.results`, with `data.cursor` when another page exists. A value that belongs to a related resource carries that resource in its name, such as `videoId`, `videoUrl`, `channelName` and `placeId`. Empty values are left out.

A failed call returns an error status and `{ "success": false, "error": { ... } }`. See [Errors](/api-reference/errors).

## One call, one page, one price

Each call returns one page. Most calls cost 1 credit and a few cost 2. A few are priced by what comes back, such as long lists and transcripts. A call that fails or finds nothing costs nothing. See [Credits and billing](/billing).

Some endpoints take `page`, some take `cursor`, and the rest return everything in one call. See [Page through results](/guides/paging).

## Send a link or an id

To point at one thing, send its link or its id, never both. That is `videoUrl` or `videoId`, `placeUrl` or `placeId`, `userUrl` or `username`, and so on. Each endpoint's page lists the pair. Sending both, or neither, returns a `400`.


# Logs
Source: https://docs.stophy.dev/api-reference/logs

GET https://api.stophy.dev/v1/logs
List your recent paid Stophy API calls, newest first, with the endpoint, credits used and time of each call. Filter by days, endpoint and API key.

See what your key has spent credits on. Needs an API key, and the call is free.

```bash theme={null}
curl "https://api.stophy.dev/v1/logs?days=7&page=0&endpoint=google.search" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

You get your recent paid calls, 50 per page, newest first. Only paid calls are logged.

**days** `integer` (default: 7)

How many days back to look, from 1 to 90.

**page** `integer` (default: 0)

The page to return, from 0. Past the last page you get an empty `logs` list.

**endpoint** `string`

Only calls to this endpoint id, such as `google.search`.

**apiKeyId** `string`

Only calls made with this API key.

**logs** `object[]` *required*

The calls on this page.

**properties**

**id** `string`

The log entry ID.

**requestId** `string`

The `requestId` the call returned.

**createdAt** `string`

When the call was made, as an ISO 8601 time.

**endpoint** `string`

The endpoint id, such as `google.search`.

**credits** `integer`

Credits the call used.

**apiKeyId** `string | null`

The API key used.

**apiKeyName** `string | null`

That key's name.

**method** `string`

Always `POST`.

**status** `integer`

Always `200`.

**response** `string`

Always `success`.

**durationMs** `integer | null`

Always `null`.

**endpoints** `string[]` *required*

Every endpoint id, for building a filter.

**page** `integer` *required*

The page returned.

**pageSize** `integer` *required*

Calls per page: 50.

**total** `integer` *required*

Calls that match, across all pages.

**totalPages** `integer` *required*

How many pages there are.

```bash cURL icon="terminal" theme={null}
curl "https://api.stophy.dev/v1/logs?days=7&page=0&endpoint=google.search" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json 200 theme={null}
{
  "endpoints": ["google.search", "youtube.search"],
  "logs": [
    {
      "apiKeyId": "string",
      "apiKeyName": "string",
      "createdAt": "2026-10-10T11:37:54.740Z",
      "credits": 1,
      "durationMs": null,
      "endpoint": "google.search",
      "id": "string",
      "method": "POST",
      "requestId": "aa3feb18-5eed-48cd-a72d-a7b3050989d9",
      "response": "success",
      "status": 200,
      "tags": []
    }
  ],
  "page": 0,
  "pageSize": 50,
  "total": 1,
  "totalPages": 1
}
```

A `days` outside 1 to 90, or a negative `page`, returns `400` with code `invalidRequest`. This response is not wrapped in `success` and `data`.


# Usage
Source: https://docs.stophy.dev/api-reference/usage

GET https://api.stophy.dev/v1/usage
Get your Stophy credit balance and lifetime usage with one call: credits left in micros, credits used and how many paid requests you have made.

Check your balance and totals. Needs an API key, and the call is free.

```bash theme={null}
curl https://api.stophy.dev/v1/usage \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

**balanceMicros** `integer` *required*

Your balance in millionths of a dollar. One credit is `1500`, so divide by 1,500 to get credits.

**creditsUsed** `integer` *required*

Credits used by all your calls so far.

**requestCount** `integer` *required*

How many paid calls you have made.

```bash cURL icon="terminal" theme={null}
curl https://api.stophy.dev/v1/usage \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json 200 theme={null}
{
  "balanceMicros": 1200000,
  "creditsUsed": 300,
  "requestCount": 120
}
```

This response is not wrapped in `success` and `data`. Without a valid key it returns `401` with code `unauthorized`.


# Credits and billing
Source: https://docs.stophy.dev/billing

Stophy credits start at $0.80 per 1,000. New accounts get 1,000 free, most calls cost 1 credit, and a call that fails or finds nothing costs nothing.

Most calls cost 1 credit, new accounts get 1,000 free, and a call that fails or finds nothing costs nothing.

## Price

| You add | Price per 1,000 credits |
| - | - |
| Less than \$100 | \$1.50 |
| \$100 or more | \$1.20 |
| \$500 or more | \$0.80 |

Top up at [stophy.dev](https://stophy.dev). The smallest top-up is \$10. Credits never expire.

## What a call costs

Of the 110 endpoints, 94 cost 1 credit and 9 cost 2. Seven are priced per unit.

| Cost | Endpoints |
| - | - |
| 2 credits | `amazon.search`, `amazon.product`, `amazon.bestsellers`, `zillow.search`, `zillow.property`, `instagram.profile`, `linkedin.profile` |
| 1 credit per 10 images | `google.images` |
| 1 credit per 10 apps | `appstore.search`, `appstore.top`, `google.play.search` |
| 1 credit, plus 1 for each result read in full | `google.search`, when `scrapeResults` is on |
| 2 credits, plus 1 per 10 seconds of audio | `instagram.transcript` |
| 1 credit with captions, or 2 credits plus 1 per 10 seconds of audio | `tiktok.transcript` |

Every other endpoint costs 1 credit, however many results come back.

Each endpoint's price is on its page in the [API reference](/api-reference/introduction). The catalog has it too, as `credits` and, when the price varies, `pricing`.

```bash theme={null}
curl https://api.stophy.dev/v1/endpoints
```

## Transcripts

`youtube.transcript` costs 1 credit. For `instagram.transcript` and `tiktok.transcript`, audio is rounded up to the next 10 seconds. Instagram goes up to 30 minutes, which is 182 credits at most. TikTok goes up to 3 minutes, which is 20 credits at most. A longer video is refused and costs nothing.

When audio was transcribed, the response has `transcribedSeconds`.

## Limit the cost of a long list

`google.images`, `google.ads.advertisers`, `appstore.search`, `appstore.top` and `google.play.search` take `limit`. On the priced ones, a smaller `limit` costs fewer credits.

## Pages

One call returns one page. The next page is a new call and costs the same again. See [Page through results](/guides/paging).

## See what a call cost

Every successful response has `creditsUsed` in the body and an `x-credits-used` header. For your balance and history, use [`GET /v1/usage`](/api-reference/usage) and [`GET /v1/logs`](/api-reference/logs).

## Running out

When your balance is too low, the call answers `402` with code `insufficientCredits` and charges nothing. The error says how many credits the call needs and how many you have.


# Anthropic
Source: https://docs.stophy.dev/developer-guides/llm-sdks/anthropic

Give Claude live web search with Stophy. Save one search function, define it as a tool, and let the tool runner call it when Claude asks.

Give Claude live web search. Claude asks for a search, your code calls Stophy, and Claude answers from the results.

## The search tool

Save this as `stophy.ts`. It calls Google search and returns the top 5 results as JSON. It works with no key. Set `STOPHY_API_KEY` to lift the free limit.

```ts stophy.ts theme={null}
export async function stophySearch(query: string): Promise<string> {
  const headers: Record<string, string> = { "content-type": "application/json" };
  if (process.env.STOPHY_API_KEY) headers.authorization = `Bearer ${process.env.STOPHY_API_KEY}`;
  const response = await fetch("https://api.stophy.dev/v1/google/search", {
    method: "POST",
    headers,
    body: JSON.stringify({ query }),
  });
  const body = await response.json();
  if (!body.success) throw new Error(body.error.message);
  return JSON.stringify(body.data.results.slice(0, 5));
}
```

## Give it to Claude

```bash theme={null}
npm install @anthropic-ai/sdk zod
```

Set `ANTHROPIC_API_KEY` in your environment.

`betaZodTool` defines the search as a tool. The tool runner calls it whenever Claude asks, and returns Claude's final message.

```ts theme={null}
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
import { stophySearch } from "./stophy";

const client = new Anthropic();

const webSearch = betaZodTool({
  name: "web_search",
  description: "Search the web. Returns the top results as JSON.",
  inputSchema: z.object({ query: z.string().describe("What to search for") }),
  run: async ({ query }) => stophySearch(query),
});

const message = await client.beta.messages.toolRunner({
  model: "claude-sonnet-5-5",
  max_tokens: 16000,
  tools: [webSearch],
  messages: [{ role: "user", content: "What changed in the latest Bun release?" }],
});

for (const block of message.content) {
  if (block.type === "text") console.log(block.text);
}
```


# OpenAI
Source: https://docs.stophy.dev/developer-guides/llm-sdks/openai

Give an OpenAI model live web search with Stophy. Save one search function, pass it as a tool, and send the results back when the model asks.

Give an OpenAI model live web search. The model asks for a search, your code calls Stophy, and the model answers from the results.

## The search tool

Save this as `stophy.ts`. It calls Google search and returns the top 5 results as JSON. It works with no key. Set `STOPHY_API_KEY` to lift the free limit.

```ts stophy.ts theme={null}
export async function stophySearch(query: string): Promise<string> {
  const headers: Record<string, string> = { "content-type": "application/json" };
  if (process.env.STOPHY_API_KEY) headers.authorization = `Bearer ${process.env.STOPHY_API_KEY}`;
  const response = await fetch("https://api.stophy.dev/v1/google/search", {
    method: "POST",
    headers,
    body: JSON.stringify({ query }),
  });
  const body = await response.json();
  if (!body.success) throw new Error(body.error.message);
  return JSON.stringify(body.data.results.slice(0, 5));
}
```

## Give it to an OpenAI model

```bash theme={null}
npm install openai
```

Set `OPENAI_API_KEY` in your environment.

Pass the search as a function tool to the Responses API. While the model keeps calling it, run the search and send the result back.

```ts theme={null}
import OpenAI from "openai";
import { stophySearch } from "./stophy";

const openai = new OpenAI();

const tools: OpenAI.Responses.Tool[] = [
  {
    type: "function",
    name: "web_search",
    description: "Search the web. Returns the top results as JSON.",
    parameters: {
      type: "object",
      properties: { query: { type: "string", description: "What to search for" } },
      required: ["query"],
      additionalProperties: false,
    },
    strict: true,
  },
];

let response = await openai.responses.create({
  model: "gpt-5-mini",
  input: "What changed in the latest Bun release?",
  tools,
});

while (true) {
  const calls = response.output.filter((item) => item.type === "function_call");
  if (calls.length === 0) break;
  const outputs: OpenAI.Responses.ResponseInputItem[] = [];
  for (const call of calls) {
    const { query } = JSON.parse(call.arguments) as { query: string };
    outputs.push({ type: "function_call_output", call_id: call.call_id, output: await stophySearch(query) });
  }
  response = await openai.responses.create({
    model: "gpt-5-mini",
    previous_response_id: response.id,
    input: outputs,
    tools,
  });
}

console.log(response.output_text);
```


# Vercel AI SDK
Source: https://docs.stophy.dev/developer-guides/llm-sdks/vercel-ai-sdk

Give any AI SDK model live web search with Stophy. Save one search function, wrap it in tool() with zod, and let the model call it in generateText.

Give any AI SDK model live web search. The model asks for a search, `execute` calls Stophy, and the model answers from the results.

## The search tool

Save this as `stophy.ts`. It calls Google search and returns the top 5 results as JSON. It works with no key. Set `STOPHY_API_KEY` to lift the free limit.

```ts stophy.ts theme={null}
export async function stophySearch(query: string): Promise<string> {
  const headers: Record<string, string> = { "content-type": "application/json" };
  if (process.env.STOPHY_API_KEY) headers.authorization = `Bearer ${process.env.STOPHY_API_KEY}`;
  const response = await fetch("https://api.stophy.dev/v1/google/search", {
    method: "POST",
    headers,
    body: JSON.stringify({ query }),
  });
  const body = await response.json();
  if (!body.success) throw new Error(body.error.message);
  return JSON.stringify(body.data.results.slice(0, 5));
}
```

## Give it to the AI SDK

```bash theme={null}
npm install ai @ai-sdk/openai zod
```

Set `OPENAI_API_KEY` in your environment.

Wrap the search in `tool()`. `stopWhen` lets the model search, read the results and answer in up to five steps. Any AI SDK model works, so swap `openai(...)` for another provider.

```ts theme={null}
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs, tool } from "ai";
import { z } from "zod";
import { stophySearch } from "./stophy";

const { text } = await generateText({
  model: openai("gpt-5-mini"),
  prompt: "What changed in the latest Bun release?",
  tools: {
    webSearch: tool({
      description: "Search the web. Returns the top results as JSON.",
      inputSchema: z.object({ query: z.string().describe("What to search for") }),
      execute: async ({ query }) => stophySearch(query),
    }),
  },
  stopWhen: stepCountIs(5),
});

console.log(text);
```


# Handle errors and retries
Source: https://docs.stophy.dev/guides/errors-and-retries

Read the error code, retry only when retryable is true, wait for Retry-After, and back off. A failed call costs nothing. Retry loops for Node.js and Python.

Send a bad call and see what an error looks like. No key needed.

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

> **Response**
>
> ```json theme={null}
> {
>   "error": {
>     "code": "invalidRequest",
>     "message": "Unknown field `foo`. Fields: query, country, language, includeDomains, excludeDomains, time, safeSearch, page, scrapeResults, scrapeLimit",
>     "retryable": false,
>     "requestId": "fb79d36c-6041-4e7f-a934-ed72fef872c2"
>   },
>   "success": false
> }
> ```

Every error has this shape, and a failed call costs nothing. Read `retryable` before you do anything else.

## Decide what to do

| When | Do this |
| - | - |
| `retryable` is `false` | Don't retry. Fix the request, or read the message. |
| `retryAfterSeconds` is set | Wait that many seconds, then retry. The `Retry-After` header has the same value. |
| `retryable` is `true` with no wait | Back off: 0.5 s, then 1 s, then 2 s. |
| Still failing after a few tries | Stop, and log the `requestId`. |

Every code is listed in [Errors](/api-reference/errors).

## A retry loop

```ts Node.js theme={null}
async function call(id: string, input: object, attempts = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(`https://api.stophy.dev/v1/${id.replaceAll(".", "/")}`, {
      method: "POST",
      headers: {
        authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
        "content-type": "application/json",
      },
      body: JSON.stringify(input),
      signal: AbortSignal.timeout(30_000),
    });
    const body = await response.json();
    if (body.success) return body.data;
    if (!body.error.retryable || attempt + 1 >= attempts) {
      throw new Error(`${body.error.code}: ${body.error.message} (${body.error.requestId})`);
    }
    const seconds = body.error.retryAfterSeconds ?? 0.5 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}
```

```python Python theme={null}
import os
import time

import requests


def call(endpoint_id, payload, attempts=3):
    for attempt in range(attempts):
        response = requests.post(
            f"https://api.stophy.dev/v1/{endpoint_id.replace('.', '/')}",
            headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
            json=payload,
            timeout=30,
        )
        body = response.json()
        if body["success"]:
            return body["data"]
        error = body["error"]
        if not error["retryable"] or attempt + 1 >= attempts:
            raise RuntimeError(f"{error['code']}: {error['message']} ({error['requestId']})")
        time.sleep(error.get("retryAfterSeconds", 0.5 * 2**attempt))
```

## Common cases

* **`401 unauthorized`** means the key is missing or wrong. Send `Authorization: Bearer <key>`.
* **`402 insufficientCredits`** means your balance is too low. The error says how many credits the call needs and how many you have. [Add credits](/billing) and try again.
* **`429 rateLimited`** means you are over your [rate limits](/rate-limits). Wait, then retry.
* **`400 invalidRequest`** means the input is not valid. The message names the field. Check the endpoint's input in the [API reference](/api-reference/introduction).
* **`404 notFound`** means the thing you asked for does not exist. Don't retry.

## Timeouts

Every call answers or fails within 25 seconds. Set your client timeout a little above that, such as 30 seconds.


# Find the right endpoint
Source: https://docs.stophy.dev/guides/find-endpoint

Search the live Stophy catalog by keyword, browse it by category, or read one endpoint's full input before you write a call. No key needed to look.

Search the catalog for any word. No key needed.

```bash cURL theme={null}
curl -s https://api.stophy.dev/v1/endpoints \
  | jq -r '.endpoints[] | select(.id | contains("video")) | "\(.id): \(.summary)"'
```

```bash CLI theme={null}
stophy endpoints video
```

```text theme={null}
youtube.video: Scrape a YouTube video page
tiktok.video: Scrape a TikTok video
```

Drop the keyword to list every endpoint: `curl -s https://api.stophy.dev/v1/endpoints` or `stophy endpoints`. Each entry has the id, a summary, the price, the input, an example, and `keyless: true` when it needs no key.

## Read one endpoint's input

Once you have an id, get its input and a working example.

```bash cURL theme={null}
curl -s https://api.stophy.dev/v1/endpoints \
  | jq '.endpoints[] | select(.id == "youtube.transcript")'
```

```bash CLI theme={null}
stophy youtube transcript --help
```

> **Response**
>
> ```json theme={null}
> {
>   "id": "youtube.transcript",
>   "summary": "Scrape a YouTube video's transcript",
>   "credits": 1,
>   "keyless": true,
>   "input": {
>     "type": "object",
>     "properties": {
>       "videoUrl": { "type": "string" },
>       "videoId": { "type": "string" },
>       "language": { "type": "string" },
>       "includeTimestamps": { "default": false, "type": "boolean" }
>     },
>     "sendOne": ["videoUrl", "videoId"],
>     "additionalProperties": false
>   },
>   "example": { "videoId": "p0fybvFyOlM" }
> }
> ```

The `example` field is a call you can send as it is. `sendOne` lists the fields where you send one and not both. A field not in `input` returns a `400`.

## Browse by category

Each page under [What you can get](/sources/web) lists the endpoints for one category, with the price and a call you can copy. The [API reference](/api-reference/introduction) has the same input for every endpoint.

Over [MCP](/mcp-server), the `stophy_search_endpoints` tool runs this same search for your agent.

> [!TIP]
>
> Try a call in the [playground](https://stophy.dev/playground) before you write any code.


# Page through results
Source: https://docs.stophy.dev/guides/paging

Get more than one page from Stophy. Send page 2, 3 and on until a page is empty, or send back the cursor from each response until none comes back.

Ask for page 2 of a search. Paging needs an API key.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/google/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"rust tutorial","page":2}'
```

> **Response**
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "results": [
>       {
>         "type": "web",
>         "url": "https://github.com/ImplFerris/LearnRust",
>         "title": "ImplFerris/LearnRust: Rust Learning Resources",
>         "description": "Rust Crash Course Tutorial : This playlist is designed to guide you from the very basics of Rust to its most advanced features. Rust 101 Crash Course: Learn ...",
>         "position": 1
>       }
>     ],
>     "page": 2
>   },
>   "creditsUsed": 1,
>   "requestId": "f53e44c9-6007-46b2-b65e-73a3d3fac03f"
> }
> ```

One call returns one page, the way the site shows it. Page 2 continues page 1 with no repeats. A page holds what the site puts on it, so the number of results changes from call to call.

Each endpoint pages in one of three ways. Its page in the [API reference](/api-reference/introduction) says which.

| The endpoint takes | How to get the next page | Examples |
| - | - | - |
| `page` | Send the same input with `page: 2`, then `3`, until `data.results` is empty. An empty page costs nothing. | `google.search`, `google.news`, `google.maps.search`, `zillow.search`, `amazon.search`, `upwork.search` |
| `cursor` | Send the same input with the `cursor` from the last response, until a response has no `cursor`. | `youtube.search`, `reddit.search`, `tiktok.search`, `instagram.comments` |
| neither | There is no next page. One call returns everything for that input. | `google.maps.place`, `appstore.search`, `google.images` |

Keep the rest of the input the same between pages. Each page is a normal call and costs its normal price.

## Loop through numbered pages

```ts Node.js theme={null}
const results = [];
for (let page = 1; page <= 5; page += 1) {
  const response = await fetch("https://api.stophy.dev/v1/google/search", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ query: "rust tutorial", page }),
  });
  const { data } = await response.json();
  results.push(...data.results);
  if (data.results.length === 0) break;
}
```

```python Python theme={null}
import os
import requests

results = []
for page in range(1, 6):
    response = requests.post(
        "https://api.stophy.dev/v1/google/search",
        headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
        json={"query": "rust tutorial", "page": page},
        timeout=30,
    )
    data = response.json()["data"]
    results += data["results"]
    if not data["results"]:
        break
```

## Loop through cursors

The response carries a `cursor` when there is a next page. Send it back, unchanged, with the same input.

```json theme={null}
{
  "success": true,
  "data": {
    "results": [{ "videoId": "Wc0ZJo06oAw", "title": "The Ultimate Rust Beginners Guide (2026)" }],
    "cursor": "fms9tEb3seen.eyJ0b2t..."
  },
  "creditsUsed": 1,
  "requestId": "43c2f153-e261-4147-a315-cc4eb1543585"
}
```

```ts Node.js theme={null}
const results = [];
let cursor: string | undefined;
do {
  const response = await fetch("https://api.stophy.dev/v1/youtube/search", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ query: "rust tutorial", cursor }),
  });
  const { data } = await response.json();
  results.push(...data.results);
  cursor = data.cursor;
} while (cursor && results.length < 100);
```

```python Python theme={null}
import os
import requests

results = []
cursor = None
while True:
    body = {"query": "rust tutorial"}
    if cursor:
        body["cursor"] = cursor
    response = requests.post(
        "https://api.stophy.dev/v1/youtube/search",
        headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
        json=body,
        timeout=30,
    )
    data = response.json()["data"]
    results += data["results"]
    cursor = data.get("cursor")
    if not cursor or len(results) >= 100:
        break
```

Set your own stop, like the 5 pages or 100 results above. Some sources have many pages. A cursor only works with the input that produced it. Any other cursor returns a `400` with code `invalidRequest`.

## Keep fewer results

`google.images`, `google.ads.advertisers`, `appstore.search`, `appstore.top` and `google.play.search` take `limit`. Send it to return fewer results. On `google.images`, `appstore.search`, `appstore.top` and `google.play.search`, 10 results cost 1 credit, so fewer results cost less.

On every other endpoint, `limit` returns a `400`. To keep a model's context small, take the rows you need from `data.results`, or use `fields` through the [MCP server](/mcp-server) to keep only some keys.


# Introduction
Source: https://docs.stophy.dev/introduction

Stophy is a web scraping API for AI agents. One API to search the web, read what people say, and look up products, places, jobs and homes.

Stophy is a web scraping API for AI agents. One API to search the web, read what people say, and look up products, places, jobs and homes. Pay only for answers.

## Try it now

No account, no key. Run this.

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

> **Response**
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "results": [
>       {
>         "type": "web",
>         "url": "https://bun.com/",
>         "title": "Bun — A fast all-in-one JavaScript runtime",
>         "description": "Bun is a fast JavaScript runtime & toolkit. All in one. Runtime, package manager, test runner and bundler in a single binary.",
>         "position": 1
>       }
>     ]
>   },
>   "creditsUsed": 0,
>   "requestId": "5d8fa22c-6ed4-4690-b20f-5b6b92b160a6"
> }
> ```

You get Google results with `creditsUsed: 0`. A key lifts the free limit, and a failed call costs nothing.

## Connect your agent

```bash Claude Code theme={null}
claude mcp add --transport http stophy https://api.stophy.dev/mcp
```

```bash Codex theme={null}
codex mcp add stophy --url https://api.stophy.dev/mcp
```

Your agent can use the free endpoints right away. To use every endpoint, sign in with your browser at `https://mcp.stophy.dev/mcp`. Every other client has its own page in [MCP server](/mcp-server).

## What your agent can get

> **[Search and AI answers](/sources/web)**
>
> Google results, news and Scholar papers.

> **[Video](/sources/video)**
>
> YouTube and TikTok videos, comments and transcripts.

> **[Social](/sources/social)**
>
> Reddit threads, X posts, and Instagram, Facebook, LinkedIn and Threads pages.

> **[Places and travel](/sources/places-and-travel)**
>
> Google Maps reviews, hotels, flights, Airbnb and Booking.com.

> **[Jobs](/sources/jobs)**
>
> LinkedIn, Indeed, Upwork and company careers pages.

> **[Shopping](/sources/shopping)**
>
> Amazon and eBay prices, and Trustpilot reviews.

> **[Apps](/sources/apps)**
>
> App Store and Google Play apps and their reviews.

> **[Real estate](/sources/real-estate)**
>
> Zillow homes for sale, for rent and sold.

> **[Ads](/sources/ads)**
>
> The Meta, Google, TikTok and LinkedIn ad libraries.

## Search, then read

Find posts with `reddit.search`, then open one with `reddit.post` to read its comments. Most sites work this way. Each call returns one page, and the response tells you how to get the next. `reddit.search` is free to try, and `reddit.post` needs a key. See [Page through results](/guides/paging).

## What it costs

* Most calls cost 1 credit.
* New accounts get 1,000 free credits.
* A call that fails or finds nothing costs nothing.

See [Credits and billing](/billing) for the few that cost more.

## Next

> **[Quickstart](/quickstart)**
>
> Get a key and call Stophy from TypeScript, Python or the CLI.

> **[Find an endpoint](/guides/find-endpoint)**
>
> Pick the right endpoint for what you need.

> **[API reference](/api-reference/introduction)**
>
> Every endpoint, with its inputs, outputs and price.

> **[llms.txt](https://docs.stophy.dev/llms.txt)**
>
> These docs as one index your agent can read.


# MCP server
Source: https://docs.stophy.dev/mcp-server

Connect Claude Code, Codex, Cursor or any MCP client to Stophy with no key, with your browser, or with an API key. One command per client.

Connect your agent to Stophy in one command. Pick your client and run it.

### Set up Stophy MCP

Start with no API key. Add a key or sign in for every endpoint.

Choose an MCP client

**Using another MCP client?** `https://api.stophy.dev/mcp`
Use this URL with Streamable HTTP. Add an Authorization: Bearer \<key> header for every endpoint.

This needs no key. Your agent can use the free endpoints right away.

## Choose how to connect

> **[No key](/mcp-server/keyless)**
>
> Free endpoints only. Nothing to set up.

> **[Browser sign-in](/mcp-server/oauth)**
>
> Every endpoint. Approve the app in your browser.

> **[API key](/mcp-server/keyless#add-an-api-key)**
>
> Every endpoint. Your key goes in the client config.

| | URL |
| - | - |
| No key or API key | `https://api.stophy.dev/mcp` |
| Browser sign-in | `https://mcp.stophy.dev/mcp` |

Both are server URLs for your client, not pages to open in a browser.

## What your agent sees

Three tools. `stophy_search_endpoints` finds an endpoint, `stophy_describe_endpoint` shows its inputs, and `stophy_call` runs it. `stophy_call` takes `id`, `input` and optional `fields`, which keeps only the keys you name on each result.

Ask *"What are people saying about Bun on Reddit?"* and your agent finds `reddit.search`, calls it, and answers. A call costs the same credits as over HTTP. See [Credits and billing](/billing).

To get one tool per endpoint for some sources, add `toolsets` to the URL.

```text theme={null}
https://api.stophy.dev/mcp?toolsets=reddit,youtube
```

## Client guides

> **[Claude Code](/quickstarts/claude-code)**

> **[Claude Desktop](/quickstarts/claude-desktop)**

> **[Cursor](/quickstarts/cursor)**

> **[Codex](/quickstarts/codex)**


# No key and API key
Source: https://docs.stophy.dev/mcp-server/keyless

Add Stophy to Claude Code, Codex, Cursor or OpenCode with no key to use the free endpoints, then add an API key to use every endpoint.

Run one command and your agent can use the free endpoints. No account.

### Set up Stophy MCP

Start with no API key. Add a key or sign in for every endpoint.

Choose an MCP client

**Using another MCP client?** `https://api.stophy.dev/mcp`
Use this URL with Streamable HTTP. Add an Authorization: Bearer \<key> header for every endpoint.

The free endpoints are the ones marked `keyless: true` in the [endpoint list](https://api.stophy.dev/v1/endpoints). Google search, YouTube search and Reddit search are among them.

## Add an API key

A key lets your agent use every endpoint. [Create one](https://stophy.dev/signup). New accounts get 1,000 free credits. Then use the same URL with your key.

### Set up Stophy MCP

Use your API key for every endpoint.

Choose an MCP client

**Using another MCP client?** `https://api.stophy.dev/mcp`
Use this URL with Streamable HTTP. Add an Authorization: Bearer \<key> header for every endpoint.

A key that is wrong is refused. Remove the header to go back to the free endpoints.

## Check it

Ask your agent this.

```text theme={null}
Search YouTube for "rust tutorial" and summarize the top three videos.
```

If `stophy` shows no tools, restart your client. Prefer not to paste a key? [Sign in with your browser](/mcp-server/oauth).


# Browser sign-in
Source: https://docs.stophy.dev/mcp-server/oauth

Connect Stophy to Claude Code, Codex, Cursor or OpenCode by signing in with your browser. No API key to copy, and every endpoint is open.

Run one command, then sign in with your browser. No key to copy.

### Set up Stophy MCP

Sign in with your browser. Every endpoint, billed to your account.

Choose an MCP client

**Using another MCP client?** `https://mcp.stophy.dev/mcp`
Use this URL with Streamable HTTP. Your client starts the browser sign-in.

`https://mcp.stophy.dev/mcp` is a server URL for your client, not a page to open. Your client starts the sign-in.

## What happens

1. Your client opens stophy.dev in your browser.
2. You sign in or sign up. New accounts get 1,000 free credits.
3. Stophy shows which app is asking. Approve it only if you started the connection.
4. Your client connects. Calls use your credits.

Signing out of stophy.dev disconnects the app. Your client asks you to sign in again next time.

## Check it

Ask your agent this.

```text theme={null}
Find coffee shops in Austin with a rating above 4.5 and list their websites.
```

Prefer a key? [Add an API key](/mcp-server/keyless#add-an-api-key).


# Quickstart
Source: https://docs.stophy.dev/quickstart

Make your first Stophy call with no key, then add a key to use every Stophy endpoint from TypeScript, Python, cURL or the CLI.

Make a call with no account, then add a key to get all 110 endpoints.

## Try it with no key

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

> **Response**
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "engine": "google",
>     "results": [
>       {
>         "type": "web",
>         "url": "https://bun.com/",
>         "title": "Bun — A fast all-in-one JavaScript runtime",
>         "description": "Bun is a fast JavaScript runtime & toolkit. All in one. Runtime, package manager, test runner and bundler in a single binary.",
>         "position": 1
>       }
>     ]
>   },
>   "creditsUsed": 0,
>   "requestId": "f09d5d15-c2b2-45d3-aa5e-9868563cc9c8"
> }
> ```

`data.results` is one page of Google results, and `creditsUsed` is `0`. Without a key you get the first page only. The endpoints marked `keyless: true` in the [endpoint catalog](https://api.stophy.dev/v1/endpoints) work this way.

## Get a key

Sign up at [stophy.dev/signup](https://stophy.dev/signup). You start with 1,000 free credits. Create a key and save it as `STOPHY_API_KEY`.

## Call it with your key

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.search({ query: "best project management software" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.search(query="best project management software")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best project management software"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google search "best project management software"
```

The response has the same shape and costs 1 credit. Send `page: 2` to get the next page. Every endpoint is a `POST` to `https://api.stophy.dev/v1/` and its id with dots as slashes, so `youtube.transcript` is `/v1/youtube/transcript`.

## Next

> **[Find an endpoint](/guides/find-endpoint)**
>
> Pick the right endpoint for what you need.

> **[Page through results](/guides/paging)**
>
> Get past the first page.

> **[Credits and billing](/billing)**
>
> What each call costs.

> **[Connect over MCP](/mcp-server)**
>
> Let your agent call Stophy.


# Claude Code
Source: https://docs.stophy.dev/quickstarts/claude-code

Add Stophy to Claude Code with one command. Start with no key, sign in with your browser, or use an API key to open every endpoint.

Add Stophy to [Claude Code](https://code.claude.com) with one command.

```bash theme={null}
claude mcp add --transport http stophy https://api.stophy.dev/mcp
```

Your agent can use the free endpoints right away. Run `claude mcp get stophy` to check it.

## Sign in with your browser

```bash theme={null}
claude mcp add --transport http stophy https://mcp.stophy.dev/mcp
```

Type `/mcp` in Claude Code, choose `stophy`, and pick Authenticate. This opens every endpoint.

## Use an API key

```bash theme={null}
claude mcp add --transport http stophy https://api.stophy.dev/mcp --header "Authorization: Bearer $STOPHY_API_KEY"
```

Set `STOPHY_API_KEY` first. [Get a key](https://stophy.dev/signup). Your shell fills it in, and Claude Code saves it on your machine. Add `--scope user` to use Stophy in every project.

## Try it

```text theme={null}
Use Stophy to find the top Reddit posts about Bun this week and summarize them.
```

If you see two `stophy` servers, run `claude mcp remove stophy` and add the one you want. To get one tool per endpoint for some sources, see [toolsets](/mcp-server#what-your-agent-sees).


# Claude Desktop
Source: https://docs.stophy.dev/quickstarts/claude-desktop

Add Stophy to Claude Desktop with the local MCP package. Use it with no key for free endpoints, or add an API key to open every endpoint.

Add Stophy to [Claude Desktop](https://claude.ai/download). It needs Node.js 18 or later.

Claude Desktop runs a local package that forwards calls to Stophy. Open `claude_desktop_config.json`.

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add this to `mcpServers`.

```json theme={null}
{
  "mcpServers": {
    "stophy": {
      "command": "npx",
      "args": ["-y", "@stophy/mcp"]
    }
  }
}
```

Quit Claude Desktop and open it again. Your agent can use the free endpoints right away.

## Use an API key

[Get a key](https://stophy.dev/signup) to open every endpoint. Add `env` to the same entry.

```json theme={null}
{
  "mcpServers": {
    "stophy": {
      "command": "npx",
      "args": ["-y", "@stophy/mcp"],
      "env": { "STOPHY_API_KEY": "your key" }
    }
  }
}
```

## Try it

Open a new chat and check that `stophy` lists its three tools. Then ask this.

```text theme={null}
Use Stophy to find the top Reddit posts about Bun this week and summarize them.
```

If `stophy` is missing, check the file is valid JSON and quit Claude Desktop fully. If calls say `unauthorized`, check the key has no extra spaces.


# Codex
Source: https://docs.stophy.dev/quickstarts/codex

Add Stophy to Codex with one command. Start with no key, sign in with your browser, or use an API key to open every endpoint.

Add Stophy to [Codex](https://developers.openai.com/codex) with one command.

```bash theme={null}
codex mcp add stophy --url https://api.stophy.dev/mcp
```

Your agent can use the free endpoints right away. Run `codex mcp list` to check it.

## Sign in with your browser

```bash theme={null}
codex mcp add stophy --url https://mcp.stophy.dev/mcp
codex mcp login stophy
```

This opens every endpoint.

## Use an API key

```bash theme={null}
codex mcp add stophy --url https://api.stophy.dev/mcp --bearer-token-env-var STOPHY_API_KEY
```

Set `STOPHY_API_KEY` first. [Get a key](https://stophy.dev/signup). Codex reads it each time it starts, so it is never saved to `~/.codex/config.toml`.

## Try it

```text theme={null}
Use Stophy to get the transcript of https://www.youtube.com/watch?v=dQw4w9WgXcQ and summarize it.
```

To get one tool per endpoint for some sources, see [toolsets](/mcp-server#what-your-agent-sees).


# Cursor
Source: https://docs.stophy.dev/quickstarts/cursor

Add Stophy to Cursor in one config file. Start with no key, sign in with your browser, or use an API key to open every endpoint.

Add Stophy to [Cursor](https://cursor.com). Put this in `~/.cursor/mcp.json`.

```json theme={null}
{
  "mcpServers": {
    "stophy": {
      "url": "https://api.stophy.dev/mcp"
    }
  }
}
```

Restart Cursor. Your agent can use the free endpoints right away.

## Sign in with your browser

Use this URL instead. Cursor opens your browser to sign in, and every endpoint opens.

```json theme={null}
{
  "mcpServers": {
    "stophy": {
      "url": "https://mcp.stophy.dev/mcp"
    }
  }
}
```

## Use an API key

[Get a key](https://stophy.dev/signup), then add a header. Keep the file private, since it holds your key.

```json theme={null}
{
  "mcpServers": {
    "stophy": {
      "url": "https://api.stophy.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_STOPHY_API_KEY"
      }
    }
  }
}
```

## Try it

Open the MCP section of Cursor Settings and check that `stophy` is on. Then ask the agent this.

```text theme={null}
Use Stophy to find coffee shops near Austin, TX with their ratings.
```

To get one tool per endpoint for some sources, see [toolsets](/mcp-server#what-your-agent-sees).


# Rate limits
Source: https://docs.stophy.dev/rate-limits

Stophy allows 600 requests a minute per account, lower free limits without a key, and a clear way to handle a 429.

| | Limit |
| - | - |
| Requests | 600 a minute per account |

Every call answers or fails within 25 seconds.

## Without a key

Endpoints marked `keyless: true` in the [endpoint catalog](https://api.stophy.dev/v1/endpoints) work with no key, over HTTP and [MCP](/mcp-server/keyless). Without a key you get the first page only. Free calls are limited to 10 a minute and 50 a day for each IP address, and going over returns a `429`.

[Sign up](https://stophy.dev/signup) for 1,000 free credits, higher limits and every endpoint.

## Headers

Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`.

## When you go over

| Code | Status | What to do |
| - | - | - |
| `rateLimited` | `429` | Wait for the `Retry-After` header, which is also `retryAfterSeconds` in the body, then retry. |

It is marked `retryable: true`. See [Errors and retries](/guides/errors-and-retries) for a retry loop.


# Resources for agents
Source: https://docs.stophy.dev/resources

Give your AI agent the right Stophy resource. agents.md sets up a project, llms.txt finds endpoints, and the OpenAPI document gives typed tools.

Point your agent at the file that fits its job.

| Resource | Use it to |
| - | - |
| [agents.md](https://stophy.dev/agents.md) | Add Stophy to a project, with a client, a key and a first call. |
| [llms.txt](https://stophy.dev/llms.txt) | Find the right endpoint for a task. |
| [Docs index](https://docs.stophy.dev/llms.txt) | Find a page in these docs. |
| [OpenAPI document](https://api.stophy.dev/openapi.json) | Generate a typed client, or give a model every endpoint as a tool. |
| [MCP discovery](https://stophy.dev/.well-known/mcp.json) | Read the MCP server's tools and sign-in. |
| [Endpoint catalog](https://api.stophy.dev/v1/endpoints) | List every endpoint with its inputs, price and whether it needs a key. |

Use the **Copy page** menu on any docs page to hand its content to your agent.

> **[API reference](/api-reference/introduction)**
>
> Every endpoint, with its inputs, outputs and price.


# CLI
Source: https://docs.stophy.dev/sdks/cli

Install the Stophy CLI, run your first command with no login, then log in to page through results, save output, script it and check your usage.

The `stophy` command gets web data from your terminal, your scripts and any agent that runs shell commands.

```bash theme={null}
npm install -g @stophy/cli
stophy google search "bun runtime"
```

No account, no login. You need Node.js 20 or later.

```text theme={null}
engine: google
1. Bun — A fast all-in-one JavaScript runtime
   https://bun.com/
2. oven-sh/bun: Incredibly fast JavaScript runtime, bundler ...
   https://github.com/oven-sh/bun
```

To install without Node.js, use the standalone binary.

```bash theme={null}
# macOS and Linux
curl -fsSL https://stophy.dev/install.sh | bash

# Windows (PowerShell)
irm https://stophy.dev/install.ps1 | iex
```

## Set up your agent

```bash theme={null}
npx -y @stophy/cli init --all
```

This logs you in, adds Stophy's skills to your coding agents, and adds the Stophy MCP server.

## Log in

Without a login you can run the commands marked `free` in `stophy endpoints`. To run the rest, log in with your browser.

```bash theme={null}
stophy login --browser
```

The CLI prints a code and opens stophy.dev. Check that the page shows the same code, then approve it. On a server with no browser, open the printed link on any other device. The CLI logs in once you approve there.

To use an API key instead, pass it to `login` or set it in the environment.

```bash theme={null}
stophy login --api-key st_...
export STOPHY_API_KEY="st_..."
```

`stophy logout` logs out and revokes this computer's key.

## Make a call

Name the source, then the command.

```bash theme={null}
stophy youtube search "bun runtime"
stophy reddit subreddit rust
stophy google maps search --query dentist --location Berlin
stophy youtube transcript --videoUrl https://youtu.be/M4TufsFlv_o
```

To point at one thing, use its link or its id with the matching option, like `--videoUrl` or `--videoId`. Send one, not both.

Run `stophy <source> --help` to see what a source can do, and `stophy <source> <command> --help` for every option on one command. `stophy endpoints reddit` lists the commands for a source with their cost, and `stophy describe reddit.search` shows one command's options and an example. If a value is not one the option accepts, the CLI stops before it calls Stophy and lists the values that work.

## Read the output

Lists print one row per result with its title and link. Other results print as `name: value` lines. Add `--json` for the data as JSON, with the credits used on stderr. `--raw` prints the full response, including `requestId`.

```bash theme={null}
stophy reddit search "bun runtime" --json
```

`-o <path>` writes the output to a file.

```bash theme={null}
stophy youtube search "bun runtime" --json -o results.json
```

## Page through results

When a command has more, its output ends with a `cursor`. Pass it back with `--cursor`. This needs a login.

```bash theme={null}
stophy reddit search "bun runtime" --cursor "<cursor from the last output>"
```

Commands for sites with numbered pages take `--page`, like `stophy google search "bun runtime" --page 2`. See [Page through results](/guides/paging).

## Use it in a script

A failed call exits non-zero and writes its message to stderr. The message ends with the request id, and with `Retry after Ns.` when the API says to wait. The CLI does not retry for you.

```bash theme={null}
if ! stophy reddit search "bun runtime" --json -o out.json 2>err.txt; then
  cat err.txt
  exit 1
fi
```

## Check your usage

```bash theme={null}
stophy status
stophy usage
stophy logs --days 7
```

`status` shows your login, balance and CLI version. `usage` shows your balance and all-time usage. `logs` shows your recent requests.

## Commands

| Command | What it does |
| - | - |
| `stophy init` | Log in, install the agent skills, and add the MCP server |
| `stophy login` | Log in with your browser or an API key |
| `stophy logout` | Log out and revoke this computer's key |
| `stophy <source> <command>` | Get data, for example `stophy youtube search` |
| `stophy endpoints [word]` | List every command and its cost |
| `stophy describe <id>` | Show one command's options, cost and an example |
| `stophy status` | Show your login, balance and CLI version |
| `stophy usage` | Show your balance and all-time usage |
| `stophy logs` | Show your recent requests |
| `stophy doctor` | Check your install, login and connection |
| `stophy version` | Show the CLI version |


# Overview
Source: https://docs.stophy.dev/sdks/overview

Pick a Stophy client. Use the TypeScript or Python SDK in your code, or the CLI in your terminal and for AI agents that run shell commands.

Stophy has a TypeScript SDK, a Python SDK and a CLI. Each one calls the same [API](/api-reference/introduction).

## Install

```bash TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
npm install stophy
```

```bash Python icon="python" theme={null}
pip install stophy
```

```bash CLI icon="square-terminal" theme={null}
npm install -g @stophy/cli
```

## Make a call

No account, no key.

```ts TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

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

```python Python icon="python" theme={null}
from stophy import Stophy

result = Stophy().google.search(query="bun runtime")
print(result["data"]["results"])
```

```bash CLI icon="square-terminal" theme={null}
stophy google search "bun runtime"
```

You get Google results with `creditsUsed: 0`. A key lifts the free limit.

## Pick one

> **[TypeScript](/sdks/typescript)**
>
> For Node.js, Bun, Deno and the browser. Typed inputs and results.

> **[Python](/sdks/python)**
>
> For Python apps and scripts. Sync and async clients.

> **[CLI](/sdks/cli)**
>
> For your terminal, your scripts, and agents that run shell commands.

The SDKs and the CLI read `STOPHY_API_KEY` from your environment. `npx -y @stophy/cli init --all` also adds Stophy's skills and MCP server to your coding agent. See [Quickstart](/quickstart) to get a key.


# Python SDK
Source: https://docs.stophy.dev/sdks/python

Install the Stophy Python SDK, make your first call with no key, then add a key to page through results, run async, handle errors and read your usage.

The `stophy` package gives you sync and async calls to Stophy from Python 3.9 or newer.

```bash theme={null}
pip install stophy
```

## Make a call

No account, no key.

```python theme={null}
from stophy import Stophy

result = Stophy().google.search(query="bun runtime")
print(result["data"]["results"])
```

> **Response**
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "engine": "google",
>     "results": [
>       {
>         "type": "web",
>         "url": "https://bun.com/",
>         "title": "Bun — A fast all-in-one JavaScript runtime",
>         "description": "Bun is a fast JavaScript runtime & toolkit. All in one. Runtime, package manager, test runner and bundler in a single binary. Use bun install or bun test in an ...",
>         "position": 1
>       }
>     ]
>   },
>   "creditsUsed": 0,
>   "requestId": "dd201ca1-960f-4e2c-89b9-34011c638c51"
> }
> ```

Responses are plain dictionaries with `success`, `data`, `creditsUsed` and `requestId`. A list is in `data["results"]`.

Methods follow the endpoint id, with keyword arguments in snake\_case. `google.search` is `stophy.google.search(...)`, and `reddit.search` is `stophy.reddit.search(...)`. The [API reference](/api-reference/introduction) lists every endpoint.

## Use a key

Without a key you can call the endpoints marked `keyless: true` in the catalog, and you get the first page only. Every other call raises a `StophyError` with code `unauthorized`.

Set `STOPHY_API_KEY` and `Stophy()` picks it up. Or pass it in:

```python theme={null}
import os

from stophy import Stophy

stophy = Stophy(api_key=os.environ["STOPHY_API_KEY"])
posts = stophy.reddit.search(query="bun runtime")
print(len(posts["data"]["results"]), posts["creditsUsed"])
```

## Find endpoints

```python theme={null}
from stophy import Stophy

catalog = Stophy().endpoints()
free = [endpoint for endpoint in catalog["endpoints"] if endpoint["keyless"]]
print(len(catalog["endpoints"]), len(free))
```

## Run async

`AsyncStophy` has the same methods. Await them.

```python theme={null}
import asyncio

from stophy import AsyncStophy


async def main() -> None:
    async with AsyncStophy() as stophy:
        result = await stophy.google.search(query="bun runtime")
        for item in result["data"]["results"]:
            print(item["title"])


asyncio.run(main())
```

## Page through results

A list call returns one page. When there is more, `data["cursor"]` is set. Pass it back to get the next page. This needs a key.

```python theme={null}
from stophy import Stophy

stophy = Stophy()
cursor = None
for _ in range(2):
    result = stophy.reddit.search(query="bun runtime", cursor=cursor)
    print(len(result["data"]["results"]))
    cursor = result["data"].get("cursor")
    if not cursor:
        break
```

Some endpoints take a `page` number instead, like `google.search`. See [Page through results](/guides/paging).

## Handle errors

```python theme={null}
from stophy import Stophy, StophyError

try:
    Stophy().reddit.search(query="bun runtime", cursor="next")
except StophyError as error:
    print(error.status, error.code, str(error))
    print(error.retryable, error.retry_after_seconds, error.request_id)
```

The SDK retries network errors and the statuses 429, 500, 502, 503 and 504 for you, and waits as long as the API asks. If the API asks for more than 60 seconds, it raises at once with `retry_after_seconds` set. A failed call costs nothing. See [Errors](/api-reference/errors) for every code.

## Options

```python theme={null}
from stophy import Stophy

with Stophy(
    timeout=20.0,
    max_retries=3,
    retry_initial_delay=0.5,
    headers={"x-app": "my-app"},
) as stophy:
    result = stophy.google.search(query="bun runtime")
```

| Option | Default | What it does |
| - | - | - |
| `api_key` | `STOPHY_API_KEY` | Your API key |
| `base_url` | `STOPHY_BASE_URL` or `https://api.stophy.dev` | Where requests go |
| `timeout` | `30.0` | Time limit in seconds |
| `max_retries` | `2` | Retries per request. `0` turns them off. |
| `retry_initial_delay` | `0.5` | Base delay in seconds before a retry. Each retry waits longer. |
| `headers` | none | Extra headers on every request |
| `transport` | none | An `httpx` transport, for tests |

## Check your usage

These need a key.

```python theme={null}
from stophy import Stophy

stophy = Stophy()

usage = stophy.usage()
print(usage["balanceMicros"] / 1500, usage["creditsUsed"], usage["requestCount"])

logs = stophy.logs(days=7, endpoint="reddit.search")
for entry in logs["logs"]:
    print(entry["createdAt"], entry["endpoint"], entry["credits"])
```

`balanceMicros` is your balance in millionths of a dollar. One credit is 1,500, so divide by 1,500 to get credits. See [Usage](/api-reference/usage) and [Logs](/api-reference/logs).


# TypeScript SDK
Source: https://docs.stophy.dev/sdks/typescript

Install the Stophy TypeScript SDK, make your first call with no key, then add a key to page through results, handle errors and read your usage.

The `stophy` package gives you typed calls to Stophy from Node.js, Bun, Deno and the browser.

```bash theme={null}
npm install stophy
```

## Make a call

No account, no key.

```ts theme={null}
import { Stophy } from "stophy";

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

> **Response**
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "engine": "google",
>     "results": [
>       {
>         "type": "web",
>         "url": "https://bun.com/",
>         "title": "Bun — A fast all-in-one JavaScript runtime",
>         "description": "Bun is a fast JavaScript runtime & toolkit. All in one. Runtime, package manager, test runner and bundler in a single binary. Use bun install or bun test in an ...",
>         "position": 1
>       }
>     ]
>   },
>   "creditsUsed": 0,
>   "requestId": "9532e2f9-ea3d-4ba4-8bc2-8ee5685668ee"
> }
> ```

Every response has `success`, `data`, `creditsUsed` and `requestId`. A list is in `data.results`.

Methods follow the endpoint id. `google.search` is `stophy.google.search(...)`, and `reddit.search` is `stophy.reddit.search(...)`. The inputs and results are typed, so a missing required field is a compile error. The [API reference](/api-reference/introduction) lists every endpoint.

## Use a key

Without a key you can call the endpoints marked `keyless: true` in the catalog, and you get the first page only. Every other call throws a `StophyError` with code `unauthorized`.

Set `STOPHY_API_KEY` and `new Stophy()` picks it up. Or pass it in:

```ts theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const posts = await stophy.reddit.search({ query: "bun runtime" });
console.log(posts.data.results.length, posts.creditsUsed);
```

`new Stophy("your key")` works too.

## Find endpoints

```ts theme={null}
import { Stophy } from "stophy";

const catalog = await new Stophy().endpoints();
const free = catalog.endpoints.filter((endpoint) => endpoint.keyless);
console.log(catalog.endpoints.length, free.length);
```

## Page through results

A list call returns one page. When there is more, `data.cursor` is set. Pass it back to get the next page. This needs a key.

```ts theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();
let cursor: string | undefined;
for (let page = 1; page <= 2; page++) {
  const result = await stophy.reddit.search({ query: "bun runtime", cursor });
  console.log(result.data.results.length);
  cursor = result.data.cursor;
  if (!cursor) break;
}
```

Some endpoints take a `page` number instead, like `google.search`. See [Page through results](/guides/paging).

## Handle errors

```ts theme={null}
import { Stophy, StophyError } from "stophy";

try {
  await new Stophy().reddit.search({ query: "bun runtime", cursor: "next" });
} catch (error) {
  if (error instanceof StophyError) {
    console.log(error.status, error.code, error.message);
    console.log(error.retryable, error.retryAfterSeconds, error.requestId);
  }
}
```

The SDK retries network errors and the statuses 429, 500, 502, 503 and 504 for you, and waits as long as the API asks. If the API asks for more than 60 seconds, it throws at once with `retryAfterSeconds` set. A failed call costs nothing. See [Errors](/api-reference/errors) for every code.

## Options

```ts theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({
  apiKey: process.env.STOPHY_API_KEY,
  timeoutMs: 20_000,
  maxRetries: 3,
  retryInitialDelayMs: 500,
  headers: { "x-app": "my-app" },
});

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
await stophy.google.search({ query: "bun runtime" }, { signal: controller.signal });
```

| Option | Default | What it does |
| - | - | - |
| `apiKey` | `STOPHY_API_KEY` | Your API key |
| `baseUrl` | `STOPHY_BASE_URL` or `https://api.stophy.dev` | Where requests go |
| `timeoutMs` | `30000` | Time limit for each attempt. A timed-out attempt is not retried. |
| `maxRetries` | `2` | Retries per request. `0` turns them off. |
| `retryInitialDelayMs` | `500` | Base delay before a retry. Each retry waits longer. |
| `headers` | none | Extra headers on every request |
| `fetch` | global `fetch` | Your own `fetch` |

## Check your usage

These need a key.

```ts theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();

const usage = await stophy.usage();
console.log(usage.balanceMicros / 1500, usage.creditsUsed, usage.requestCount);

const logs = await stophy.logs({ days: 7, endpoint: "reddit.search" });
for (const entry of logs.logs) {
  console.log(entry.createdAt, entry.endpoint, entry.credits);
}
```

`balanceMicros` is your balance in millionths of a dollar. One credit is 1,500, so divide by 1,500 to get credits. See [Usage](/api-reference/usage) and [Logs](/api-reference/logs).


# Ads
Source: https://docs.stophy.dev/sources/ads

Search the public ad libraries of Meta, Google, TikTok and LinkedIn. Get each ad's creative and copy, and find advertisers.

Search the public ad libraries of Meta, Google, TikTok and LinkedIn. Get each ad's creative and copy, and find advertisers. See every field in the [Ads reference](/api-reference/endpoint/meta-ads-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape ads from the Meta ad library

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.meta.ads.search({ query: "nike", platforms: ["instagram"], language: "en" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.meta.ads.search(query="nike", platforms=["instagram"], language="en")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/meta/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike","platforms":["instagram"],"language":"en"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy meta ads search nike --platforms instagram --language en
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "adId": "abc123",
        "adUrl": "https://example.com/",
        "pageId": "abc123",
        "pageName": "example",
        "pageUrl": "https://example.com/",
        "pageAvatarUrl": "https://example.com/image.jpg",
        "pageCategories": [
          "example"
        ],
        "pageLikes": 1234,
        "isActive": false,
        "firstShownAt": "2026-09-28T12:00:00.000Z",
        "lastShownAt": "2026-09-28T12:00:00.000Z",
        "platforms": [
          "example"
        ],
        "format": "example",
        "text": "A short, readable summary of the result.",
        "linkUrl": "https://example.com/",
        "linkTitle": "example",
        "linkDescription": "example",
        "ctaText": "example",
        "imageUrls": [
          "https://example.com/image.jpg"
        ],
        "videoUrls": [
          "https://example.com/"
        ],
        "cards": [
          {
            "text": "A short, readable summary of the result.",
            "linkUrl": "https://example.com/",
            "linkTitle": "example",
            "ctaText": "example",
            "imageUrl": "https://example.com/image.jpg",
            "videoUrl": "https://example.com/"
          }
        ],
        "versions": 1,
        "categories": [
          "example"
        ],
        "paidBy": "example",
        "spendMin": 1,
        "spendMax": 1,
        "spendCurrency": "example",
        "impressionsMin": 1,
        "impressionsMax": 1,
        "reachMin": 1,
        "reachMax": 1,
        "countries": [
          "example"
        ]
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "9c7a5ce1-b871-4d38-ab64-05459dfe7058"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape ads from the Meta ad library](/api-reference/endpoint/meta-ads-search) | 1 credit |
| [Scrape a Meta ad's details](/api-reference/endpoint/meta-ads-ad) | 1 credit |
| [Scrape the ads a Facebook page runs](/api-reference/endpoint/meta-ads-page) | 1 credit |
| [Scrape ads from the Google ads library](/api-reference/endpoint/google-ads-search) | 1 credit (no key needed) |
| [Scrape a Google ad's details](/api-reference/endpoint/google-ads-ad) | 1 credit |
| [Scrape advertisers from the Google ads library](/api-reference/endpoint/google-ads-advertisers) | 1 credit |
| [Scrape ads from the TikTok ad library](/api-reference/endpoint/tiktok-ads-search) | 1 credit |
| [Scrape a TikTok ad's details](/api-reference/endpoint/tiktok-ads-ad) | 1 credit |
| [Scrape ads from the LinkedIn ad library](/api-reference/endpoint/linkedin-ads-search) | 1 credit |
| [Scrape a LinkedIn ad's details](/api-reference/endpoint/linkedin-ads-ad) | 1 credit |

## More ways to call it

### Scrape ads from the Google ads library

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.search({ domain: "nike.com" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.search(domain="nike.com")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/ads/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"nike.com"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google ads search --domain nike.com
```

### Scrape advertisers from the Google ads library

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.ads.advertisers({ query: "nike" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.ads.advertisers(query="nike")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/ads/advertisers \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google ads advertisers nike
```

> [!TIP]
>
> Google ad search works without a key. Each library has a search and an ad endpoint, and Google also has an advertisers endpoint. Each search needs a keyword, an advertiser or both, except Google, which takes a domain or an advertiser. Each endpoint's reference says what it accepts.


# Apps
Source: https://docs.stophy.dev/sources/apps

Search the App Store and Google Play. Get any app's details and reviews, and the App Store top charts.

Search the App Store and Google Play. Get any app's details and reviews, and the App Store top charts. See every field in the [Apps reference](/api-reference/endpoint/appstore-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape App Store search results

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.search({ query: "notes", country: "gb", device: "ipad" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.search(query="notes", country="gb", device="ipad")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"notes","country":"gb","device":"ipad"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore search notes --country gb --device ipad
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "appId": "abc123",
        "appUrl": "https://example.com/",
        "bundleId": "abc123",
        "name": "Example title",
        "developerId": "abc123",
        "developerName": "example",
        "developerUrl": "https://example.com/",
        "seller": "example",
        "website": "https://example.com/",
        "price": 19.99,
        "priceCurrency": "example",
        "priceText": "example",
        "genres": [
          "example"
        ],
        "primaryGenreId": "abc123",
        "primaryGenre": "example",
        "contentRating": "example",
        "description": "A short, readable summary of the result.",
        "releaseNotes": "example",
        "version": "example",
        "releasedAt": "2026-09-28T12:00:00.000Z",
        "updatedAt": "2026-09-28T12:00:00.000Z",
        "minimumOsVersion": "example",
        "sizeBytes": 1,
        "languages": [
          "example"
        ],
        "rating": 4.5,
        "ratings": 4.5,
        "iconUrl": "https://example.com/",
        "screenshotUrls": [
          "https://example.com/"
        ],
        "ipadScreenshotUrls": [
          "https://example.com/"
        ]
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "d7b5c4f5-98db-434a-85df-a05b193dcbbf"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape an App Store app page](/api-reference/endpoint/appstore-app) | 1 credit |
| [Scrape App Store search results](/api-reference/endpoint/appstore-search) | From 1 credit |
| [Scrape an App Store app's reviews](/api-reference/endpoint/appstore-reviews) | 1 credit (no key needed) |
| [Scrape App Store top charts](/api-reference/endpoint/appstore-top) | From 1 credit |
| [Scrape a Google Play app page](/api-reference/endpoint/google-play-app) | 1 credit |
| [Scrape Google Play search results](/api-reference/endpoint/google-play-search) | From 1 credit |
| [Scrape a Google Play app's reviews](/api-reference/endpoint/google-play-reviews) | 1 credit (no key needed) |

## More ways to call it

### Scrape a Google Play app's reviews

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.play.reviews({ appId: "com.spotify.music" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.play.reviews(app_id="com.spotify.music")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/play/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"appId":"com.spotify.music"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google play reviews --appId com.spotify.music
```

### Scrape App Store top charts

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.appstore.top({});
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.appstore.top()
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/appstore/top \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'
```

```bash CLI icon="square-terminal" theme={null}
stophy appstore top
```

> [!TIP]
>
> App Store reviews and Google Play reviews work without a key. Pass an App Store app id or a Google Play package name from a search result into that store's other endpoints. Search and chart endpoints cost 1 credit per 10 apps, and `limit` returns fewer. Review endpoints page. See [Page through results](/guides/paging).


# Jobs
Source: https://docs.stophy.dev/sources/jobs

Search job listings on LinkedIn, Indeed, Upwork and company careers pages. Get the full posting, pay and requirements for any job.

Search job listings on LinkedIn, Indeed, Upwork and company careers pages. Get the full posting, pay and requirements for any job. See every field in the [Jobs reference](/api-reference/endpoint/linkedin-jobs-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape LinkedIn job search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.jobs.search({ query: "software engineer", location: "United States", datePosted: "pastWeek", company: ["1441", "1586"] });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.jobs.search(query="software engineer", location="United States", date_posted="pastWeek", company=["1441", "1586"])
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/jobs/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"software engineer","location":"United States","datePosted":"pastWeek","company":["1441","1586"]}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy linkedin jobs search "software engineer" --location "United States" --datePosted pastWeek --company 1441,1586
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "jobId": "abc123",
        "jobUrl": "https://example.com/",
        "title": "Example title",
        "companyName": "example",
        "companyUrl": "https://example.com/",
        "companyAvatarUrl": "https://example.com/image.jpg",
        "location": "example",
        "publishedAt": "2026-09-28T12:00:00.000Z",
        "salaryMin": 1,
        "salaryMax": 1,
        "salaryCurrency": "example",
        "salaryPeriod": "hour",
        "salaryText": "example",
        "isEasyApply": false,
        "insight": "example"
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "149e9e5f-1f26-4ceb-a616-7b1483fc8c77"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape LinkedIn job search results](/api-reference/endpoint/linkedin-jobs-search) | 1 credit |
| [Scrape a LinkedIn job page](/api-reference/endpoint/linkedin-jobs-job) | 1 credit |
| [Scrape Upwork job search results](/api-reference/endpoint/upwork-search) | 1 credit |
| [Scrape an Upwork job page](/api-reference/endpoint/upwork-job) | 1 credit |
| [Scrape Indeed job search results](/api-reference/endpoint/indeed-search) | 1 credit |
| [Scrape an Indeed job page](/api-reference/endpoint/indeed-job) | 1 credit |
| [Scrape a company's open jobs from its careers page](/api-reference/endpoint/careers-jobs) | 1 credit |
| [Scrape one job from a company's careers page](/api-reference/endpoint/careers-job) | 1 credit |
| [Scrape a Glassdoor company's ratings and details](/api-reference/endpoint/glassdoor-company) | 1 credit |
| [Scrape a Glassdoor company's employee reviews](/api-reference/endpoint/glassdoor-company-reviews) | 1 credit |
| [Scrape a Glassdoor company's salaries by job title](/api-reference/endpoint/glassdoor-company-salaries) | 1 credit |

## More ways to call it

### Scrape Indeed job search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.indeed.search({ query: "data analyst", location: "Chicago, IL", datePosted: "last7Days" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.indeed.search(query="data analyst", location="Chicago, IL", date_posted="last7Days")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/indeed/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"data analyst","location":"Chicago, IL","datePosted":"last7Days"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy indeed search "data analyst" --location "Chicago, IL" --datePosted last7Days
```

### Scrape Upwork job search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.upwork.search({ query: "react developer" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.upwork.search(query="react developer")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/upwork/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"react developer"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy upwork search "react developer"
```

> [!TIP]
>
> Pass the job link from a search result into that site's job endpoint to get the full posting.


# Places and travel
Source: https://docs.stophy.dev/sources/places-and-travel

Find places on Google Maps and Tripadvisor with their reviews, and search stays on Google Hotels, Airbnb and Booking.com. Search flights on Google. Filter by rating, traveler type, dates and more.

Find places on Google Maps and Tripadvisor with their reviews, and search stays on Google Hotels, Airbnb and Booking.com. Search flights on Google. Filter by rating, traveler type, dates and more. See every field in the [Places and travel reference](/api-reference/endpoint/google-maps-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape Google Maps search results

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.maps.search({ query: "coffee", location: "Austin, TX", openNow: true });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.maps.search(query="coffee", location="Austin, TX", open_now=True)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/maps/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"coffee","location":"Austin, TX","openNow":true}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google maps search --query coffee --location "Austin, TX" --openNow
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "placeId": "abc123",
        "googlePlaceId": "abc123",
        "placeUrl": "https://example.com/",
        "name": "Example title",
        "categories": [
          "example"
        ],
        "address": "example",
        "latitude": 1,
        "longitude": 1,
        "rating": 4.5,
        "reviews": 1234,
        "photos": 1,
        "phone": "example",
        "website": "https://example.com/",
        "description": "A short, readable summary of the result.",
        "hours": [
          {
            "days": "example",
            "times": [
              "example"
            ]
          }
        ],
        "hoursToday": "example",
        "openStatus": "example",
        "timezone": "example",
        "thumbnailUrl": "https://example.com/image.jpg",
        "reservationUrl": "https://example.com/",
        "attributes": [
          "example"
        ]
      }
    ],
    "page": 1
  },
  "creditsUsed": 1,
  "requestId": "c2340913-dda9-413f-abd0-401d92169587"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape Google Maps search results](/api-reference/endpoint/google-maps-search) | 1 credit (no key needed) |
| [Scrape a Google Maps place's details](/api-reference/endpoint/google-maps-place) | 1 credit |
| [Scrape a Google Maps place's reviews](/api-reference/endpoint/google-maps-reviews) | 1 credit (no key needed) |
| [Scrape Tripadvisor search results](/api-reference/endpoint/tripadvisor-search) | 1 credit |
| [Scrape a Tripadvisor place page](/api-reference/endpoint/tripadvisor-place) | 1 credit |
| [Scrape a Tripadvisor place's reviews](/api-reference/endpoint/tripadvisor-reviews) | 1 credit |
| [Scrape Google Hotels results with prices and ratings](/api-reference/endpoint/google-hotels) | 1 credit |
| [Scrape Google Flights results with prices and times](/api-reference/endpoint/google-flights) | 1 credit |
| [Scrape Airbnb search results with prices](/api-reference/endpoint/airbnb-search) | 1 credit |
| [Scrape an Airbnb listing's details, host, amenities, ratings and price](/api-reference/endpoint/airbnb-listing) | 1 credit |
| [Scrape an Airbnb listing's guest reviews](/api-reference/endpoint/airbnb-reviews) | 1 credit |
| [Scrape Booking.com search results with prices](/api-reference/endpoint/booking-search) | 1 credit |
| [Scrape a Booking.com hotel page](/api-reference/endpoint/booking-hotel) | 1 credit |
| [Scrape a Booking.com hotel's guest reviews](/api-reference/endpoint/booking-hotel-reviews) | 1 credit |
| [Scrape Yelp search results](/api-reference/endpoint/yelp-search) | 1 credit |
| [Scrape a Yelp business page](/api-reference/endpoint/yelp-business) | 1 credit |
| [Scrape a Yelp business's reviews](/api-reference/endpoint/yelp-business-reviews) | 1 credit |

## More ways to call it

### Scrape Google Hotels results with prices and ratings

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.hotels({ query: "Lisbon", checkIn: "2026-12-02" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.hotels(query="Lisbon", check_in="2026-12-02")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/hotels \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"Lisbon","checkIn":"2026-12-02"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google hotels Lisbon --checkIn 2026-12-02
```

### Scrape Google Flights results with prices and times

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.flights({ origin: "JFK", destination: "LAX", departDate: "2026-12-02" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.flights(origin="JFK", destination="LAX", depart_date="2026-12-02")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/google/flights \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"origin":"JFK","destination":"LAX","departDate":"2026-12-02"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy google flights --origin JFK --destination LAX --departDate 2026-12-02
```

> [!TIP]
>
> Google Maps search and Google Maps reviews work without a key. Pass the place id from a Google Maps search, or the place link from a Tripadvisor search, into that source's other endpoints.


# Real estate
Source: https://docs.stophy.dev/sources/real-estate

Search homes for sale, for rent and sold on Zillow with more than 20 filters. Get the price, photos and details for any listing.

Search homes for sale, for rent and sold on Zillow with more than 20 filters. Get the price, photos and details for any listing. See every field in the [Real estate reference](/api-reference/endpoint/zillow-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape Zillow search results

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.zillow.search({ location: "Austin, TX", daysOnZillow: "30Days", hasPool: true });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.zillow.search(location="Austin, TX", days_on_zillow="30Days", has_pool=True)
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/zillow/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"location":"Austin, TX","daysOnZillow":"30Days","hasPool":true}'
```

```bash CLI icon="square-terminal" theme={null}
stophy zillow search "Austin, TX" --daysOnZillow 30Days --hasPool
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "total": 1234,
    "results": [
      {
        "propertyId": "abc123",
        "propertyUrl": "https://example.com/",
        "status": "forSale",
        "statusText": "example",
        "price": 19.99,
        "priceCurrency": "USD",
        "addressFull": "example",
        "addressStreet": "example",
        "addressCity": "example",
        "addressRegion": "example",
        "addressPostalCode": "example",
        "latitude": 1,
        "longitude": 1,
        "bedrooms": 1,
        "bathrooms": 1,
        "sqft": 1,
        "homeType": "example",
        "daysOnZillow": 1,
        "lastSoldAt": "2026-09-28T12:00:00.000Z",
        "zestimate": 1,
        "rentZestimate": 1,
        "brokerName": "example",
        "imageUrl": "https://example.com/image.jpg",
        "buildingName": "example",
        "buildingMinRent": 1,
        "buildingMaxRent": 1,
        "buildingAvailableUnits": 1,
        "units": [
          {
            "bedrooms": 1,
            "price": 19.99
          }
        ]
      }
    ],
    "page": 1,
    "totalPages": 1234
  },
  "creditsUsed": 2,
  "requestId": "cb1f55c6-6eb7-4069-a0a0-9dbcce9060a7"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape Zillow search results](/api-reference/endpoint/zillow-search) | 2 credits |
| [Scrape a Zillow property page](/api-reference/endpoint/zillow-property) | 2 credits |

## More ways to call it

### Scrape a Zillow property page

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.zillow.property({ propertyUrl: "https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.zillow.property(property_url="https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/zillow/property \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"propertyUrl":"https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy zillow property --propertyUrl https://www.zillow.com/homedetails/123-Main-St-Austin-TX-78701/29383449_zpid/
```

> [!TIP]
>
> Zillow search and Zillow property cost 2 credits. Pass the property link from a search result into `zillow.property` for the full listing.


# Shopping
Source: https://docs.stophy.dev/sources/shopping

Search Amazon products and best sellers, and search TikTok Shop products, sellers and reviews. Search eBay and Facebook Marketplace, and read Trustpilot reviews.

Search Amazon products and best sellers, and search TikTok Shop products, sellers and reviews. Search eBay and Facebook Marketplace, and read Trustpilot reviews. See every field in the [Shopping reference](/api-reference/endpoint/amazon-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape Amazon search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.search({ query: "wireless earbuds" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.search(query="wireless earbuds")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"wireless earbuds"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy amazon search "wireless earbuds"
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "total": 1234,
    "results": [
      {
        "productId": "abc123",
        "productUrl": "https://example.com/",
        "title": "Example title",
        "imageUrl": "https://example.com/image.jpg",
        "price": 19.99,
        "originalPrice": 19.99,
        "priceCurrency": "example",
        "rating": 4.5,
        "reviews": 1234,
        "boughtPastMonth": 1,
        "isSponsored": false
      }
    ],
    "page": 1
  },
  "creditsUsed": 2,
  "requestId": "24e8e3de-f7b0-4e55-bdce-02fb0ffc66cb"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape Amazon search results](/api-reference/endpoint/amazon-search) | 2 credits |
| [Scrape an Amazon product page](/api-reference/endpoint/amazon-product) | 2 credits |
| [Scrape Amazon Best Sellers lists](/api-reference/endpoint/amazon-bestsellers) | 2 credits |
| [Scrape Amazon search suggestions](/api-reference/endpoint/amazon-suggest) | 1 credit |
| [Scrape TikTok Shop search results](/api-reference/endpoint/tiktok-shop-search) | 1 credit |
| [Scrape a TikTok Shop seller's products](/api-reference/endpoint/tiktok-shop-products) | 1 credit |
| [Scrape a TikTok Shop product page](/api-reference/endpoint/tiktok-shop-product) | 1 credit |
| [Scrape a TikTok Shop product's reviews](/api-reference/endpoint/tiktok-shop-reviews) | 1 credit |
| [Scrape eBay search results](/api-reference/endpoint/ebay-search) | 1 credit |
| [Scrape an eBay item page](/api-reference/endpoint/ebay-item) | 1 credit |
| [Scrape Facebook Marketplace search results](/api-reference/endpoint/facebook-marketplace-search) | 1 credit |
| [Scrape Trustpilot search results](/api-reference/endpoint/trustpilot-search) | 1 credit |
| [Scrape a Trustpilot company page](/api-reference/endpoint/trustpilot-company) | 1 credit |
| [Scrape a Trustpilot company's reviews](/api-reference/endpoint/trustpilot-company-reviews) | 1 credit |
| [Scrape an Amazon product's US reviews](/api-reference/endpoint/amazon-reviews) | 1 credit |

## More ways to call it

### Scrape an Amazon product page

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.product({ productUrl: "https://www.amazon.com/dp/B0CX23V2ZK" });
console.log(result.data);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.product(product_url="https://www.amazon.com/dp/B0CX23V2ZK")
print(result["data"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/product \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://www.amazon.com/dp/B0CX23V2ZK"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy amazon product --productUrl https://www.amazon.com/dp/B0CX23V2ZK
```

### Scrape an Amazon product's US reviews

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.amazon.reviews({ productUrl: "https://www.amazon.com/dp/B0CX23V2ZK" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.amazon.reviews(product_url="https://www.amazon.com/dp/B0CX23V2ZK")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/amazon/reviews \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"productUrl":"https://www.amazon.com/dp/B0CX23V2ZK"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy amazon reviews --productUrl https://www.amazon.com/dp/B0CX23V2ZK
```

> [!TIP]
>
> Amazon search, product and best sellers cost 2 credits. Pass the product link from an Amazon search result into `amazon.product`.


# Social
Source: https://docs.stophy.dev/sources/social

Search and read posts, profiles and comments on Reddit, Instagram, LinkedIn, Pinterest, Facebook, X and Threads. Get a LinkedIn profile, a company, or its latest posts.

Search and read posts, profiles and comments on Reddit, Instagram, LinkedIn, Pinterest, Facebook, X and Threads. Get a LinkedIn profile, a company, or its latest posts. See every field in the [Social reference](/api-reference/endpoint/reddit-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape Reddit search results

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.reddit.search({ query: "typescript" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.reddit.search(query="typescript")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/reddit/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"typescript"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy reddit search typescript
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "post",
        "postId": "abc123",
        "postUrl": "https://example.com/",
        "title": "Example title",
        "text": "A short, readable summary of the result.",
        "authorId": "abc123",
        "authorUsername": "example",
        "authorUrl": "https://example.com/",
        "subreddit": "example",
        "score": 4.5,
        "upvotePercent": 1,
        "comments": 1,
        "publishedAt": "2026-09-28T12:00:00.000Z",
        "flair": "example",
        "linkUrl": "https://example.com/",
        "thumbnailUrl": "https://example.com/image.jpg",
        "isNsfw": false,
        "isVideo": false,
        "isPinned": false,
        "imageUrls": [
          "https://example.com/image.jpg"
        ],
        "videoUrl": "https://example.com/",
        "videoHlsUrl": "https://example.com/",
        "videoDurationSeconds": 120,
        "pollOptions": [
          {
            "text": "A short, readable summary of the result.",
            "votes": 1
          }
        ],
        "pollTotalVotes": 1234,
        "pollEndsAt": "2026-09-28T12:00:00.000Z",
        "repostOfUrl": "https://example.com/"
      }
    ]
  },
  "creditsUsed": 1,
  "requestId": "d26232c4-7eb1-4b64-b5d5-e80c35be869e"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape Reddit search results](/api-reference/endpoint/reddit-search) | 1 credit (no key needed) |
| [Scrape a Reddit post and its comments](/api-reference/endpoint/reddit-post) | 1 credit |
| [Scrape a subreddit and its posts](/api-reference/endpoint/reddit-subreddit) | 1 credit |
| [Scrape a Reddit user's profile, posts and comments](/api-reference/endpoint/reddit-user) | 1 credit |
| [Scrape where else a link was shared on Reddit](/api-reference/endpoint/reddit-discussions) | 1 credit |
| [Scrape Reddit's popular or newest communities](/api-reference/endpoint/reddit-subreddits) | 1 credit |
| [Scrape an Instagram profile and its posts](/api-reference/endpoint/instagram-profile) | 2 credits |
| [Scrape an Instagram profile's reels](/api-reference/endpoint/instagram-profile-reels) | 1 credit |
| [Scrape an Instagram post or reel](/api-reference/endpoint/instagram-post) | 1 credit |
| [Scrape the comments of an Instagram post](/api-reference/endpoint/instagram-comments) | 1 credit |
| [Scrape a LinkedIn company page](/api-reference/endpoint/linkedin-company) | 1 credit |
| [Scrape a public LinkedIn profile](/api-reference/endpoint/linkedin-profile) | 2 credits |
| [Scrape a person's or company's public LinkedIn posts](/api-reference/endpoint/linkedin-posts) | 1 credit |
| [Scrape Pinterest search results](/api-reference/endpoint/pinterest-search) | 1 credit |
| [Scrape a Pinterest pin](/api-reference/endpoint/pinterest-pin) | 1 credit (no key needed) |
| [Scrape a Pinterest board and its pins](/api-reference/endpoint/pinterest-board) | 1 credit |
| [Scrape a Pinterest profile and its pins](/api-reference/endpoint/pinterest-profile) | 1 credit |
| [Scrape a public Facebook page's details](/api-reference/endpoint/facebook-page) | 1 credit |
| [Scrape a public Facebook page's posts](/api-reference/endpoint/facebook-page-posts) | 1 credit |
| [Scrape a public Facebook post, reel or video](/api-reference/endpoint/facebook-post) | 1 credit |
| [Scrape the comments of a public Facebook post](/api-reference/endpoint/facebook-post-comments) | 1 credit |
| [Scrape an X profile](/api-reference/endpoint/x-profile) | 1 credit (no key needed) |
| [Scrape an X post](/api-reference/endpoint/x-post) | 1 credit (no key needed) |
| [Scrape a Threads profile](/api-reference/endpoint/threads-profile) | 1 credit |
| [Scrape a Threads profile's posts](/api-reference/endpoint/threads-profile-posts) | 1 credit |
| [Scrape a Threads post and its replies](/api-reference/endpoint/threads-post) | 1 credit |
| [Scrape an X profile's posts](/api-reference/endpoint/x-profile-posts) | 1 credit |

## More ways to call it

### Scrape an Instagram profile and its posts

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.instagram.profile({ username: "natgeo" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.instagram.profile(username="natgeo")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/instagram/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"natgeo"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy instagram profile --username natgeo
```

### Scrape a public LinkedIn profile

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.linkedin.profile({ profileId: "satyanadella" });
console.log(result.data);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.linkedin.profile(profile_id="satyanadella")
print(result["data"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/linkedin/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"profileId":"satyanadella"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy linkedin profile --profileId satyanadella
```

> [!TIP]
>
> Reddit search, Pinterest pins, X profiles and X posts work without a key. Instagram profile and LinkedIn profile cost 2 credits. Endpoints that return a `cursor` or take a `page` give you more pages. See [Page through results](/guides/paging).


# Video
Source: https://docs.stophy.dev/sources/video

Search YouTube and TikTok, open any video, channel or playlist, and read comments. Get transcripts from YouTube, TikTok and Instagram videos.

Search YouTube and TikTok, open any video, channel or playlist, and read comments. Get transcripts from YouTube, TikTok and Instagram videos. See every field in the [Video reference](/api-reference/endpoint/youtube-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape YouTube search results

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.search({ query: "rust tutorial" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.search(query="rust tutorial")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"rust tutorial"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube search "rust tutorial"
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "video",
        "videoId": "Wc0ZJo06oAw",
        "videoUrl": "https://www.youtube.com/watch?v=Wc0ZJo06oAw",
        "title": "The Ultimate Rust Beginners Guide (2026)",
        "channelId": "UCt6XPuD8u3YjvybuT-Xnj5A",
        "channelName": "SBJake",
        "channelUrl": "https://www.youtube.com/channel/UCt6XPuD8u3YjvybuT-Xnj5A",
        "channelUsername": "SBJake",
        "durationSeconds": 422,
        "views": 545124,
        "thumbnailUrl": "https://i.ytimg.com/vi/Wc0ZJo06oAw/hqdefault.jpg",
        "isShort": false,
        "isLive": false,
        "publishedAt": "2025-09-30T13:12:21.000Z"
      },
      {
        "type": "video",
        "videoId": "BpPEoZW5IiY",
        "videoUrl": "https://www.youtube.com/watch?v=BpPEoZW5IiY",
        "title": "Learn Rust Programming - Complete Course 🦀",
        "channelId": "UC8butISFwT-Wl7EV0hUK0BQ",
        "channelName": "freeCodeCamp.org",
        "channelUrl": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
        "channelUsername": "freecodecamp",
        "durationSeconds": 50350,
        "views": 1248090,
        "thumbnailUrl": "https://i.ytimg.com/vi/BpPEoZW5IiY/hqdefault.jpg",
        "isShort": false,
        "isLive": false,
        "publishedAt": "2023-10-01T01:33:57.000Z"
      }
    ],
    "cursor": "EqIDEg1ydXN0IHR1dG9yaWFs…"
  },
  "creditsUsed": 1,
  "requestId": "2fe9dbad-fc48-4890-9751-0b24b596035b"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape YouTube search results](/api-reference/endpoint/youtube-search) | 1 credit (no key needed) |
| [Scrape YouTube search suggestions](/api-reference/endpoint/youtube-suggest) | 1 credit |
| [Scrape a YouTube video page](/api-reference/endpoint/youtube-video) | 1 credit (no key needed) |
| [Scrape a YouTube video's transcript](/api-reference/endpoint/youtube-transcript) | 1 credit (no key needed) |
| [Scrape the comments of a YouTube video](/api-reference/endpoint/youtube-comments) | 1 credit (no key needed) |
| [Scrape a YouTube channel and its videos](/api-reference/endpoint/youtube-channel) | 1 credit (no key needed) |
| [Scrape a YouTube playlist and its videos](/api-reference/endpoint/youtube-playlist) | 1 credit |
| [Scrape a YouTube community post and its comments](/api-reference/endpoint/youtube-post) | 1 credit |
| [Scrape a TikTok profile and its videos](/api-reference/endpoint/tiktok-profile) | 1 credit (no key needed) |
| [Scrape a TikTok video](/api-reference/endpoint/tiktok-video) | 1 credit |
| [Scrape a TikTok video's transcript](/api-reference/endpoint/tiktok-transcript) | From 1 credit (no key needed) |
| [Scrape TikTok videos for a hashtag](/api-reference/endpoint/tiktok-hashtag) | 1 credit |
| [Scrape a TikTok sound and its videos](/api-reference/endpoint/tiktok-sound) | 1 credit |
| [Scrape the comments of a TikTok video](/api-reference/endpoint/tiktok-comments) | 1 credit |
| [Scrape TikTok search results](/api-reference/endpoint/tiktok-search) | 1 credit |
| [Scrape an Instagram video's transcript](/api-reference/endpoint/instagram-transcript) | From 1 credit |

## More ways to call it

### Scrape a YouTube video's transcript

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.youtube.transcript({ videoUrl: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" });
console.log(result.data.text);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.youtube.transcript(video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(result["data"]["text"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/youtube/transcript \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoUrl":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy youtube transcript --videoUrl "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

### Scrape a TikTok profile and its videos

```typescript TypeScript icon="https://mintcdn.com/sirathic/7E4w9-IC4ysabjfc/images/icons/typescript.svg?fit=max&auto=format&n=7E4w9-IC4ysabjfc&q=85&s=d8272a85e64145620f1fbbfcf7932986" theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.tiktok.profile({ username: "khaby.lame" });
console.log(result.data.results);
```

```python Python icon="python" theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.tiktok.profile(username="khaby.lame")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null}
curl -X POST https://api.stophy.dev/v1/tiktok/profile \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"username":"khaby.lame"}'
```

```bash CLI icon="square-terminal" theme={null}
stophy tiktok profile --username khaby.lame
```

> [!TIP]
>
> YouTube search, video, transcript, comments and channel work without a key, and so do TikTok profiles and TikTok transcripts. A YouTube transcript costs 1 credit. TikTok and Instagram transcripts are priced by the video, so see [Credits and billing](/billing). TikTok videos over 3 minutes can't be transcribed.


# Search and AI answers
Source: https://docs.stophy.dev/sources/web

Search Google, News, Images, Scholar and Patents, and read what people search for. You get results and cited sources.

Search Google, News, Images, Scholar and Patents, and read what people search for. You get results and cited sources. See every field in the [Search and AI answers reference](/api-reference/endpoint/google-search), or try it in the [playground](https://stophy.dev/playground).

## Scrape Google Search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.search({ query: "best project management software" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.search(query="best project management software")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/google/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"best project management software"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy google search "best project management software"
```

The response:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://bun.com/",
        "title": "Bun — A fast all-in-one JavaScript runtime",
        "description": "Bun is a fast JavaScript runtime & toolkit. All in one. Runtime, package manager, test runner and bundler in a single binary. Use bun install or bun test in an ...",
        "position": 1
      },
      {
        "url": "https://github.com/oven-sh/bun",
        "title": "oven-sh/bun: Incredibly fast JavaScript runtime, bundler ...",
        "description": "At its core is the Bun runtime, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Rust and powered by JavaScriptCore ...",
        "position": 2
      }
    ]
  },
  "creditsUsed": 0,
  "requestId": "44eea069-e571-4dd8-95b4-cd56e641701a"
}
```

## Endpoints

| Endpoint | Cost |
| - | - |
| [Scrape Google Search results](/api-reference/endpoint/google-search) | From 1 credit (no key needed) |
| [Scrape Google News results and headlines](/api-reference/endpoint/google-news) | 1 credit (no key needed) |
| [Scrape Google Images results](/api-reference/endpoint/google-images) | From 1 credit (no key needed) |
| [Scrape Google Scholar search results](/api-reference/endpoint/google-scholar) | 1 credit |
| [Scrape Google Patents search results](/api-reference/endpoint/google-patents) | 1 credit (no key needed) |
| [Scrape Google search suggestions](/api-reference/endpoint/google-suggest) | 1 credit (no key needed) |
| [Scrape Google Trends related searches](/api-reference/endpoint/google-trends-related) | 1 credit |
| [Scrape what is trending on Google now](/api-reference/endpoint/google-trends-trending) | 1 credit |
| [Scrape Google Trends interest over time](/api-reference/endpoint/google-trends-interest) | 1 credit |
| [Scrape Google Trends interest by region](/api-reference/endpoint/google-trends-regions) | 1 credit |
| [Scrape web search results](/api-reference/endpoint/web-search) | From 1 credit (no key needed) |
| [Scrape news search results](/api-reference/endpoint/web-news) | From 1 credit (no key needed) |
| [Scrape image search results](/api-reference/endpoint/web-images) | From 1 credit (no key needed) |
| [Scrape any public web page as markdown, HTML, links or a screenshot](/api-reference/endpoint/web-scrape) | From 1 credit (no key needed) |
| [Turn a PDF, Word, Excel, PowerPoint or HTML file into markdown](/api-reference/endpoint/web-parse) | 1 credit (no key needed) |
| [Scrape the list of pages on a website](/api-reference/endpoint/web-map) | 1 credit (no key needed) |
| [Scrape the emails, phone numbers and social profiles a website publishes](/api-reference/endpoint/web-contacts) | 1 credit |
| [Crawl a website and scrape its pages as markdown](/api-reference/endpoint/web-crawl) | From 1 credit |
| [Crawl a website in the background](/api-reference/endpoint/web-crawl-start) | From 0 credits |
| [Check a background crawl and read the finished pages](/api-reference/endpoint/web-crawl-status) | 0 credits |
| [Stop a background crawl and keep the pages already read](/api-reference/endpoint/web-crawl-cancel) | 0 credits |
| [Scrape up to 100 pages in the background](/api-reference/endpoint/web-batch) | From 0 credits |
| [Check a batch scrape and read the finished pages](/api-reference/endpoint/web-batch-status) | 0 credits |
| [Stop a batch scrape and keep the pages already read](/api-reference/endpoint/web-batch-cancel) | 0 credits |

## More ways to call it

### Scrape Google News results and headlines

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.news({ query: "nvidia" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.news(query="nvidia")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/google/news \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nvidia"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy google news nvidia
```

### Scrape Google Scholar search results

```typescript TypeScript icon="https://mintlify.s3.us-west-1.amazonaws.com/sirathic/images/icons/typescript.svg" theme={null} theme={null} theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY });
const result = await stophy.google.scholar({ query: "malaria vaccine efficacy" });
console.log(result.data.results);
```

```python Python icon="python" theme={null} theme={null} theme={null}
from stophy import Stophy

stophy = Stophy()  # reads STOPHY_API_KEY
result = stophy.google.scholar(query="malaria vaccine efficacy")
print(result["data"]["results"])
```

```bash cURL icon="terminal" theme={null} theme={null} theme={null}
curl -X POST https://api.stophy.dev/v1/google/scholar \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"malaria vaccine efficacy"}'
```

```bash CLI icon="square-terminal" theme={null} theme={null} theme={null}
stophy google scholar "malaria vaccine efficacy"
```

> [!TIP]
>
> Google search, News, suggestions and Patents work without a key, for the first page only. Google Images costs 1 credit per 10 images. Turn on `scrapeResults` in Google search to read the top pages in the same call. Every other endpoint costs 1 credit.