CLI

Install

npm install -g @scrapecreators/cli

Or run without installing:

npx @scrapecreators/cli tiktok profile --handle charlidamelio --api-key YOUR_KEY

Quick Start

1. Get your API key at app.scrapecreators.com or sign up with GitHub below
2. Authenticate:

   scrapecreators auth login

3. Make your first request:

   scrapecreators tiktok profile --handle charlidamelio

4. Explore what's available:

   scrapecreators list

Authentication

Three ways to authenticate, in priority order:

Sign up with GitHub

New users can sign up from a terminal or AI agent without creating a password. The GitHub device flow includes 10,000 free API calls and does not require a credit card. You authorize with a short code, so you never share your GitHub password with the CLI or agent.

This flow is separate from the local gh CLI. Do not read or send a local gh auth token.

1. Start the device flow

curl -sS -X POST "https://api.scrapecreators.com/v1/github/device/code" \
  -H "content-type: application/json" \
  -d '{}'

The response includes device_code, user_code, verification_uri, interval, and expires_in. Open the verification URL and enter the short user code.

2. Poll for authorization

curl -sS -X POST "https://api.scrapecreators.com/v1/github/device/token" \
  -H "content-type: application/json" \
  -d '{"device_code":"YOUR_DEVICE_CODE"}'

Wait at least the returned interval between requests. Keep polling on authorization_pending, increase the interval on slow_down, and stop on expired_token or access_denied. A completed authorization returns an access token.

3. Get your ScrapeCreators API key

ACCESS_TOKEN="value returned by the token endpoint"
curl -sS "https://api.scrapecreators.com/v1/github/device/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

The response includes your api_key. Save it with scrapecreators auth login or set it as SCRAPECREATORS_API_KEY. Then run scrapecreators balance to verify the key.

Usage

Every API endpoint is a subcommand under its platform:

scrapecreators <platform> <action> [--params]

Examples:

# profiles
scrapecreators instagram profile --handle jane
scrapecreators tiktok profile --handle charlidamelio
scrapecreators youtube channel --handle ThePatMcAfeeShow

# content feeds
scrapecreators tiktok profile-videos --handle charlidamelio --sort-by popular
scrapecreators instagram user-posts --handle jane
scrapecreators instagram user-reels --handle jane

# single post/video
scrapecreators instagram post --url "https://www.instagram.com/reel/DOq6eV6iIgD"
scrapecreators tiktok video --url "https://www.tiktok.com/@user/video/123"

# search
scrapecreators youtube search --query "tutorials"
scrapecreators instagram reels-search --query "dogs"
scrapecreators reddit search --query "best programming languages"

Discover Endpoints

# list all platforms
scrapecreators list

# list endpoints for a specific platform
scrapecreators list tiktok

# see full help for any endpoint
scrapecreators tiktok profile --help

Interactive Mode

Run with no arguments to get a guided walkthrough:

scrapecreators

Walks you through: pick platform → pick action → fill params → execute.

Commands Reference

Run any command with --help for full usage details.

Output & Options

The CLI auto-detects whether output goes to a terminal or a pipe:

# default: compact JSON
scrapecreators tiktok profile --handle charlidamelio

# pretty-printed JSON
scrapecreators tiktok profile --handle charlidamelio --pretty

# pipe to jq
scrapecreators tiktok profile --handle charlidamelio | jq '.stats'

# table format
scrapecreators tiktok profile --handle charlidamelio --format table

# csv (full dump — all fields)
scrapecreators tiktok profile --handle charlidamelio --format csv > output.csv

# csv clean (noisy fields removed — spreadsheet-friendly)
scrapecreators tiktok profile --handle charlidamelio --format csv --clean > output.csv

# clean json (strips booleans, empty values, settings)
scrapecreators tiktok profile --handle charlidamelio --clean

# save to file, print only the file path
scrapecreators tiktok profile-videos --handle charlidamelio --output ./data.json

All status messages (spinners, warnings) go to stderr. Data goes to stdout. Safe for piping.

AI Agent Integration

The CLI is designed agent-first. All 110+ endpoints are also available as an MCP server — no CLI installation required for agents.

MCP Server

Add to your agent's MCP config manually:

{
  "mcpServers": {
    "scrapecreators": {
      "url": "https://api.scrapecreators.com/mcp",
      "headers": {
        "x-api-key": "your-key-here"
      }
    }
  }
}

Or auto-configure with the CLI:

scrapecreators agent add cursor    # writes .cursor/mcp.json
scrapecreators agent add claude    # writes ~/.claude/claude_desktop_config.json
scrapecreators agent add codex     # writes ~/.codex/mcp.json

Merges into existing config without overwriting other MCP servers. Prompts for API key if not already stored.

Agent Skill

Install the ScrapeCreators agent skill to teach agents how to pick the right endpoint, handle pagination, and manage credits:

npx skills add ScrapeCreators/social-media-research-skills

Works with Cursor, Claude Code, Codex, GitHub Copilot, Gemini CLI, Windsurf, and 40+ other agents.

Agent-Optimized Output

The default output is already compact JSON — no extra flags needed. To reduce further:

# --clean: strip booleans, empty values, settings (keeps urls and stats)
scrapecreators tiktok profile --handle x --clean

# --output: save to file, return only the path
scrapecreators tiktok profile-videos --handle x --clean --output ./data.json
# stdout: ./data.json

Structured errors for agents:

{
  "error": true,
  "code": "HTTP_401",
  "message": "...",
  "suggestion": "Run 'scrapecreators auth login'..."
}

Known Limitations

• Handles: pass without @. Use charlidamelio not @charlidamelio
• Hashtags: pass without #. Use fyp not #fyp
• Transcripts: video must be under 2 minutes