mindcase 0.2.0

Python SDK for the Mindcase Developer API

Mindcase Python SDK

Official Python SDK for the Mindcase Developer API — programmatic access to 34+ data collection agents across Instagram, LinkedIn, Amazon, YouTube, Google Maps, and more.

Installation

pip install mindcase

Quick Start

from mindcase import MindcaseClient

client = MindcaseClient("mk_live_...")

# List available agent groups
groups = client.list_groups()
# ['instagram', 'linkedin', 'amazon', 'youtube', ...]

# List agents in a group
agents = client.list_agents("instagram")

# Run an agent and wait for results
results = client.run_and_wait(
    "instagram", "profile-scraper",
    usernames=["nike", "adidas"]
)

for row in results:
    print(row["Username"], row["Followers"])

Authentication

Get your API key from the Mindcase Dashboard under Developer > API Keys.

client = MindcaseClient("mk_live_your_key_here")

Usage

Discover Agents

# List all groups
groups = client.list_groups()

# List agents in a group
agents = client.list_agents("linkedin")
for agent in agents:
    print(agent.name, agent.slug, agent.credits_per_row)

# Get agent details and parameter schema
agent = client.get_agent("linkedin", "profile-scraper")
print(agent.name)             # "LinkedIn Profile Scraper"
print(agent.required_params)  # {'profileUrls': Parameter(...)}
print(agent.credits_per_row)  # 2

Run Agents

# Run an agent — returns immediately with a Job object
job = client.run("amazon", "product-scraper", searchTerms=["laptop stand"])
print(job.job_id)   # "job_abc123"
print(job.status)   # "queued"

# Then poll for results manually
results = client.wait_for_results(job.job_id)

# Or run and wait for results in one call (polls automatically)
results = client.run_and_wait(
    "amazon", "product-scraper",
    searchTerms=["laptop stand"],
    timeout=300,          # max wait in seconds (default 300)
    poll_interval=3.0,    # seconds between polls (default 3)
)
print(f"Got {results.row_count} rows")
for row in results:
    print(row["Title"], row["Price"])

Job Management

# Check job status
job = client.get_job("job_abc123")
print(job.status)      # queued, running, completed, failed, cancelled
print(job.is_done)     # True if completed
print(job.is_running)  # True if queued or running

# Get results for a completed job
results = client.get_results("job_abc123")
print(results.columns)              # ['Title', 'Price', ...]
print(results.to_list("Title"))     # ['Laptop Stand', ...]
print(results[0])                   # first row as dict

# Cancel a running job
client.cancel_job("job_abc123")

# List your recent jobs
jobs = client.list_jobs(limit=10)
jobs = client.list_jobs(status="completed")

Check Credits

credits = client.get_credits()
print(f"{credits} credits remaining")

Error Handling

from mindcase import (
    MindcaseError,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

try:
    results = client.run_and_wait("instagram", "profile-scraper", usernames=["nike"])
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Not enough credits — top up at mindcase.co")
except RateLimitError:
    print("Too many requests — retry after 60s")
except NotFoundError:
    print("Agent not found")
except ValidationError as e:
    print(f"Bad parameters: {e.message}")
except MindcaseError as e:
    print(f"API error {e.status_code}: {e.message}")

Configuration

client = MindcaseClient(
    api_key="mk_live_...",
    base_url="https://api.mindcase.co/api/v1",  # default
    timeout=30,                                   # request timeout in seconds
)

Links

• Documentation
• Dashboard
• GitHub

License

MIT