SocialCrawl

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'view': {'enum': ['balance', 'transactions'], 'type': 'string', 'description': "'balance' (default) returns the current credit balance and recent-deduction summary. 'transactions' returns the itemised credit ledger — every deduction and refund keyed by request_id, which is how you confirm what a metered endpoint actually charged after its upfront hold was refunded."}, 'limit': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'transactions: page size (1-100, default 50).'}, 'cursor': {'type': 'string', 'description': "transactions: opaque keyset cursor from a previous response's next_cursor."}, 'requestId': {'type': 'string', 'description': "transactions: fetch the receipt(s) for one request id (e.g. 'req-a1b2c3d4e5f6')."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['action'], 'properties': {'name': {'type': 'string', 'maxLength': 120, 'description': 'create: human-readable label, up to 120 characters.'}, 'limit': {'type': 'integer', 'maximum': 500, 'minimum': 1, 'description': 'query_results: page size, 1-500 (default 100). It governs the coverage list too.'}, 'action': {'enum': ['create', 'get', 'delete', 'add_members', 'query', 'query_status', 'query_results', 'query_cancel', 'estimate_cost'], 'type': 'string', 'description': "Cohort operation. Lifecycle order: 'create' a cohort → 'add_members' (up to 1,000 per call, 10,000 per cohort) → 'estimate_cost' locally to size max_credits → 'query' (async, 202) → 'query_status' until it succeeds → 'query_results' (page with cursor). Also 'get' a cohort, 'query_cancel' a running query, and 'delete' a cohort with everything under it. Everything except 'query' costs 0 credits."}, 'cursor': {'type': 'string', 'description': 'query_results: pass `next_cursor` back verbatim. Keep going until it is null.'}, 'date_to': {'type': 'string', 'description': 'query: optional RFC3339 upper bound on the window.'}, 'members': {'type': 'array', 'items': {'type': 'object', 'required': ['platform', 'handle'], 'properties': {'handle': {'type': 'string', 'description': 'The public account handle — or the full profile URL for LinkedIn.'}, 'platform': {'enum': ['instagram', 'tiktok', 'youtube', 'twitter', 'threads', 'bluesky', 'truth-social', 'kwai', 'twitch', 'linkedin'], 'type': 'string', 'description': "The identity's platform. Only these ten are supported."}, 'external_id': {'type': 'string', 'description': 'Your own opaque key, echoed back on every match and coverage row so you can join to your records. Optional in the API, but without it a match cannot be tied back to anything.'}}, 'additionalProperties': False}, 'maxItems': 1000, 'description': 'add_members (or estimate_cost): up to 1,000 identities per call, 10,000 per cohort. Rows are FLAT — a member with identities on several platforms is several rows sharing one external_id, not a nested array. Re-sending an external_id updates its identity rather than adding a row, so a nightly full re-push is safe. LinkedIn takes the full profile URL, not a bare handle.'}, 'keywords': {'type': 'array', 'items': {'type': 'string'}, 'maxItems': 20, 'description': "query (required): up to 20 terms. Matching is literal and whole-word after Unicode NFKC case-folding — no stemming, fuzzy matching, or brand-alias inference. Pass 'Acme' and 'AcmeCo' separately if you want both."}, 'query_id': {'type': 'string', 'description': "Query id from 'query'. Required for query_status/query_results/query_cancel."}, 'cohort_id': {'type': 'string', 'description': "Cohort id from 'create'. Required for get/delete/add_members/query."}, 'date_from': {'type': 'string', 'description': "query (required): a full RFC3339 timestamp (e.g. '2026-08-01T00:00:00.000Z'), not a bare calendar date. It bounds how far back each crawl reaches."}, 'platforms': {'type': 'array', 'items': {'enum': ['instagram', 'tiktok', 'youtube', 'twitter', 'threads', 'bluesky', 'truth-social', 'kwai', 'twitch', 'linkedin'], 'type': 'string'}, 'description': 'query: restrict the run to a subset of the platforms present in the cohort. Omit to query them all.'}, 'max_credits': {'type': 'integer', 'maximum': 1000000, 'minimum': 1, 'description': "query (required, no default): your own safety limit. Submission fails with a 400 before any credit is held if the computed ceiling exceeds it — run action 'estimate_cost' first to size it."}, 'idempotencyKey': {'type': 'string', 'format': 'uuid', 'description': 'UUIDv4 for the write actions (create/add_members/query), which the API requires. Omit it and one is generated and echoed back — but supply your own (or reuse the echoed one) to make a retry replay the original call instead of creating a second cohort or reserving a second query.'}, 'retention_days': {'type': 'integer', 'maximum': 90, 'minimum': 7, 'description': 'create: 7-90, default 30. When it elapses the cohort and everything under it is purged. Uploading members or submitting a query renews the clock.'}, 'platform_counts': {'type': 'object', 'description': "estimate_cost: the panel's platform mix as { instagram: 4000, youtube: 1000, ... } when you want a ceiling without passing the identities themselves.", 'additionalProperties': {'type': 'integer', 'minimum': 0}}, 'max_items_per_identity': {'type': 'integer', 'maximum': 1000, 'minimum': 1, 'description': 'query (required, no default): item budget per member, 1-1,000.'}, 'max_pages_per_identity': {'type': 'integer', 'maximum': 20, 'minimum': 1, 'description': 'query (required, no default) and estimate_cost: page budget per member, 1-20. Twitter, Bluesky, Threads and Twitch serve one fixed page per identity and ignore anything above 1.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'id': {'type': 'string', 'description': "endpoint (required): the endpoint id as 'platform/resource' (e.g. 'tiktok/profile'), a path ('/v1/tiktok/profile'), or a full URL."}, 'live': {'type': 'boolean', 'description': "Set false to answer from this server's bundled catalogue instead of calling the live API. Default is live whenever an API key is configured; without a key everything except 'llms' falls back to bundled data automatically."}, 'page': {'type': 'integer', 'minimum': 1, 'description': 'Page number (default 1). Long output is paged, not truncated.'}, 'action': {'enum': ['quickstart', 'catalog', 'endpoint', 'llms', 'freshness', 'status'], 'type': 'string', 'description': "'quickstart' (default): auth, base URL, envelope, billing, the error taxonomy, limits, and a first call — GET /v1/utility/quickstart. 'catalog': the machine-readable list of every endpoint with live metered-aware prices — GET /v1/utility/endpoints. 'endpoint': one endpoint's complete usage guide, params, pricing rule, cache, paging, example response, curl, and related endpoints — GET /v1/utility/endpoint. 'llms': the agent context corpus for the whole API or one platform — GET /v1/utility/llms. 'freshness': compare the live registry against this server's bundled catalogue to see whether this MCP version is current. 'status': every platform's live circuit-breaker state — GET /v1/status, the public meta route to read before retrying a persistent 502 or 503."}, 'format': {'enum': ['markdown', 'json'], 'type': 'string', 'description': "llms: 'markdown' (default) returns the corpus text; 'json' returns a structured context object."}, 'method': {'enum': ['GET', 'POST', 'PATCH', 'DELETE'], 'type': 'string', 'description': 'catalog: filter by HTTP method. endpoint: disambiguate a resource registered under more than one method (the stateful `web` family).'}, 'search': {'type': 'string', 'description': 'catalog: case-insensitive substring filter over endpoint paths and summaries.'}, 'platform': {'type': 'string', 'description': "Scope to one platform slug (e.g. 'tiktok'). Applies to quickstart, catalog, and llms."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'page': {'type': 'integer', 'minimum': 1, 'description': "Page number for long topics (default 1). Topics longer than one response are paged rather than truncated — the footer tells you how many pages there are. 'full' and the largest platform topics span several pages."}, 'topic': {'type': 'string', 'default': 'overview', 'description': "Documentation topic: 'overview', 'full', 'authentication', 'credits', 'pricing' (per-endpoint costs), 'errors', 'idempotency', 'pagination', 'caching', 'hydration' (opt-in `include=` row joins), 'response-schema', 'limits', 'monitors', 'discovery', or a platform slug (e.g., 'tiktok', or 'web' for the scraping/browser surface)."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'page': {'type': 'integer', 'minimum': 1, 'description': 'Page number (default 1). Output longer than one response is paged, not truncated — the footer says how many pages there are and repeats your filters.'}, 'detail': {'enum': ['compact', 'full'], 'type': 'string', 'description': "'full' (default for a single platform) prints every parameter with its type, range, enum values, and couplings. 'compact' prints the summary table only — use it when searching broadly."}, 'method': {'enum': ['GET', 'POST', 'PATCH', 'DELETE'], 'type': 'string', 'description': 'Only show endpoints served with this HTTP method.'}, 'search': {'type': 'string', 'description': "Free-text search over endpoint names, summaries, descriptions, archetypes, and tags (e.g. 'transcript', 'reviews', 'followers'). Works with or without `platform` — without one it searches all platforms."}, 'maxCost': {'type': 'number', 'minimum': 0, 'description': 'Only show endpoints that cost at most this many credits per call (metered endpoints are judged by their ceiling).'}, 'platform': {'enum': ['web', 'tiktok', 'instagram', 'youtube', 'twitter', 'linkedin', 'facebook', 'reddit', 'threads', 'pinterest', 'twitch', 'snapchat', 'truthsocial', 'telegram', 'kick', 'kwai', 'tiktokshop', 'perplexity', 'google', 'amazon', 'google_shopping', 'google_news', 'finance', 'google_trends', 'trustpilot', 'g2', 'google_play', 'app_store', 'tripadvisor', 'walmart', 'target', 'wayfair', 'home_depot', 'ebay', 'etsy', 'sephora', 'aliexpress', 'hm', 'kohls', 'klarna', 'gumtree', 'yelp', 'utility', 'linktree', 'linkbio', 'linkme', 'komi', 'pillar', 'polymarket', 'hackernews', 'quora', 'douyin', 'github', 'tavily', 'naver', 'rumble', 'bluesky', 'spotify', 'apple_music', 'search', 'prism', 'content_analysis', 'on_page', 'jobs', 'us_congress_trades'], 'type': 'string', 'description': "Platform slug (e.g., 'tiktok', 'instagram', 'youtube'). Omit it and pass `search` to look for an endpoint across all platforms."}, 'hydrating': {'type': 'boolean', 'description': 'Only show endpoints that can fill their own rows in the same call via an `include=` row join (e.g. a search page that can carry engagement counts). Use it to find the one call that answers a question instead of a page plus one lookup per row.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['action'], 'properties': {'id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{1,64}$', 'description': 'Monitor id. Required for get/runs/timeseries/pause/resume/delete.'}, 'to': {'type': 'string', 'description': 'runs/timeseries: ISO end of the time window.'}, 'from': {'type': 'string', 'description': 'runs/timeseries: ISO start of the time window.'}, 'name': {'type': 'string', 'description': 'create: optional human-readable label.'}, 'limit': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'list/runs: page size (1-100, default 20).'}, 'action': {'enum': ['create', 'list', 'get', 'runs', 'timeseries', 'pause', 'resume', 'delete'], 'type': 'string', 'description': "Monitor operation: 'create' a scheduled monitor, 'list' your monitors, 'get' one, 'runs' for its run history, 'timeseries' for its metric series, 'pause'/'resume' it, or 'delete' it."}, 'cursor': {'type': 'string', 'description': 'list/runs: pagination cursor.'}, 'metric': {'type': 'string', 'description': 'timeseries: comma-separated metric keys to project (defaults to all stable computed keys).'}, 'params': {'type': 'object', 'description': "create: parameters passed to the recipe on every run (e.g., { keyword: 'acme' }).", 'additionalProperties': {}}, 'recipe': {'type': 'string', 'description': "create: the recipe to run each cadence — any registered endpoint or Prism composite as 'platform/resource' (e.g., 'prism/brand-mentions', 'tiktok/profile')."}, 'status': {'type': 'string', 'description': "Filter. For list: 'active' | 'paused' | 'all'. For runs: 'ok' | 'partial' | 'failed' | 'skipped'."}, 'cadence': {'type': 'string', 'description': "create: 'hourly', 'daily', 'weekly', or a cron expression (e.g., '0 9 * * 1')."}, 'include': {'enum': ['result'], 'type': 'string', 'description': "runs: set to 'result' to include each run's full stored result envelope."}, 'alert_rules': {'type': 'array', 'items': {'type': 'object', 'required': ['metric', 'op', 'value'], 'properties': {'op': {'enum': ['gt', 'lt', 'gte', 'lte', 'abs_change_gt', 'pct_change_gt', 'pct_change_lt'], 'type': 'string'}, 'value': {'type': 'number'}, 'metric': {'type': 'string'}, 'window': {'enum': ['1d', '1w'], 'type': 'string'}}, 'additionalProperties': False}, 'description': "create: optional alert rules on the recipe's computed metrics — e.g., [{ metric: 'negative_share', op: 'pct_change_gt', value: 25 }]."}, 'webhook_url': {'type': 'string', 'description': "create: HTTPS URL that receives each run's signed (HMAC-SHA256) result."}, 'output_schema': {'type': 'object', 'description': 'create: optional JSON schema to shape the delivered payload.', 'additionalProperties': {}}, 'webhook_secret': {'type': 'string', 'description': 'create: optional signing secret (8-200 chars); otherwise one is generated and returned once.'}, 'suppress_webhook_unless_alert': {'type': 'boolean', 'description': 'create: only fire the webhook when an alert rule trips (default false).'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'rows': {'type': 'integer', 'minimum': 1, 'description': "endpoint: the row cap you intend to send alongside `include` (the endpoint's own `limit`). A row join holds per row, so capping the rows caps the credits — quote it before you spend it."}, 'sort': {'enum': ['cost_asc', 'cost_desc', 'platform', 'name'], 'type': 'string', 'description': "list: sort order (default 'cost_desc' — most expensive first)."}, 'limit': {'type': 'integer', 'maximum': 200, 'minimum': 1, 'description': 'list: maximum rows to return (1-200, default 40).'}, 'model': {'enum': ['ladder', 'flat', 'metered', 'free'], 'type': 'string', 'description': "list: filter by billing model — 'ladder' (tier rate per request), 'flat' (per-endpoint override), 'metered' (query-dependent, ceiling deducted then refunded down), or 'free' (0 credits)."}, 'action': {'enum': ['overview', 'endpoint', 'platform', 'list', 'hydration'], 'type': 'string', 'description': "'overview' (default): the tier ladder, every free endpoint, every flat override, every metered band with its rule, cache TTLs, and the refund matrix. 'endpoint': one endpoint's exact price, metered rule, price-driving params, row joins, and worst case (needs platform + resource) — add `include`/`rows` for an exact quote instead of a band. 'platform': the cost table for one platform (needs platform). 'list': rank/filter endpoints by price across platforms. 'hydration': every `include=` row join in the API, what each one fills, what it costs per row and what a fully-joined page holds (optionally scoped with `platform`)."}, 'method': {'enum': ['GET', 'POST', 'PATCH', 'DELETE'], 'type': 'string', 'description': "HTTP method. Disambiguates the `web` platform, where one resource is served by several methods; also filters the 'list' action."}, 'search': {'type': 'string', 'description': 'list: free-text filter over platform, resource, summary, and archetype.'}, 'include': {'type': 'string', 'description': "endpoint: the `include=` row-join tokens you intend to send (comma-separated, e.g. 'engagement' or 'engagement,channel'). Turns the quoted band into the exact hold for that call, itemised per join. Costs nothing to ask."}, 'maxCost': {'type': 'number', 'minimum': 0, 'description': 'list: only endpoints that can cost at most this many credits (metered judged by their ceiling).'}, 'minCost': {'type': 'number', 'minimum': 0, 'description': 'list: only endpoints that cost at least this many credits (metered judged by their floor).'}, 'platform': {'enum': ['web', 'tiktok', 'instagram', 'youtube', 'twitter', 'linkedin', 'facebook', 'reddit', 'threads', 'pinterest', 'twitch', 'snapchat', 'truthsocial', 'telegram', 'kick', 'kwai', 'tiktokshop', 'perplexity', 'google', 'amazon', 'google_shopping', 'google_news', 'finance', 'google_trends', 'trustpilot', 'g2', 'google_play', 'app_store', 'tripadvisor', 'walmart', 'target', 'wayfair', 'home_depot', 'ebay', 'etsy', 'sephora', 'aliexpress', 'hm', 'kohls', 'klarna', 'gumtree', 'yelp', 'utility', 'linktree', 'linkbio', 'linkme', 'komi', 'pillar', 'polymarket', 'hackernews', 'quora', 'douyin', 'github', 'tavily', 'naver', 'rumble', 'bluesky', 'spotify', 'apple_music', 'search', 'prism', 'content_analysis', 'on_page', 'jobs', 'us_congress_trades'], 'type': 'string', 'description': "Platform slug. Required for 'endpoint' and 'platform' actions; filters the 'list' action."}, 'resource': {'type': 'string', 'description': "Resource path for the 'endpoint' action (e.g., 'profile', 'comments', 'jobs/{job_id}')."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['platform', 'resource'], 'properties': {'body': {'type': 'object', 'description': "JSON request body for POST batch endpoints (e.g. youtube/videos, prism/profiles). Put array/object params here — e.g. { ids: ['dQw4w9WgXcQ'] } or { items: [{ platform: 'tiktok', handle: '@scout2015' }] }. Ignored for GET endpoints. Use socialcrawl_list_endpoints to see which params belong in the body. For the web-scraping platform use the socialcrawl_web tool instead.", 'additionalProperties': {}}, 'params': {'type': 'object', 'description': "Query parameters as key-value pairs (e.g., { handle: 'charlidamelio' }). For GET endpoints these are the query string. For POST batch endpoints, put scalar query params here (e.g. { hl: 'en' }) and the array/object body in `body`.", 'additionalProperties': {'type': 'string'}}, 'platform': {'enum': ['web', 'tiktok', 'instagram', 'youtube', 'twitter', 'linkedin', 'facebook', 'reddit', 'threads', 'pinterest', 'twitch', 'snapchat', 'truthsocial', 'telegram', 'kick', 'kwai', 'tiktokshop', 'perplexity', 'google', 'amazon', 'google_shopping', 'google_news', 'finance', 'google_trends', 'trustpilot', 'g2', 'google_play', 'app_store', 'tripadvisor', 'walmart', 'target', 'wayfair', 'home_depot', 'ebay', 'etsy', 'sephora', 'aliexpress', 'hm', 'kohls', 'klarna', 'gumtree', 'yelp', 'utility', 'linktree', 'linkbio', 'linkme', 'komi', 'pillar', 'polymarket', 'hackernews', 'quora', 'douyin', 'github', 'tavily', 'naver', 'rumble', 'bluesky', 'spotify', 'apple_music', 'search', 'prism', 'content_analysis', 'on_page', 'jobs', 'us_congress_trades'], 'type': 'string', 'description': "Platform slug (e.g., 'tiktok', 'instagram', 'youtube')"}, 'resource': {'type': 'string', 'minLength': 1, 'description': "Resource path (e.g., 'profile', 'post/comments', 'search')"}, 'idempotencyKey': {'type': 'string', 'minLength': 16, 'description': 'Optional Idempotency-Key header. Lets you safely retry the same request — replays return the original response and deduct 0 credits (24h TTL).'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['action'], 'properties': {'id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{1,128}$', 'description': 'Job / monitor / session id. Required for *_get, *_cancel, *_delete, *_update, *_checks, *_execute, and job_errors actions. Returned by the matching *_create / *_list action.'}, 'input': {'type': 'object', 'description': "Operation parameters. For sync/GET actions these are query params (e.g. { url: 'https://example.com', formats: 'markdown,screenshot' } for scrape; { query: 'ai agents', limit: 10 } for search). For POST/PATCH actions this is the JSON body (e.g. { url, prompt, model } for agent; { url, cadence_minutes, webhook_url } for monitor_create; { code, language } for session_execute). Use socialcrawl_list_endpoints for platform 'web', or the 'web' get_docs topic, for the full per-action parameter list.", 'additionalProperties': {}}, 'action': {'enum': ['scrape', 'search', 'map', 'extract', 'crawl', 'batch_scrape', 'agent', 'job_list', 'job_get', 'job_cancel', 'job_errors', 'crawl_preview', 'monitor_create', 'monitor_list', 'monitor_get', 'monitor_update', 'monitor_delete', 'monitor_checks', 'session_create', 'session_list', 'session_get', 'session_execute', 'session_close'], 'type': 'string', 'description': "Web operation. Sync (returns data now): scrape, search, map, extract. Async jobs: crawl, batch_scrape, agent → then job_get/job_list/job_cancel to poll, and job_errors for a job's per-page failure feed. crawl_preview dry-runs a crawl's parameters for free before you pay for it. Change detection: monitor_create/list/get/update/delete/checks. Interactive browser: session_create/list/get/execute/close."}, 'idempotencyKey': {'type': 'string', 'minLength': 16, 'description': 'Optional Idempotency-Key for the async job submitters (crawl, batch_scrape). Replays return the original job and deduct 0 credits.'}}, 'additionalProperties': False}