# Mindcase — Web Data API for AI Agents

> This is a skills file for AI coding agents (Claude Code, Cursor, etc.).
> Drop it into your project and the agent will know exactly how to use the
> Mindcase API to collect structured web data. No further explanation needed.

> **First — get the API key.** Every call needs the user's Mindcase API key. If
> the user hasn't given you one, **ask them for it now.** If they don't have a
> key yet, tell them: go to **https://console.mindcase.co**, sign up, copy the
> key, and paste it back here. Then use it as `Authorization: Bearer mk_live_...`
> on every request. Do not attempt calls without a key — they will return `401`.

---

## What Mindcase is

Mindcase is a **web data API**. You ask it to run a "data agent" (a scraper for
a specific platform + task, e.g. `linkedin/profiles` or `google/maps/places`),
and it returns clean, structured JSON. There are 100+ agents across LinkedIn,
Amazon, Google, Instagram, TikTok, YouTube, and 30+ other platforms.

You do NOT need to build or maintain any scrapers. You call one endpoint, poll
for results, and get rows of data.

- **API base URL:** `https://api.mindcase.co/api/v1`
- **Auth:** Bearer token — `Authorization: Bearer mk_live_...`
- **Get an API key:** https://console.mindcase.co (sign up → copy your key)
- **Billing:** pay-per-row, prepaid wallet. Each agent has a price per 1,000 rows
  (see the catalog below). Runs are charged to the wallet of the key's owner.

---

## Authentication

Every request (except the public catalog endpoints) needs the API key:

```
Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxx
```

If the key is missing or invalid → `401`. If the wallet has no balance → `402`.

---

## The core workflow (run → poll → results)

Running an agent is **asynchronous**:

1. **POST** to `/agents/{group}/{slug}/run` with `{ "params": {...} }` → returns a `job_id`.
2. **Poll GET** `/jobs/{job_id}/results` every ~2s until `status` is `completed`.
3. The completed response contains `data` — an array of result rows.

### Step 1 — start a job

```bash
curl -X POST https://api.mindcase.co/api/v1/agents/linkedin/profiles/run \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "queries": [
        "https://www.linkedin.com/in/williamhgates",
        "https://www.linkedin.com/in/satyanadella"
      ]
    }
  }'
```

Response:

```json
{ "job_id": "7f3a1c2e-...", "agent": "linkedin/profiles", "status": "queued", "created_at": "2026-06-01T..." }
```

### Step 2 — poll for results

```bash
curl https://api.mindcase.co/api/v1/jobs/7f3a1c2e-.../results \
  -H "Authorization: Bearer mk_live_..."
```

While running:

```json
{ "status": "running", "message": "Job is running. Results available when completed.", "row_count": 0 }
```

When completed:

```json
{
  "status": "completed",
  "row_count": 2,
  "data": [
    { "fullName": "Bill Gates", "headline": "...", "followers": 35000000, ... },
    { "fullName": "Satya Nadella", "headline": "...", "followers": 11000000, ... }
  ]
}
```

If the wallet ran out mid-run, you still get the rows collected so far, plus a
`notice` field explaining the balance was exhausted.

### Status values
`queued` → `running` → `completed` | `failed` | `cancelled`

### Handling failures
- **`failed`** → read the `error` field in the results response and report it to
  the user; don't blindly retry.
- **`401`** → stop and ask the user for a valid API key. Don't retry the same key.
- **`400` / "invalid input" on a search agent** → it may need a **location** (a
  city, region, or pincode). Add one and try again.
- Jobs can take 30s to a few minutes — keep polling every ~2s. A `"running"`
  response with `row_count: 0` is normal, not an error.

---

