mindcase 0.1.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["data"]:
    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")

# Get agent details and parameter schema
agent = client.get_agent("linkedin", "profile-scraper")
print(agent["parameters"])  # See required/optional params

Run Agents

# Fire and forget — returns immediately with a job ID
job = client.run("amazon", "product-scraper", searchTerms=["laptop stand"])
print(job["job_id"])

# Run and wait for results (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")

Job Management

# Check job status
job = client.get_job("job_abc123")
print(job["status"])  # queued, running, completed, failed, cancelled

# Get results for a completed job
results = client.get_results("job_abc123")

# 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