## All endpoints

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/agents` | yes | List agent groups |
| GET | `/agents/all` | no | List every agent (catalog) |
| GET | `/agents/{group}` | yes | List agents in a group |
| GET | `/agents/{group}/{slug}` | no | Agent detail + parameter schema |
| GET | `/agents/{group}/{slug}/options` | no | Allowed values for select-type params |
| POST | `/agents/{group}/{slug}/run` | yes | Start a job → returns `job_id` |
| GET | `/jobs` | yes | List your jobs |
| GET | `/jobs/{job_id}` | yes | Job status (`status`, `row_count`, timestamps) |
| DELETE | `/jobs/{job_id}` | yes | Cancel a running job |
| GET | `/jobs/{job_id}/results` | yes | Job results (`data` array when completed) |
| GET | `/balance` | yes | Remaining wallet balance (USD) |

`{slug}` may contain a slash for nested agents (e.g. `google/maps/places` →
group `google`, slug `maps/places`).

---

## Discovering an agent's parameters

Before running an agent, fetch its schema to learn the exact parameter names,
types, and which are required:

```bash
curl https://api.mindcase.co/api/v1/agents/linkedin/profiles
```

Returns (abridged):

```json
{
  "name": "LinkedIn Profile Details",
  "group": "linkedin",
  "slug": "profiles",
  "price_per_1k_usd": 3.5,
  "unit": "profiles",
  "parameters": {
    "queries": {
      "type": "array",
      "required": true,
      "name": "Profile URLs",
      "description": "LinkedIn profile URLs to fetch full details for. One per line."
    }
  },
  "output_schema": [ { "name": "Full Name", "field": "fullName", "type": "string" }, ... ],
  "sample_data": [ ... ],
  "sample_input": { "queries": ["https://www.linkedin.com/in/williamhgates", ...] }
}
```

- `parameters` — what to put in `params` when running. Types: `string`, `array`,
  `number`, `integer`, `boolean`, `date`. `required: true` means it must be set.
- `sample_input` — an example `params` payload. Use it as a guide, but **only
  send keys that appear in `parameters`**. `sample_input` sometimes carries
  extra keys the API rejects with `422 Unknown parameters` — when unsure, build
  the body from the `parameters` list (the `required: true` ones), not from
  `sample_input`.
- `output_schema` / `sample_data` — the shape of the rows you'll get back.

**Always fetch the schema before running an unfamiliar agent** — don't guess
parameter names, and don't send keys that aren't in `parameters`.

---

## Controlling row count & cost

Most agents accept a row-limit parameter — common names: `maxResults`,
`maxItems`, `limit`, `resultsLimit`, `maxReviews`, `maxPosts`, `maxPages`.
Set it to cap how many rows (and how much money) a run uses.
Cost ≈ `rows / 1000 × price_per_1k_usd`.

Check `/balance` before large runs.

---

## Errors

| Code | Meaning |
|------|---------|
| 400 | Bad request — invalid/missing params |
| 401 | Invalid or missing API key |
| 402 | Insufficient wallet balance — top up at console.mindcase.co |
| 404 | Unknown agent or job |
| 422 | Unknown parameters — you sent a key that isn't in the agent's `parameters`. Send only keys listed there (don't copy extra keys from `sample_input`). |
| 429 | Rate limit exceeded (default 60 requests/min per key) — retry after 60s |

---

## Python SDK

```bash
pip install mindcase
```

```python
from mindcase import Mindcase

client = Mindcase(api_key="mk_live_...")  # or set MINDCASE_API_KEY env var

# Runs the job and polls to completion, returning rows.
results = client.run("linkedin/profiles", params={
    "queries": ["https://www.linkedin.com/in/williamhgates"]
})
for row in results:
    print(row["fullName"], row.get("followers"))
```

## Node.js SDK

```bash
npm install mindcase
```

```js
import { Mindcase } from "mindcase";

const client = new Mindcase({ apiKey: "mk_live_..." });
const results = await client.run("google/maps/places", {
  params: { keywords: ["coffee"], location: "San Francisco, USA", maxResults: 20 },
});
console.log(results);
```

---

<!-- skills:catalog:start (auto-generated by scripts/gen-skills-catalog.mjs — do not edit by hand) -->
## Full agent catalog (100 agents)

Reference each agent by `group/slug`. Pricing is per 1,000 rows.

| Agent ID | Name | Price | What it does |
|----------|------|-------|--------------|
| `airbnb/listings` | Airbnb Listing Details | $3/1k listings | Get Airbnb listing details — price, availability, ratings, host info, amenities — from listing URLs |
| `airbnb/reviews` | Airbnb Reviews | $2/1k reviews | Extract Airbnb reviews — text, author, rating, date — from provided URLs, specifying a locale |
| `amazon/bestsellers` | Amazon Bestsellers | $2.7/1k products | Get Amazon bestseller products from category URLs, with rankings, ratings, and prices |
| `amazon/products` | Amazon Products | $2.6/1k products | Get Amazon product data — titles, pricing, reviews, ASINs, and seller info — from product or category URLs |
| `amazon/reviews` | Amazon Reviews | $2.6/1k reviews | Extract Amazon product reviews—ratings, text, verification, helpful votes—from product URLs, limiting to a set number of reviews |
| `amazon/search` | Amazon Search | $0.1/1k products | Extract Amazon product titles, prices, ratings, and images by searching with your queries |
| `amazon/sellers` | Amazon Sellers | $2.7/1k sellers | Get Amazon seller info — name, ratings, review count, store URL — from product or category URLs |
| `appstore/reviews` | App Store Reviews | $0.1/1k reviews | Extract App Store reviews – text, rating, author, and date – from app URLs |
| `blinkit/category` | Blinkit Category | $0.005/1k products | Extract Blinkit category page listings — products, prices, stock, ratings — from category URLs |
| `blinkit/products` | Blinkit Products | $1/1k products | Extract Blinkit product details — MRP, selling price, stock — from product URLs |
| `blinkit/search` | Blinkit Search | $0.003/1k products | Search Blinkit by query — listings, prices, stock, ratings, images |
| `booking/reviews` | Booking Reviews | $0.8/1k reviews | Extract Booking.com hotel reviews, ratings, stars, and reviewer details from hotel URLs |
| `builtwith/technology` | BuiltWith Technology | $2/1k domains | Get the technology stack of any website — analytics, hosting, CMS, frameworks, payment processors, ad pixels, and more |
| `ebay/sold-listings` | eBay Sold Listings | $3.5/1k listings | Get confirmed eBay sold prices and detailed listing data by keyword across 8 marketplaces |
| `etsy/search` | Etsy Products | $8/1k products | Search Etsy for products matching keywords, returning listing title, price, images, and URL |
| `facebook/ads-library` | Facebook Ads Library | $3/1k ads | Scrape Facebook/Meta Ad Library — see what ads any brand is currently running, with creative copy, CTA, and dates. |
| `facebook/marketplace` | Facebook Marketplace | $2.5/1k listings | Scrape listings from Facebook Marketplace — title, price, location, and photos — by city or category URL. |
| `facebook/pages` | Facebook Pages | $6/1k pages | Scrape public Facebook page profiles — likes, followers, intro, contact info, and page metadata. |
| `facebook/posts` | Facebook Posts | $0.18/1k posts | Scrape posts from public Facebook pages — text, engagement, reactions, and timestamps. |
| `flipkart/products` | Flipkart Products | $1/1k products | Extract Flipkart product details — title, price, ratings, images, specifications, seller info — from product URLs |
| `g2/reviews` | G2 Reviews | $3.5/1k reviews | Extract G2.com product reviews with star ratings, review text, and reviewer details from a product URL |
| `glassdoor/jobs` | Glassdoor Jobs | $0.3/1k jobs | Extract Glassdoor job listings with role, location, date, rating, and Easy Apply status from keywords |
| `glassdoor/reviews` | Glassdoor Reviews | $8/1k reviews | Extract Glassdoor employee reviews via keyword search — pros, cons, ratings, culture / comp / leadership scores |
| `google/flights` | Google Flights | $0.1/1k flights | Search Google Flights for one-way, round-trip, and multi-city flights, including prices, stops, airlines, and passenger counts |
| `google/images` | Google Images | $1.8/1k results | Extract Google Images details — URL, source, description, dimensions, and thumbnail — by providing a query and image count |
| `google/jobs` | Google Jobs | $20/1k jobs | Extract job data, application links, company information, and full job descriptions from Google Jobs by query |
| `google/maps/places` | Google Maps Places | $2/1k places | Search Google Maps places for address, rating, reviews, contact info, opening hours, and images |
| `google/maps/reverse-geocoding` | Google Reverse Geocoding | $0.8/1k addresses | Extract street addresses and location names from Google Maps using latitude/longitude coordinates |
| `google/maps/reviews` | Google Maps Reviews | $0.25/1k reviews | Extract reviews from Google Maps places — reviewer info, ratings, text, responses — using start URLs and max reviews |
| `google/news` | Google News | $4.5/1k news | Get Google News articles by search query — title, source, snippet, published date — with country and language filters |
| `google/play/reviews` | Google Play Reviews | $0.1/1k reviews | Extract Google Play reviews, including reviewer name, rating, publish date, and full text |
| `google/search` | Google Search | $1.7/1k pages | Scrape Google Search results — organic links, snippets, titles — with country/language filters and search operators |
| `google/shopping` | Google Shopping | $3.2/1k results | Extract Google Shopping product listings and details by keyword, country, language, count, and date range |
| `google/trends-daily` | Google Trending Daily | $0.8/1k trends | Pull today's trending searches from Google Trends — keywords with traffic estimates, related news, and pictures, for 40+ countries |
| `indeed/jobs` | Indeed Jobs | $0.06/1k jobs | Extract Indeed job listings by title and limit, providing job title, company name, location, and URL |
| `instagram/comments` | Instagram Comments | $1.6/1k comments | Extract Instagram comments — text, timestamps, usernames, likes, and replies — from post or reel URLs |
| `instagram/hashtag` | Instagram Hashtag | $1.8/1k results | Get Instagram posts, reels, engagement metrics, images, timestamps, and audio from a list of hashtags |
| `instagram/hashtag-analytics` | Instagram Hashtag Analytics | $1.3/1k results | Extract Instagram hashtag stats: top/recent posts, volume, posts per day, related hashtags with frequency, from input hashtags |
| `instagram/mentions` | Instagram Mentions | $1.4/1k posts | Extract Instagram tagged posts and mentions for a username, including text, hashtags, comments, images, likes, and locations |
| `instagram/posts` | Instagram Posts | $0.8/1k posts | Extract Instagram post metadata and media, including captions, hashtags, engagement, and comments, from profiles |
| `instagram/profiles` | Instagram Profiles | $1.3/1k profiles | Extract Instagram profile data, including bio, followers, website, verification, and recent posts with engagement, from usernames |
| `instagram/reels` | Instagram Reels | $0.9/1k reels | Get Instagram Reels and their metadata — caption, transcript, hashtags, engagement, duration, and video file — using a username |
| `instagram/search` | Instagram Profile Search | $1.4/1k profiles | Extract Instagram profiles, places, and hashtags from a search query, listing names, follower counts, and post details |
| `instamart/category` | Instamart Category | $0.005/1k products | Extract Instamart category page listings — products, prices, stock, ratings — from category URLs |
| `instamart/products` | Instamart Products | $1/1k products | Extract Instamart product details — MRP, selling price, stock — from product URLs |
| `instamart/search` | Instamart Search | $0.003/1k products | Search Instamart by query — listings, prices, stock, ratings, images |
| `linkedin/ads-library` | LinkedIn Ads | $1/1k ads | Extract LinkedIn ad details, ad copy, media URL, and call-to-action buttons from Ad Library URLs |
| `linkedin/company-details` | LinkedIn Companies | $2.6/1k companies | Get LinkedIn company details — name, size, website, industry, specialties — from LinkedIn URLs |
| `linkedin/company-employees` | LinkedIn Employees | $1.2/1k profiles | List LinkedIn company employees — name, role, location, seniority — from a list of company URLs |
| `linkedin/company-posts` | LinkedIn Company Posts | $1.4/1k posts | Get LinkedIn posts from a company or profile — content, media, and engagement metrics |
| `linkedin/company-search` | LinkedIn Company Search | $3.5/1k companies | Search LinkedIn for companies by keyword, industry, location, and size, returning name, profile URL, and employee count |
| `linkedin/job-detail` | LinkedIn Job Details | $4.5/1k jobs | Extract LinkedIn job details: description, company info, salary insights, application statistics, from a job ID |
| `linkedin/job-search` | LinkedIn Job Search | $0.8/1k jobs | Extract LinkedIn job details — title, company, location, URL — by specifying job titles, location, and filters |
| `linkedin/post-comments` | LinkedIn Post Comments | $1.7/1k comments | Extract LinkedIn post comments and replies, including likes and reactions, from a list of post URLs |
| `linkedin/post-reactions` | LinkedIn Post Reactions | $1.7/1k reactions | Extract reactions from LinkedIn posts and comments, providing likes and appreciations |
| `linkedin/post-search` | LinkedIn Post Search | $1.4/1k posts | Search LinkedIn posts, including author, content, and date, using configurable filters to target specific profiles or companies |
| `linkedin/profile-comments` | LinkedIn Profile Comments | $1.9/1k comments | Extract LinkedIn profile comments and their social activities like likes and reactions, requiring no input |
| `linkedin/profile-posts` | LinkedIn Profile Posts | $1.2/1k posts | Get LinkedIn profile posts — content, media, reactions, and comments — from profile URLs, specifying post count |
| `linkedin/profile-reactions` | LinkedIn Profile Reactions | $1.9/1k reactions | Monitor public LinkedIn profiles for reactions, along with full post details and social activities |
| `linkedin/profile-search` | LinkedIn People Search | $3.5/1k profiles | Find LinkedIn profiles by name, title, company, school, industry, and more — returns name, title, company, location |
| `linkedin/profiles` | LinkedIn Profile Details | $3.5/1k profiles | Extract LinkedIn profile data — work history, education, skills, contact info — from queries |
| `naukri/job` | Naukri Jobs | $2/1k jobs | Pull details for a specified number of Naukri job postings, including title, company, and experience |
| `producthunt/products` | Product Hunt | $0.07/1k products | Scrape Product Hunt launches — today's leaderboard, a specific date, or by category/topic. Includes upvotes, makers, and ranks. |
| `reddit/posts` | Reddit Posts | $2.9/1k results | Extract Reddit posts and comments — by URL (subreddit / post / user) or search keyword |
| `shopee/products` | Shopee Products | $4.5/1k products | Get Shopee product listings from keyword, category, or URL, with price, discount, seller, ratings, stock & shipping |
| `shopify/products` | Shopify Products | $0.01/1k products | Extract product data — prices, variants, images, descriptions — from any Shopify-powered store URL |
| `similarweb/traffic` | Similarweb Traffic | $8/1k websites | Pull Similarweb website analytics including traffic, rank, and audience data for domains you provide |
| `skyscanner/flights` | Skyscanner Flights | $2.3/1k flights | Compare flight prices across airlines using IATA codes and dates. Powered by Skyscanner. |
| `spotify/play-count` | Spotify Play Counts | $2.7/1k urls | Extract play counts and statistics for Spotify artists, albums, and tracks from their URLs |
| `threads/post-details` | Threads Post Details | $2.1/1k posts | Extract Threads post caption, media, engagement, author details, and all replies from post URLs |
| `threads/posts` | Threads Posts | $3.7/1k posts | Extract Threads posts and user profiles by username, hashtag, or keyword, including engagement metrics |
| `threads/profiles` | Threads Profiles | $4.7/1k profiles | Extract Threads profile details from usernames: follower count, bio, URLs, picture, and full name |
| `threads/search` | Threads Search | $4.7/1k results | Search Threads for posts and users matching a searchQuery, returning post content and user details |
| `tiktok/comments` | TikTok Comments | $0.4/1k comments | Extract TikTok comments — text, author, likes, replies — from a list of video URLs |
| `tiktok/followers` | TikTok Followers & Following | $0.9/1k followers | Extract TikTok followers and following — full profile data — from TikTok profiles |
| `tiktok/hashtag` | TikTok Hashtag | $1.9/1k videos | Extract TikTok videos from a list of hashtags — URLs, likes, plays, music, creator data |
| `tiktok/profiles` | TikTok Profiles | $0.4/1k profiles | Extract TikTok profile data — follower counts, bios, and engagement stats — from profile URLs |
| `tiktok/sound` | TikTok Sounds | $1.9/1k videos | Extract TikTok videos with their URLs, likes, country, video and music metadata, and creator data from sound URLs |
| `tiktok/trends` | TikTok Trends | $1.6/1k results | Monitor global TikTok trends, delivering top videos, posts, authors, and music data automatically |
| `tiktok/user-search` | TikTok User Search | $2.4/1k profiles | Search TikTok for users, returning profile data: name, nickname, signature, and follower count |
| `tiktok/video` | TikTok Video Details | $4.7/1k videos | Get TikTok video details from URLs: captions, music, heart count, play count, hashtags, and profile info |
| `tripadvisor/listings` | TripAdvisor Listings | $2/1k listings | Extract Tripadvisor data on hotels, restaurants, attractions, pricing, and ratings, requiring no input |
| `tripadvisor/reviews` | TripAdvisor Reviews | $0.8/1k reviews | Extract Tripadvisor reviews for specified places, with text, rating, dates, reviewer, owner responses, and place details |
| `twitter/profiles` | Twitter / X Profiles | $0.3/1k profiles | Extract Twitter user data — bio, follower count, following count, recent posts — from usernames or profile URLs |
| `twitter/tweets` | Twitter / X Posts | $0.2/1k tweets | Extract tweets from Twitter by keyword, URL, list, or profile, with content, date, and engagement metrics |
| `upwork/jobs` | Upwork Jobs | $3/1k jobs | Extract Upwork job postings with their title, description, budget, required skills, and client details |
| `walmart/products` | Walmart Products | $1/1k products | Scrape Walmart product details — price, ratings, seller, availability — from search, category, or product URLs. |
| `ycombinator/companies` | Y Combinator Companies | $5/1k companies | Extract YC startup leads, founder emails, LinkedIn profiles, and hiring data from a URL |
| `yelp/reviews` | Yelp Reviews | $0.4/1k reviews | Extract Yelp review text, rating, author, and date from a list of review URLs |
| `youtube/channel-information` | YouTube Channel Profile | $0.4/1k profiles | Extract YouTube channel profiles, subscriber counts, statistics, and geo-targeting details by query |
| `youtube/channels` | YouTube Channel Videos / Shorts / Streams | $0.4/1k videos | Extract YouTube channel data from URLs, with video lists, subscriber counts, and channel metadata |
| `youtube/comments` | YouTube Comments | $0.7/1k comments | Extract YouTube comments — text, likes, timestamps, and reply threads — from video URLs, specifying max comments |
| `youtube/email` | YouTube Channel Emails | $20/1k profiles | Extract the visible email address from a YouTube channel's public profile page using its specific URL |
| `youtube/search` | YouTube Search | $0.2/1k results | Extract YouTube search results for a query, providing video, channel, and playlist titles, links, and descriptions |
| `youtube/video-transcript` | YouTube Transcripts | $4.5/1k results | Extract a YouTube video's full transcript with timestamps, plus title, description, views, and channel info |
| `zepto/category` | Zepto Category | $0.005/1k products | Extract Zepto category page listings — products, prices, stock, ratings — from category URLs |
| `zepto/products` | Zepto Products | $1/1k products | Extract Zepto product details — MRP, selling price, stock — from product URLs |
| `zepto/search` | Zepto Search | $0.003/1k products | Search Zepto by query — listings, prices, stock, ratings, images |
| `zillow/listing` | Zillow Listing Details | $1.6/1k results | Extract Zillow property address, price, beds, baths, and square footage from a list of Zillow URLs |
| `zillow/zip-search` | Zillow ZIP Search | $1/1k results | Extract Zillow real estate property listings by ZIP code, specifying if for sale, rent, or sold |
<!-- skills:catalog:end -->

---

## Quick recipes

**Run and wait (raw HTTP, any language):**
1. `POST /agents/{id}/run` with `{ "params": {...} }` → get `job_id`
2. loop: `GET /jobs/{job_id}/results` every 2s
3. stop when `status == "completed"` → use `data`; or `failed`/`cancelled` → handle error

**Find the right agent:** `GET /agents/all`, match by platform + task in the
`group`/`slug`/`name`/`description`, then `GET /agents/{group}/{slug}` for params.

**Estimate cost:** `price_per_1k_usd × (expected_rows / 1000)`. Cap rows with the
agent's limit param. Check `GET /balance` first.

---

*Generated for Mindcase — https://mindcase.co*