# SocialCrawl API — Full Reference Last updated: 2026-07-17 ## Base URL: https://www.socialcrawl.dev/v1 ## Authentication Every request requires an `x-api-key` header: ``` curl https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \ -H "x-api-key: sc_your_api_key_here" ``` ## Response Format All responses follow this envelope: ```json { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile", "data": { ... }, "credits_used": 1, "credits_remaining": 4999, "request_id": "req-XXXXX", "cached": false } ``` ## Request Headers Optional headers accepted on every `/v1/*` request: - `Cache-Control: no-cache`: bypass the response cache and force a live fetch. Billed at the normal endpoint rate; the fresh result is written back so the next call is a free hit. Only the `no-cache` directive triggers it (`no-store` alone does not); matching is case-insensitive. - `Idempotency-Key: `: make the request safely retriable. Replays return the original response verbatim, cost 0 new credits, and add `X-Idempotent-Replay: true` (24h TTL). Takes precedence over `Cache-Control: no-cache`. ## Caching & Freshness Successful responses are cached and shared across your account (the key is the endpoint plus its sorted query parameters, not your API key). A cache hit costs 0 credits and returns `cached: true` / `X-Cache: HIT`; a miss is billed at the endpoint rate and returns `X-Cache: MISS`. Freshness windows by data type: profiles ~15 min, posts ~10 min, comments ~5 min, search ~2 min, analytics ~30 min. After the window expires the next call is a live miss that re-warms the entry. Send `Cache-Control: no-cache` to force a live fetch for a single call. --- ## Account — Meta Endpoints Account metadata (balance, usage). These endpoints cost 0 credits and never touch upstream platforms. ### GET /credits/balance Check your current credit balance and recent deduction count. Credit cost: 0 (metadata call) Response: ```json { "success": true, "platform": "meta", "endpoint": "/v1/credits/balance", "data": { "balance": 4999, "recent_deductions": 12 }, "credits_used": 0, "credits_remaining": 4999, "request_id": "req-XXXXX", "cached": false } ``` ``` curl "https://www.socialcrawl.dev/v1/credits/balance" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /credits/transactions List your credit ledger (dispute-grade receipts), newest first. Deductions are negative, refunds positive. Cursor-paginated (limit defaults to 50, capped at 100) and filterable by request_id. Credit cost: 0 (metadata call) Query params: limit, cursor, request_id (all optional) Response: ```json { "success": true, "platform": "meta", "endpoint": "/v1/credits/transactions", "data": { "items": [ { "id": "tx_XXXXX", "type": "deduction", "amount": -20, "balance_after": 4980, "description": "search/everywhere", "endpoint": "/v1/search/everywhere", "platform": "search", "credit_tier": "standard", "request_id": "req-XXXXX", "created_at": "2026-07-03T00:00:00.000Z" } ], "next_cursor": null }, "credits_used": 0, "credits_remaining": 4980, "request_id": "req-XXXXX", "cached": false } ``` ``` curl "https://www.socialcrawl.dev/v1/credits/transactions?limit=50" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Amazon ### GET /amazon/shop Get Amazon shop page Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Amazon shop or storefront page ``` curl "https://www.socialcrawl.dev/v1/amazon/shop?url=https://www.amazon.com/shop/sydneydelrey" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /amazon/product-search Search Amazon products by keyword Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase. - country (optional, enum: US | GB | CA | DE | FR | IT | ES | JP | IN | MX | BR | AU | NL) — Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace. - depth (optional, integer) — Maximum number of products to return (default 20, max 700). Search is a synchronous live scrape whose latency grows with depth; the 20-row default keeps keyword→ASIN resolution fast and reliable. Higher depth returns more rows at the same flat credit cost but takes longer (a timeout is auto-refunded). ``` curl "https://www.socialcrawl.dev/v1/amazon/product-search?query=wireless earbuds" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /amazon/product Get an Amazon product by ASIN Credit cost: 5 (advanced) Parameters: - asin (required) — 10-character Amazon ASIN (the product identifier). - country (optional, enum: US | GB | CA | DE | FR | IT | ES | JP | IN | MX | BR | AU | NL) — Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace. ``` curl "https://www.socialcrawl.dev/v1/amazon/product?asin=B0FQFB8FMG" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /amazon/reviews Get Amazon product reviews Credit cost: 5 (advanced) Parameters: - asin (required) — 10-character Amazon ASIN (the product identifier). - country (optional, enum: US | GB | CA | DE | FR | IT | ES | JP | IN | MX | BR | AU | NL) — Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace. ``` curl "https://www.socialcrawl.dev/v1/amazon/reviews?asin=B0DCH8VDXF" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /amazon/sellers Get Amazon sellers and offers for a product Credit cost: 1 (standard) Parameters: - asin (required) — 10-character Amazon ASIN (the product identifier). - country (optional, enum: US | GB | CA | DE | FR | IT | ES | JP | IN | MX | BR | AU | NL) — Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace. ``` curl "https://www.socialcrawl.dev/v1/amazon/sellers?asin=B09SM24S8C" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## App_store ### GET /app_store/app-search Search Apple App Store apps by keyword Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword (e.g. 'photo editor'). - country (optional, string) — Storefront country as a DFS location name ('United States') or numeric location code ('2840'). Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of results to retrieve (default 100, rounded up to multiples of 100, max 300). ``` curl "https://www.socialcrawl.dev/v1/app_store/app-search?query=photo editor" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/search-suggestions Get Apple App Store search suggestions Credit cost: 1 (standard) Parameters: - query (required) — Partial search keyword to autocomplete (e.g. 'reverse'). - country (optional, string) — ISO 3166-1 alpha-2 storefront country code. Defaults to 'us'. ``` curl "https://www.socialcrawl.dev/v1/app_store/search-suggestions?query=reverse" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/app-info Get full Apple App Store app details Credit cost: 5 (advanced) Parameters: - app_id (required) — Apple App Store numeric app id (e.g. '324684580'), from app-search. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. ``` curl "https://www.socialcrawl.dev/v1/app_store/app-info?app_id=324684580" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/app-reviews Get Apple App Store reviews for an app Credit cost: 5 (advanced) Parameters: - app_id (required) — Apple App Store numeric app id (e.g. '324684580'), from app-search. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of reviews to retrieve (default 50, batches of 50, max 600). - sort_by (optional, enum: most_recent | most_helpful) — Review ordering: `most_recent` (default) or `most_helpful`. - rating (optional, integer) — Filter to a single star rating (1–5). ``` curl "https://www.socialcrawl.dev/v1/app_store/app-reviews?app_id=324684580" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/app-list Get an Apple App Store chart Credit cost: 5 (advanced) Parameters: - app_collection (required) — Chart to retrieve: top_free_ios, top_paid_ios, top_grossing_ios, top_free_ipad, top_paid_ipad, top_grossing_ipad, new_ios, new_free_ios, new_paid_ios. - app_category (optional, enum: books | business | catalogs | education | entertainment | finance | food_and_drink | games | games_action | games_adventure | games_arcade | games_board | games_card | games_casino | games_dice | games_educational | games_family | games_music | games_puzzle | games_racing | games_role_playing | games_simulation | games_sports | games_strategy | games_trivia | games_word | health_and_fitness | lifestyle | magazines_and_newspapers | magazines_arts | magazines_automotive | magazines_weddings | magazines_business | magazines_children | magazines_computer | magazines_food | magazines_crafts | magazines_electronics | magazines_entertainment | magazines_fashion | magazines_health | magazines_history | magazines_home | magazines_literary | magazines_men | magazines_movies_and_music | magazines_politics | magazines_outdoors | magazines_family | magazines_pets | magazines_professional | magazines_regional | magazines_science | magazines_sports | magazines_teens | magazines_travel | magazines_women | medical | music | navigation | news | photo_and_video | productivity | reference | shopping | social_networking | sports | travel | utilities | weather) — Optional Apple App Store category to scope the chart (e.g. 'photo_and_video', 'games_puzzle'). - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of apps to retrieve (default 100, max 500). ``` curl "https://www.socialcrawl.dev/v1/app_store/app-list?app_collection=top_free_ios" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/app-listings-search Search the Apple App Store listings database (paginated) Credit cost: 10 (premium) Parameters: - title (required) — App title to search for (e.g. 'photo editor'). - description (optional, string) — Optional app-description text to match. - limit (optional, integer) — Apps per page (1–50, default 20). - offset (optional, integer) — Pagination offset (up to 10,000; use offset_token beyond). - offset_token (optional, string) — Opaque deep-pagination cursor from a prior response. - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. ``` curl "https://www.socialcrawl.dev/v1/app_store/app-listings-search?title=photo editor" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/categories List Apple App Store app categories Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/app_store/categories?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/locations List supported Apple App Store storefront locations Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/app_store/locations?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /app_store/languages List supported Apple App Store languages Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/app_store/languages?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Bluesky ### GET /bluesky/profile Get a Bluesky profile Credit cost: 1 (standard) Parameters: - handle (required) — Bluesky handle (e.g. `espn.com`). ``` curl "https://www.socialcrawl.dev/v1/bluesky/profile?handle=espn.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /bluesky/user/posts List a Bluesky user's posts (oneOf: handle|user_id) Credit cost: 1 (standard) Parameters: - handle (optional, string) — Bluesky handle. - user_id (optional, string) — Bluesky `did` (Bluesky's internal user ID format, e.g. `did:plc:x7d6j54pm22ufehkes6jo4jf`). - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/bluesky/user/posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /bluesky/post Get a Bluesky post Credit cost: 1 (standard) Parameters: - url (required) — Bluesky post URL. ``` curl "https://www.socialcrawl.dev/v1/bluesky/post?url=https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Content_analysis ### GET /content_analysis/search Search web citations of a keyword with per-mention sentiment Credit cost: 20 (override; tier advanced) Parameters: - keyword (required) — Brand or term to find mentions of. Wrap in escaped double-quotes for an exact phrase (e.g. "logitech mouse"). - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. Translated to a page_types filter upstream. - search_mode (optional, enum: as_is | one_per_domain) — as_is (default) returns every matching page; one_per_domain dedupes to the top page per domain. - limit (optional, integer) — Number of citations to return per page (1–100, default 10). Paginate via `cursor` for more. - cursor (optional, string) — Opaque pagination cursor — pass the `next_cursor` from the previous response to fetch the next page. - order_by (optional, string) — Sort rules as "field,direction"; separate multiple rules with ";" (e.g. content_info.sentiment_connotations.anger,desc). - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). Combined with page_type via AND when both are present. ``` curl "https://www.socialcrawl.dev/v1/content_analysis/search?keyword=openai" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/summary Aggregate mention summary for a keyword Credit cost: 20 (override; tier advanced) Parameters: - keyword (required) — Brand or term to summarize. - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. - positive_connotation_threshold (optional, string) — Minimum positive-connotation probability (0–1, default 0.4) for a mention to count as positive. - sentiments_connotation_threshold (optional, string) — Minimum sentiment-connotation probability (0–1, default 0.4) for the 6-axis emotion buckets. - internal_list_limit (optional, integer) — Cap on internal arrays such as top_domains / categories (1–20). - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). ``` curl "https://www.socialcrawl.dev/v1/content_analysis/summary?keyword=openai" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/sentiment Sentiment breakdown for a keyword Credit cost: 20 (override; tier advanced) Parameters: - keyword (required) — Brand or term to analyze. - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. - positive_connotation_threshold (optional, string) — Minimum positive-connotation probability (0–1, default 0.4). - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). ``` curl "https://www.socialcrawl.dev/v1/content_analysis/sentiment?keyword=openai" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/rating-distribution Rating histogram for a keyword Credit cost: 20 (override; tier advanced) Parameters: - keyword (required) — Product or term to build the rating histogram for. - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). ``` curl "https://www.socialcrawl.dev/v1/content_analysis/rating-distribution?keyword=iphone" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/phrase-trends Keyword mention volume + sentiment over time Credit cost: 20 (override; tier advanced) Parameters: - keyword (required) — Brand or term to trend. - date_from (required) — Start of the date range (yyyy-mm-dd). - date_to (optional, string) — End of the date range (yyyy-mm-dd); defaults to today. - date_group (optional, enum: day | week | month) — Bucket size: day, week, or month (default month). - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. - internal_list_limit (optional, integer) — Cap on internal arrays per bucket (1–20). - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). ``` curl "https://www.socialcrawl.dev/v1/content_analysis/phrase-trends?keyword=openai&date_from=2025-01-01" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/category-trends Category mention volume + sentiment over time Credit cost: 20 (override; tier advanced) Parameters: - category_code (required) — Numeric category code from the /content_analysis/categories taxonomy (e.g. 10021 = Apparel). - date_from (required) — Start of the date range (yyyy-mm-dd). - date_to (optional, string) — End of the date range (yyyy-mm-dd); defaults to today. - date_group (optional, enum: day | week | month) — Bucket size: day, week, or month (default month). - internal_list_limit (optional, integer) — Cap on internal arrays per bucket (1–20). - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array (≤8 conditions). ``` curl "https://www.socialcrawl.dev/v1/content_analysis/category-trends?category_code=10021&date_from=2025-01-01" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/languages List supported Content Analysis languages Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/content_analysis/languages?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/locations List supported Content Analysis locations Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/content_analysis/locations?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/categories List the Content Analysis category taxonomy Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/content_analysis/categories?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /content_analysis/filters List the filterable fields for Content Analysis Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/content_analysis/filters?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Facebook ### GET /facebook/profile Get Facebook page profile Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Facebook page or profile - get_business_hours (optional, string) — Get the business's hours ``` curl "https://www.socialcrawl.dev/v1/facebook/profile?url=https://www.facebook.com/Meta" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/posts List Facebook page posts (oneOf: url|pageId) Credit cost: 1 (standard) Parameters: - url (optional, string) — Full URL of the Facebook page or profile to fetch posts for - pageId (optional, string) — Facebook profile page id - cursor (optional, string) — To paginate through the posts - Constraint: one of url, pageId (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/post Get Facebook post details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Facebook post - get_comments (optional, boolean) — Whether you want to get the first several comments of the post - get_transcript (optional, boolean) — Whether you want to get the transcript of the post ``` curl "https://www.socialcrawl.dev/v1/facebook/post?url=https://www.facebook.com/Meta/posts/1234567890" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/post/comments List Facebook post comments (oneOf: url|feedback_id) Credit cost: 1 (standard) Parameters: - url (optional, string) — Full URL of the Facebook post to fetch comments for - feedback_id (optional, string) — Using feedback_id (instead of url) will *really* speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post. - cursor (optional, string) — Cursor to get more comments. Get 'cursor' from previous response. - Constraint: one of url, feedback_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/post/comments?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/group/posts List Facebook group posts (oneOf: url|group_id) Credit cost: 1 (standard) Parameters: - url (optional, string) — Full URL of the Facebook group - group_id (optional, string) — The ID of the group - sort_by (optional, enum: TOP_POSTS | RECENT_ACTIVITY | CHRONOLOGICAL | CHRONOLOGICAL_LISTINGS) — How to sort the posts - Constraint: one of url, group_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/group/posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/post/transcript Get Facebook video transcript Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the Facebook video post ``` curl "https://www.socialcrawl.dev/v1/facebook/post/transcript?url=https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/photos List Facebook profile photos Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Facebook page or profile - next_page_id (optional, string) — To paginate through to the next page - cursor (optional, string) — To paginate through to the next page ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/photos?url=https://www.facebook.com/Meta" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/reels List Facebook profile reels Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Facebook page or profile - next_page_id (optional, string) — To paginate through to the next page - cursor (optional, string) — To paginate through to the next page ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/reels?url=https://www.facebook.com/Meta" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/adlibrary/ad Get Facebook Ad Library ad details (oneOf: id|url) Credit cost: 5 (advanced) Parameters: - id (optional, string) — Facebook Ad Library ad ID - url (optional, string) — Facebook Ad URL - trim (optional, boolean) — Set to true for a trimmed down version of the response - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/adlibrary/company/ads List Facebook Ad Library company ads (oneOf: pageId|companyName) Credit cost: 5 (advanced) Parameters: - pageId (optional, string) — Facebook page ID of the advertiser - companyName (optional, string) — The name of the company. Can either use this or pageId - country (optional, string) — This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. - status (optional, enum: ALL | ACTIVE | INACTIVE) — Status of the ad. Defaults to ACTIVE. - media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE) — Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme. - language (optional, string) — Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc - sort_by (optional, enum: total_impressions | relevancy_monthly_grouped) — Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. - start_date (optional, string) — Start date to search for. Format: YYYY-MM-DD - end_date (optional, string) — End date to search for. Format: YYYY-MM-DD - cursor (optional, string) — Cursor to paginate through results - trim (optional, boolean) — Set to true for a trimmed down version of the response - Constraint: one of pageId, companyName (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/company/ads?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/adlibrary/search/ads Search Facebook Ad Library Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword or phrase to find ads in the Facebook Ad Library - sort_by (optional, enum: total_impressions | relevancy_monthly_grouped) — Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. - search_type (optional, enum: keyword_unordered | keyword_exact_phrase) — If you want to search by exact phrase or not - ad_type (optional, enum: all | political_and_issue_ads) — Search for all ads or only political and issue ads - country (optional, string) — This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. - status (optional, enum: ALL | ACTIVE | INACTIVE) — Status of the ad. Defaults to ACTIVE. - media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE) — Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. - start_date (optional, string) — Impressions start date. Needs to be in YYYY-MM-DD format. - end_date (optional, string) — Impressions end date. Needs to be in YYYY-MM-DD format. - cursor (optional, string) — Cursor to paginate through results - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads?query=artificial intelligence" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/adlibrary/search/companies Search Facebook Ad Library companies Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword or phrase to find companies in the Facebook Ad Library ``` curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/companies?query=Nike" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/events List a Facebook page's events Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the public Facebook page. - cursor (optional, string) — Cursor returned by the previous response for pagination. ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/events?url=https://www.facebook.com/brickyardoldtown" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/post/comment/replies List replies to a Facebook post comment Credit cost: 1 (standard) Parameters: - feedback_id (required) — `feedback_id` from `/v1/facebook/post/comments` for the parent comment (this is NOT the comment ID). - expansion_token (required) — `expansion_token` from `/v1/facebook/post/comments` for the parent comment. - cursor (optional, string) — Cursor returned by the previous response for pagination. ``` curl "https://www.socialcrawl.dev/v1/facebook/post/comment/replies?feedback_id=ZmVlZGJhY2s6MzM3MzYxMzI5OTQ4Nzc1NV8xOTI5NTk0OTE3Njg3MTcz&expansion_token=MjoxNzc4NjM1MDM3OgF_JaMa3kMP9RIWC" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/marketplace/location/search Search Facebook Marketplace locations Credit cost: 1 (standard) Parameters: - query (required) — Location search query (city or area name). ``` curl "https://www.socialcrawl.dev/v1/facebook/marketplace/location/search?query=Los Angeles" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/marketplace/search Search Facebook Marketplace listings Credit cost: 1 (standard) Parameters: - query (required) — Search keyword (e.g., `bike`, `couch`). - lat (required) — Latitude of the search location. - lng (required) — Longitude of the search location. - radius_km (optional, integer) — Search radius in kilometers. - min_price (optional, integer) — Minimum listing price. - max_price (optional, integer) — Maximum listing price. - count (optional, integer) — Number of listings to return per page. - sort_by (optional, enum: suggested | distance_ascend | creation_time_descend | price_ascend | price_descend) — Sort order for results. - delivery_method (optional, enum: all | local_pickup | shipping) — Delivery filter — local pickup only, shipping only, or all. - condition (optional, enum: new | used_like_new | used_good | used_fair) — Filter listings by item condition. - date_listed (optional, enum: all | 1 | 7 | 30 | last_24_hours | last_7_days | last_30_days) — Filter by listing recency (relative window or numeric day count). - availability (optional, enum: available | sold | all) — Filter by listing status — `available`, `sold`, or `all`. - cursor (optional, string) — Opaque pagination cursor returned by the previous response — forward as-is. ``` curl "https://www.socialcrawl.dev/v1/facebook/marketplace/search?query=bike&lat=40.7128&lng=-74.0060" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/marketplace/item Get a Facebook Marketplace item (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Facebook Marketplace item ID (numeric). - url (optional, string) — Full URL of the Marketplace item. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/marketplace/item?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/events/search Search Facebook events by keyword Credit cost: 1 (standard) Parameters: - query (required) — Event name or keyword to search for. - cursor (optional, string) — Cursor returned by the previous response for pagination. ``` curl "https://www.socialcrawl.dev/v1/facebook/events/search?query=dogs" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/events List Facebook events for a city Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the city's Facebook Events page. - time (optional, enum: today | this_week | next_week) — Relative time window. Defaults to all time when omitted. - cursor (optional, string) — Cursor returned by the previous response for pagination. ``` curl "https://www.socialcrawl.dev/v1/facebook/events?url=https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/event/details Get details for a Facebook event (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Facebook event ID (numeric). - url (optional, string) — Full URL of the event. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/event/details?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/adlibrary/ad/transcript Get a Facebook Ad Library video ad transcript (oneOf: id|url) Credit cost: 10 (premium) Parameters: - id (optional, string) — Facebook Ad Library ad ID. - url (optional, string) — Facebook Ad Library ad URL. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad/transcript?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/full Facebook profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - url (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /facebook/profile/reels/full Facebook profile reels with exact views, likes, comments, and shares merged in, in one call. Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the Facebook page or profile - cursor (optional, string) — Cursor from a prior response's next_cursor to page deeper. - limit (optional, integer) — Return up to this many reels in one call (1–50). The endpoint pages the underlying list server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page of 10). If the walk hits the internal time budget first, the response carries `_warnings: ["walk_deadline_reached"]`, unfetched pages are refunded, and `next_cursor` resumes where it stopped. Omit for a single page. ``` curl "https://www.socialcrawl.dev/v1/facebook/profile/reels/full?url=https://www.facebook.com/Meta" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Github ### GET /github/profile Get a GitHub user profile Credit cost: 1 (standard) Parameters: - handle (required) — GitHub username — 1–39 chars, alphanumeric + non-consecutive hyphens, no leading/trailing hyphen. ``` curl "https://www.socialcrawl.dev/v1/github/profile?handle=octocat" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo Get a GitHub repository Credit cost: 1 (standard) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. ``` curl "https://www.socialcrawl.dev/v1/github/repo?url=https://github.com/octocat/Hello-World" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/profile/repos List a GitHub user's repositories Credit cost: 1 (standard) Parameters: - handle (required) — GitHub username. - type (optional, enum: all | owner | member) — Filter — `all`, `owner`, or `member`. Defaults to `owner`. - sort (optional, enum: created | updated | pushed | full_name) — Sort field — `created`, `updated`, `pushed`, or `full_name`. Defaults to `full_name`. - direction (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `asc` for full_name, `desc` otherwise. - per_page (optional, integer) — Repos per page (1–100). Defaults to 30. - page (optional, integer) — 1-indexed page number for pagination. ``` curl "https://www.socialcrawl.dev/v1/github/profile/repos?handle=octocat" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo/readme Get a repository's README Credit cost: 1 (standard) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. ``` curl "https://www.socialcrawl.dev/v1/github/repo/readme?url=https://github.com/octocat/Hello-World" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo/releases List a repository's releases Credit cost: 1 (standard) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. - per_page (optional, integer) — Releases per page (1–100). Defaults to 30. - page (optional, integer) — 1-indexed page number. ``` curl "https://www.socialcrawl.dev/v1/github/repo/releases?url=https://github.com/facebook/react" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo/issues List a repository's issues (and PRs) Credit cost: 1 (standard) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. - type (optional, enum: issue | pr | all) — Filter the unified issues+PRs list — `issue` returns only issues, `pr` returns only pull requests, `all` (default) returns both. Each item also carries `post.ext.type` (`issue`/`pull_request`). - state (optional, enum: open | closed | all) — `open`, `closed`, or `all`. Defaults to `open`. - labels (optional, string) — Comma-separated label names (e.g. `bug,help wanted`). - sort (optional, enum: created | updated | comments) — `created`, `updated`, or `comments`. Defaults to `created`. - direction (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `desc`. - since (optional, string) — Only issues updated at or after this ISO 8601 timestamp. - per_page (optional, integer) — Issues per page (1–100). Defaults to 30. - page (optional, integer) — 1-indexed page number. ``` curl "https://www.socialcrawl.dev/v1/github/repo/issues?url=https://github.com/facebook/react" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/issue Get a single issue or pull request Credit cost: 1 (standard) Parameters: - url (required) — GitHub HTML URL — `https://github.com/{owner}/{repo}/issues/{n}` or `/pull/{n}`. ``` curl "https://www.socialcrawl.dev/v1/github/issue?url=https://github.com/facebook/react/issues/27522" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/issue/comments Get comments on an issue or pull request Credit cost: 1 (standard) Parameters: - url (required) — GitHub HTML URL of the issue or PR. - since (optional, string) — Only comments updated at or after this ISO 8601 timestamp. - per_page (optional, integer) — Comments per page (1–100). Defaults to 30. - page (optional, integer) — 1-indexed page number. ``` curl "https://www.socialcrawl.dev/v1/github/issue/comments?url=https://github.com/facebook/react/issues/27522" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/search Search GitHub issues and pull requests Credit cost: 1 (standard) Parameters: - query (required) — GitHub search query (uses GitHub's qualifier syntax — see https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). - sort (optional, enum: reactions | comments | created | updated) — Sort field — `reactions`, `comments`, `created`, `updated`. Defaults to best-match relevance. - order (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `desc`. - per_page (optional, integer) — Results per page (1–100). Defaults to 30. - page (optional, integer) — 1-indexed page number. ``` curl "https://www.socialcrawl.dev/v1/github/search?query=repo:vercel/next.js is:issue is:open" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo/top-issues Top feature request and top complaint for a repository Credit cost: 5 (advanced) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. ``` curl "https://www.socialcrawl.dev/v1/github/repo/top-issues?url=https://github.com/facebook/react" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/repo/dossier Full project dossier for a repository Credit cost: 5 (advanced) Parameters: - url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`. ``` curl "https://www.socialcrawl.dev/v1/github/repo/dossier?url=https://github.com/facebook/react" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /github/user/profile-velocity User contribution velocity dossier Credit cost: 10 (premium) Parameters: - handle (required) — GitHub username. - depth (optional, enum: quick | default | deep) — `quick`, `default`, or `deep`. Defaults to `default`. Trades off upstream calls vs. dossier richness. ``` curl "https://www.socialcrawl.dev/v1/github/user/profile-velocity?handle=octocat" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google ### GET /google/search Google web search Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase - region (optional, string) — 2 letter country code, ie US, UK, CA, etc This will show results from that country - date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted - page (optional, integer) — Page number to retrieve ``` curl "https://www.socialcrawl.dev/v1/google/search?query=best restaurants in London" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/ad Get Google ad details Credit cost: 5 (advanced) Parameters: - url (required) — Ads Transparency Center CREATIVE URL — must include both the advertiser and creative segments (`…/advertiser/{AR…}/creative/{CR…}`). Get one from `/v1/google/company/ads`. ``` curl "https://www.socialcrawl.dev/v1/google/ad?url=https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/adlibrary/advertisers/search Search Google Ad Library advertisers Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword or phrase to find advertisers in the Google Ads Transparency Center. - region (optional, string) — 2-letter country code to search in. Defaults to US. ``` curl "https://www.socialcrawl.dev/v1/google/adlibrary/advertisers/search?query=lululemon" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/company/ads List Google ads by company (oneOf: domain|advertiser_id) Credit cost: 5 (advanced) Parameters: - domain (optional, string) — Company domain name to look up ads for - advertiser_id (optional, string) — The advertiser id of the company - topic (optional, enum: all | political) — The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU' - region (optional, string) — The region to search for. Defaults to anywhere - start_date (optional, string) — Start date to search for. Format: YYYY-MM-DD - end_date (optional, string) — End date to search for. Format: YYYY-MM-DD - platform (optional, enum: google_maps | google_play | google_search | google_shopping | youtube) — Google surface to filter ads by (e.g. youtube, google_search) - format (optional, enum: text | image | video) — Ad format to filter by: text, image, or video - get_ad_details (optional, string) — Set to true to get the ad details. Will cost 25 credits. - cursor (optional, string) — Cursor to paginate through results - Constraint: one of domain, advertiser_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google/company/ads?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/business/info Get a Google Business Profile (oneOf: keyword|cid|place_id) Credit cost: 1 (standard) Parameters: - keyword (optional, string) — Business name + address (e.g. 'Irving Farm New York 645 5th Ave'). Use cid/place_id when known for an exact match. - cid (optional, string) — Google customer id (cid) of the place — the most reliable identifier. - place_id (optional, string) — Google place_id of the place. - location_name (optional, string) — Geographic context as 'City,Region,Country' (default 'New York,New York,United States'). - language_name (optional, string) — Result language (default 'English'). - Constraint: one of keyword, cid, place_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google/business/info?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/business/extended-reviews Get Google extended (multi-source) reviews (oneOf: keyword|cid|place_id) Credit cost: 5 (advanced) Parameters: - keyword (optional, string) — Business name + address. Use cid/place_id for an exact match. - cid (optional, string) — Google customer id (cid) of the place. - place_id (optional, string) — Google place_id of the place. - location_name (optional, string) — Geographic context as 'City,Region,Country'. - language_name (optional, string) — Result language (default 'English'). - depth (optional, integer) — Number of reviews to return (default 20, step 20, max 1000). - Constraint: one of keyword, cid, place_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google/business/extended-reviews?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/business/updates Get Google Business Profile posts (updates) (oneOf: keyword|cid) Credit cost: 1 (standard) Parameters: - keyword (optional, string) — Business name + location (e.g. 'Toyota of Manhattan New York'). - cid (optional, string) — Google customer id (cid) of the business. - location_name (optional, string) — Geographic context as 'City,Region,Country'. - language_name (optional, string) — Result language (default 'English'). - Constraint: one of keyword, cid (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google/business/updates?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/business/questions Get Google Business Profile questions & answers (oneOf: keyword|cid|place_id) Credit cost: 5 (advanced) Parameters: - keyword (optional, string) — Business name + location (e.g. 'Starbucks Reserve Roastery New York'). - cid (optional, string) — Google customer id (cid) of the business. - place_id (optional, string) — Google place_id of the business. - location_name (optional, string) — Geographic context as 'City,Region,Country'. - language_name (optional, string) — Result language (default 'English'). - depth (optional, integer) — Number of questions to return (default 20). - Constraint: one of keyword, cid, place_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google/business/questions?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/hotels/search Search Google hotels Credit cost: 1 (standard) Parameters: - keyword (required) — Hotel search query (e.g. 'hotels in New York'). - location_name (optional, string) — Geographic context as 'City,Region,Country'. - language_name (optional, string) — Result language (default 'English'). - check_in (optional, string) — Check-in date (YYYY-MM-DD). Defaults to the next day. - check_out (optional, string) — Check-out date (YYYY-MM-DD). Defaults to one night. ``` curl "https://www.socialcrawl.dev/v1/google/hotels/search?keyword=hotels in New York" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google/hotels/info Get Google hotel detail Credit cost: 5 (advanced) Parameters: - hotel_identifier (required) — Opaque hotel id returned by GET /v1/google/hotels/search. - location_name (optional, string) — Geographic context as 'City,Region,Country'. - language_name (optional, string) — Result language (default 'English'). ``` curl "https://www.socialcrawl.dev/v1/google/hotels/info?hotel_identifier=ChkIoYjXwK-S_okHGg0vZy8xMW1fd3MzY243EAE" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google_finance ### GET /google_finance/quote Get a financial instrument quote Credit cost: 5 (advanced) Parameters: - keyword (required) — Instrument identifier: TICKER:EXCHANGE for stocks/ETFs/indices ('GOOGL:NASDAQ', '.INX:INDEXSP') or a forex/crypto pair ('EUR-USD', 'BTC-USD'). Use the `id` returned by ticker-search. - language (optional, string) — Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English. - location (optional, string) — Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US. ``` curl "https://www.socialcrawl.dev/v1/google_finance/quote?keyword=GOOGL:NASDAQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_finance/ticker-search Search financial instruments by name Credit cost: 1 (standard) Parameters: - keyword (required) — Company / instrument name to search for (e.g. 'Apple', 'Euro', 'Bitcoin'). - category (optional, enum: all | stock | index | mutual_fund | currency | futures) — Restrict to one instrument class: all (default), stock, index, mutual_fund, currency, or futures. A class with no matches returns an empty list. - language (optional, string) — Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English. - location (optional, string) — Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US. ``` curl "https://www.socialcrawl.dev/v1/google_finance/ticker-search?keyword=Apple" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_finance/markets Get a markets overview (indices + movers) Credit cost: 1 (standard) Parameters: - language (optional, string) — Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English. - location (optional, string) — Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US. ``` curl "https://www.socialcrawl.dev/v1/google_finance/markets?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google_news ### GET /google_news/search Search Google News Credit cost: 1 (standard) Parameters: - keyword (required) — Search query (e.g. 'openai'). Supports any language; pass the matching language_code. Advanced operators (site:, intitle:, cache:, …) are not supported. - depth (optional, integer) — Number of articles to retrieve (default 10, multiples of 10, max 100). No pagination beyond depth. - location_code (optional, integer) — Google location code (e.g. 2840 = United States). Use one of location_code / location_name / location_coordinate. - location_name (optional, string) — Google location name (e.g. 'South Korea'). - location_coordinate (optional, string) — GPS target as 'latitude,longitude,radius_mm' (e.g. '40.7128,-74.0060,200') for local-news radius queries. - language_code (optional, string) — Google language code (e.g. 'en', 'ko'). Default 'en'. - time_range (optional, enum: hour | day | week | month | year) — Only return articles published within this window: hour, day, week, month, or year. ``` curl "https://www.socialcrawl.dev/v1/google_news/search?keyword=openai" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google_play ### GET /google_play/app-search Search Google Play apps by keyword Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword (e.g. 'photo editor'). - country (optional, string) — Storefront country as a DFS location name ('United States') or numeric location code ('2840'). Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of results to retrieve (default 30, rounded up to multiples of 30, max 300). ``` curl "https://www.socialcrawl.dev/v1/google_play/app-search?query=photo editor" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/search-suggestions Get Google Play search suggestions Credit cost: 1 (standard) Parameters: - query (required) — Partial search keyword to autocomplete (e.g. 'reverse'). - country (optional, string) — ISO 3166-1 alpha-2 storefront country code. Defaults to 'us'. - language (optional, string) — ISO 639-1 language code. Defaults to 'en'. ``` curl "https://www.socialcrawl.dev/v1/google_play/search-suggestions?query=reverse" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/app-info Get full Google Play app details Credit cost: 5 (advanced) Parameters: - app_id (required) — Google Play package name (e.g. 'com.spotify.music'), from app-search. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. ``` curl "https://www.socialcrawl.dev/v1/google_play/app-info?app_id=com.spotify.music" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/app-reviews Get Google Play reviews for an app Credit cost: 5 (advanced) Parameters: - app_id (required) — Google Play package name (e.g. 'com.spotify.music'), from app-search. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of reviews to retrieve (default 150, batches of 150, max 600). - sort_by (optional, enum: newest | most_relevant) — Review ordering: `newest` (default) or `most_relevant`. - rating (optional, integer) — Filter to a single star rating (1–5). ``` curl "https://www.socialcrawl.dev/v1/google_play/app-reviews?app_id=com.spotify.music" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/app-list Get a Google Play store chart Credit cost: 5 (advanced) Parameters: - app_collection (required) — Chart to retrieve: topselling_free, topselling_paid, topgrossing, movers_shakers, topselling_new_free, topselling_new_paid. - app_category (optional, enum: art_and_design | auto_and_vehicles | beauty | books_and_reference | business | comics | communication | dating | education | entertainment | events | finance | food_and_drink | health_and_fitness | house_and_home | libraries_and_demo | lifestyle | maps_and_navigation | medical | music_and_audio | news_and_magazines | parenting | personalization | photography | productivity | shopping | social | sports | tools | travel_and_local | video_players | android_wear | watch_face | weather | game | game_action | game_adventure | game_arcade | game_board | game_card | game_casino | game_casual | game_educational | game_music | game_puzzle | game_racing | game_role_playing | game_simulation | game_sports | game_strategy | game_trivia | game_word | family) — Optional Google Play category to scope the chart (e.g. 'photography', 'game_puzzle'). - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. - depth (optional, integer) — Number of apps to retrieve (default 100, max 500). ``` curl "https://www.socialcrawl.dev/v1/google_play/app-list?app_collection=topselling_free" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/app-listings-search Search the Google Play listings database (paginated) Credit cost: 10 (premium) Parameters: - title (required) — App title to search for (e.g. 'photo editor'). - description (optional, string) — Optional app-description text to match. - limit (optional, integer) — Apps per page (1–50, default 20). - offset (optional, integer) — Pagination offset (up to 10,000; use offset_token beyond). - offset_token (optional, string) — Opaque deep-pagination cursor from a prior response. - filters (optional, string) — Advanced DataForSEO filter expression as a JSON array. - country (optional, string) — Storefront country as a DFS location name or numeric code. Defaults to the US. - language (optional, string) — Language code (e.g. 'en'). Defaults to 'en'. ``` curl "https://www.socialcrawl.dev/v1/google_play/app-listings-search?title=photo editor" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/categories List Google Play app categories Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/google_play/categories?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/locations List supported Google Play storefront locations Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/google_play/locations?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_play/languages List supported Google Play languages Credit cost: 1 (standard) ``` curl "https://www.socialcrawl.dev/v1/google_play/languages?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google_shopping ### GET /google_shopping/product-search Search Google Shopping products Credit cost: 5 (advanced) Parameters: - query (required) — Product search keyword (e.g. 'wireless earbuds'). - country (optional, string) — DataForSEO location name (e.g. 'United States', 'United Kingdom'). Defaults to United States. - language (optional, string) — Language code (e.g. 'en'). Defaults to en. - depth (optional, integer) — Number of product results to retrieve (default 40, max 120). More results = longer task time. - price_min (optional, string) — Minimum product price filter. - price_max (optional, string) — Maximum product price filter. - sort_by (optional, enum: review_score | price_low_to_high | price_high_to_low) — Result ordering: review_score, price_low_to_high, or price_high_to_low. ``` curl "https://www.socialcrawl.dev/v1/google_shopping/product-search?query=wireless earbuds" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_shopping/product Get Google Shopping product detail (oneOf: product_id|gid|data_docid) Credit cost: 1 (standard) Parameters: - product_id (optional, string) — Google Shopping product_id (from product-search). - gid (optional, string) — Google Shopping gid (from product-search). - data_docid (optional, string) — Google Shopping data_docid (from product-search). - country (optional, string) — DataForSEO location name. Defaults to United States. - language (optional, string) — Language code. Defaults to en. - Constraint: one of product_id, gid, data_docid (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google_shopping/product?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_shopping/reviews Get Google Shopping product reviews Credit cost: 1 (standard) Parameters: - gid (required) — Google Shopping gid of the product (from product-search). Required. - product_id (optional, string) — Google Shopping product_id (recommended for accuracy). - data_docid (optional, string) — Google Shopping data_docid (recommended for accuracy). - depth (optional, integer) — Number of reviews to retrieve (default 10, multiples of 10, max 8000). - country (optional, string) — DataForSEO location name. Defaults to United States. - language (optional, string) — Language code. Defaults to en. ``` curl "https://www.socialcrawl.dev/v1/google_shopping/reviews?gid=3591805395819257241" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_shopping/sellers Get Google Shopping sellers for a product (oneOf: product_id|gid|data_docid) Credit cost: 1 (standard) Parameters: - product_id (optional, string) — Google Shopping product_id (from product-search). - gid (optional, string) — Google Shopping gid (from product-search). - data_docid (optional, string) — Google Shopping data_docid (from product-search). - country (optional, string) — DataForSEO location name. Defaults to United States. - language (optional, string) — Language code. Defaults to en. - Constraint: one of product_id, gid, data_docid (at least one required) ``` curl "https://www.socialcrawl.dev/v1/google_shopping/sellers?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Google_trends ### GET /google_trends/explore Get Google Trends interest over time Credit cost: 5 (advanced) Parameters: - keywords (required) — 1-5 comma-separated keywords (e.g. 'reverse audio,voice changer'). With multiple keywords the 0-100 values are normalised across the set for direct comparison. - location (optional, string) — Location as a DFS name ('United States') or numeric code ('2840'). Defaults to worldwide-leaning US. - timeframe (optional, enum: past_hour | past_4_hours | past_day | past_7_days | past_30_days | past_90_days | past_12_months | past_5_years) — Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months. - category (optional, integer) — Numeric Google Trends category code to scope the query (default 0 = all categories). ``` curl "https://www.socialcrawl.dev/v1/google_trends/explore?keywords=uv index" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /google_trends/rising Get related + rising Google Trends queries Credit cost: 5 (advanced) Parameters: - keyword (required) — Single keyword to expand (e.g. 'uv index'). Google Trends returns the related-queries list for one keyword only. - location (optional, string) — Location as a DFS name ('United States') or numeric code ('2840'). Defaults to worldwide-leaning US. - timeframe (optional, enum: past_hour | past_4_hours | past_day | past_7_days | past_30_days | past_90_days | past_12_months | past_5_years) — Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months. ``` curl "https://www.socialcrawl.dev/v1/google_trends/rising?keyword=uv index" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Hackernews ### GET /hackernews/search Search Hacker News Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term. - tags (optional, string) — Algolia tag filter — comma-separated. Common values: "story", "comment", "poll", "show_hn", "ask_hn", "front_page", "author_". Defaults to "story". - numericFilters (optional, string) — Algolia numeric filter expression on `created_at_i` (the only filterable numeric attribute) — e.g. "created_at_i>1700000000". Combine with commas for AND. No filter is applied by default. - hitsPerPage (optional, integer) — Hits per page (1–1000). Defaults to 30. - page (optional, integer) — 0-indexed page number for pagination. ``` curl "https://www.socialcrawl.dev/v1/hackernews/search?query=claude code" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /hackernews/story Get a Hacker News story Credit cost: 1 (standard) Parameters: - id (required) — HN story id (the numeric `objectID`). ``` curl "https://www.socialcrawl.dev/v1/hackernews/story?id=8863" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /hackernews/story/comments Get comments on a Hacker News story Credit cost: 1 (standard) Parameters: - id (required) — HN story id (the numeric `objectID`). ``` curl "https://www.socialcrawl.dev/v1/hackernews/story/comments?id=8863" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /hackernews/profile Get a Hacker News user profile Credit cost: 1 (standard) Parameters: - handle (required) — Hacker News username (case-sensitive, e.g. `pg` or `kogir`). ``` curl "https://www.socialcrawl.dev/v1/hackernews/profile?handle=pg" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Instagram ### GET /instagram/profile Get Instagram user profile Credit cost: 1 (standard) Parameters: - handle (required) — Instagram username without the @ symbol - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/instagram/profile?handle=instagram" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/profile/posts List Instagram user posts Credit cost: 1 (standard) Parameters: - handle (required) — Instagram username without the @ symbol - next_max_id (optional, string) — Cursor to get next page of results. - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/instagram/profile/posts?handle=instagram" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/post Get Instagram post details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Instagram post - region (optional, string) — 2 letter country code to set the proxy in - trim (optional, boolean) — Set to true to get a trimmed response - download_media (optional, boolean) — Set to true to also download the video/images and get back permanent, durable media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving — the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched. ``` curl "https://www.socialcrawl.dev/v1/instagram/post?url=https://www.instagram.com/p/CwA1234abcd/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/post/comments List Instagram post comments Credit cost: 5 (advanced) Parameters: - url (required) — URL of the Instagram post (a /p/, /reel/, /reels/, or /tv/ link). - sort (optional, enum: top | recent) — Ordering: `top` (default) ranks by Instagram's popularity order (most-liked first); `recent` returns newest-first. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - safe_url (optional, boolean) — When true, returns URL-safe profile picture links suitable for embedding. ``` curl "https://www.socialcrawl.dev/v1/instagram/post/comments?url=https://www.instagram.com/p/DXidPIVDU6M/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/comment Look up one Instagram comment by URL or id Credit cost: 5 (override; tier advanced) Parameters: - comment_url (optional, string) — An Instagram comment permalink: `https://www.instagram.com/p/{shortcode}/c/{commentId}/` (or a reply permalink `.../c/{parent}/r/{reply}/`, best-effort). Mutually exclusive with `post_url`+`comment_id`. - post_url (optional, string) — The post URL (a `/p/`, `/reel/`, `/reels/`, or `/tv/` link). Combine with `comment_id`, or with `author_username`/`text_contains` for a search. - comment_id (optional, string) — The target comment's numeric id (`pk`). Requires `post_url`. - author_username (optional, string) — Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id. - text_contains (optional, string) — Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id. - deep_scan (optional, boolean) — Widen the scan budget for deeply-buried comments (raises the per-chain page ceiling and deadline). Bills 15 credits instead of 5. - position_hint (optional, string) — Opaque token from a prior lookup's `lookup.position_hint`. Passing it back replays just the last-known sort chain first, making a re-check of an already-found comment cheap. - max (optional, integer) — For `author_username`/`text_contains` search: max matches to return (1–20, default 5). ``` curl "https://www.socialcrawl.dev/v1/instagram/comment?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/basic-profile Get Instagram basic profile Credit cost: 1 (standard) Parameters: - userId (optional, string) — Instagram numeric user ID ``` curl "https://www.socialcrawl.dev/v1/instagram/basic-profile?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/profile/reels List Instagram user reels (oneOf: user_id|handle) Credit cost: 1 (standard) Parameters: - user_id (optional, string) — Instagram user id. Use this for faster response times. - handle (optional, string) — Instagram username without the @ symbol - max_id (optional, string) — Max id to get more reels. Get 'max_id' from previous response. - trim (optional, boolean) — Set to true for a trimmed down version of the response - Constraint: one of user_id, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/profile/reels?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/highlights List Instagram story highlights (oneOf: user_id|handle) Credit cost: 1 (standard) Parameters: - user_id (optional, string) — Instagram user id. Use for faster response times. - handle (optional, string) — Instagram username without the @ symbol - Constraint: one of user_id, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/highlights?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/highlight/detail Get Instagram highlight detail Credit cost: 1 (standard) Parameters: - id (optional, string) — Instagram highlight ID — the numeric id, with or without the `highlight:` prefix. Get it from `/v1/instagram/user/highlights`. ``` curl "https://www.socialcrawl.dev/v1/instagram/highlight/detail?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/search/reels Search Instagram reels Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find Instagram reels - date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted - page (optional, integer) — The page number to return. ``` curl "https://www.socialcrawl.dev/v1/instagram/search/reels?query=workout routine" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/media/transcript Get Instagram media transcript Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the Instagram video or reel ``` curl "https://www.socialcrawl.dev/v1/instagram/media/transcript?url=https://www.instagram.com/reel/DHsD6HGqJhp/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/user/embed Get Instagram user embed HTML Credit cost: 1 (standard) Parameters: - handle (required) — Instagram username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/instagram/user/embed?handle=instagram" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/audio/reels List Instagram reels using an audio track Credit cost: 1 (standard) Parameters: - audio_id (required) — Instagram audio ID — the numeric id from an instagram.com/reels/audio/{audio_id}/ URL - cursor (optional, string) — Pagination cursor from the previous response ``` curl "https://www.socialcrawl.dev/v1/instagram/audio/reels?audio_id=1392969992841787" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/search/hashtag Search Instagram posts by hashtag Credit cost: 5 (advanced) Parameters: - hashtag (required) — The hashtag to search for. The leading # is optional. - type (optional, enum: top | recent | clips) — Ranking of the returned posts: `top` (default), `recent`, or `clips` (reels only). - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. ``` curl "https://www.socialcrawl.dev/v1/instagram/search/hashtag?hashtag=makeup" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/search/profiles Search Instagram profiles by keyword Credit cost: 1 (standard) Parameters: - query (required) — Bio or caption keyword/phrase to search for. - cursor (optional, string) — The cursor returned by the previous response. In this version it is the next Google results page number. ``` curl "https://www.socialcrawl.dev/v1/instagram/search/profiles?query=yoga" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/reels/trending Get trending Instagram reels Credit cost: 5 (advanced) ``` curl "https://www.socialcrawl.dev/v1/instagram/reels/trending?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/followers List Instagram followers (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username without the @ symbol. - user_id (optional, string) — Instagram numeric user ID. Use this for faster responses. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/followers?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/following List Instagram following (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username without the @ symbol. - user_id (optional, string) — Instagram numeric user ID. Use this for faster responses. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/following?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/similar List similar Instagram accounts (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username without the @ symbol. - user_id (optional, string) — Instagram numeric user ID. Use this for faster responses. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/similar?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/post/likers List Instagram post likers Credit cost: 5 (advanced) Parameters: - url (required) — URL of the Instagram post (a /p/ or /reel/ link). - safe_url (optional, boolean) — When true, returns URL-safe profile picture links suitable for embedding. ``` curl "https://www.socialcrawl.dev/v1/instagram/post/likers?url=https://www.instagram.com/p/CnpPou9hWqq/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/post/stats Get Instagram post stats including the share count Credit cost: 5 (advanced) Parameters: - url (required) — URL of the Instagram post (a /p/, /reel/, or /tv/ link). - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. ``` curl "https://www.socialcrawl.dev/v1/instagram/post/stats?url=https://www.instagram.com/p/CnpPou9hWqq/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/tagged List posts an Instagram user is tagged in (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username without the @ symbol. - user_id (optional, string) — Instagram numeric user ID. Use this for faster responses. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/tagged?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/location/posts List recent posts at an Instagram location Credit cost: 5 (advanced) Parameters: - location_id (required) — Instagram numeric location ID. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. ``` curl "https://www.socialcrawl.dev/v1/instagram/location/posts?location_id=331004901" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/engagement Get Instagram engagement statistics Credit cost: 5 (advanced) Parameters: - handle (required) — Instagram username without the @ symbol. ``` curl "https://www.socialcrawl.dev/v1/instagram/engagement?handle=mrbeast" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/search/location Search Instagram locations Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword or phrase to find Instagram locations. ``` curl "https://www.socialcrawl.dev/v1/instagram/search/location?query=Paris" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/username-suggestions Get Instagram username suggestions Credit cost: 5 (advanced) Parameters: - query (required) — Keyword to seed the username suggestions. ``` curl "https://www.socialcrawl.dev/v1/instagram/username-suggestions?query=mrbeast" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/search/music Search Instagram music Credit cost: 5 (advanced) Parameters: - query (required) — Search keyword or phrase to find Instagram audio tracks. - cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page. ``` curl "https://www.socialcrawl.dev/v1/instagram/search/music?query=beyonce" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/stories List an Instagram user's active stories (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username without the @ symbol. - user_id (optional, string) — Instagram numeric user ID. Use this for faster responses. - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/stories?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/story/download Download a single Instagram story (oneOf: user_id) (oneOf: story_id) Credit cost: 5 (advanced) Parameters: - user_id (optional, string) — Instagram numeric user ID of the story's author. - story_id (optional, string) — ID of the individual story to download. - safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding. - Constraint: one of user_id (at least one required) - Constraint: one of story_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/story/download?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/music/trending List trending Instagram music Credit cost: 5 (advanced) ``` curl "https://www.socialcrawl.dev/v1/instagram/music/trending?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/profile/full Instagram profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - handle (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/instagram/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/profile/reels/full Instagram reels with views, likes, comments, and per-reel share counts where available, in one call. (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund). - user_id (optional, string) — Numeric Instagram user id. Alternative to handle. - cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper. - limit (optional, integer) — Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/profile/reels/full?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /instagram/profile/posts/full Instagram posts with views, likes, comments, and per-post share counts where available, in one call. (oneOf: handle|user_id) Credit cost: 5 (advanced) Parameters: - handle (optional, string) — Instagram username (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund). - user_id (optional, string) — Numeric Instagram user id. Alternative to handle. - cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper. - limit (optional, integer) — Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/instagram/profile/posts/full?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Kick ### GET /kick/clip Get Kick clip details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Kick clip ``` curl "https://www.socialcrawl.dev/v1/kick/clip?url=https://kick.com/xqc/clips/clip_abc123" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Komi ### GET /komi/page Get Komi page Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Komi page ``` curl "https://www.socialcrawl.dev/v1/komi/page?url=https://kimkardashian.komi.io/" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Kwai ### GET /kwai/profile Get a Kwai user profile (oneOf: handle|url) Credit cost: 1 (standard) Parameters: - handle (optional, string) — Kwai profile handle (without the @) - url (optional, string) — Kwai profile URL - Constraint: one of handle, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/kwai/profile?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /kwai/user/posts List a Kwai user's posts (oneOf: handle|url) Credit cost: 1 (standard) Parameters: - handle (optional, string) — Kwai profile handle (without the @) - url (optional, string) — Kwai profile URL - cursor (optional, string) — Cursor from the previous response for the next page - count (optional, integer) — Number of posts to return (max 50) - Constraint: one of handle, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/kwai/user/posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /kwai/post Get a Kwai post Credit cost: 1 (standard) Parameters: - url (optional, string) — Full URL of the Kwai post ``` curl "https://www.socialcrawl.dev/v1/kwai/post?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Linkbio ### GET /linkbio/page Get Linkbio page Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Linkbio page ``` curl "https://www.socialcrawl.dev/v1/linkbio/page?url=https://lnk.bio/example" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Linkedin ### GET /linkedin/profile Get LinkedIn user profile Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile page ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company Get LinkedIn company page Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn company page ``` curl "https://www.socialcrawl.dev/v1/linkedin/company?url=https://www.linkedin.com/company/microsoft/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post Get LinkedIn post details Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn post ``` curl "https://www.socialcrawl.dev/v1/linkedin/post?url=https://www.linkedin.com/posts/williamhgates_example-activity-1234567890" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/people Search LinkedIn people Credit cost: 10 (premium) Parameters: - query (required) — Name or display-name keyword to search for (e.g. 'Bill Gates'). - page (optional, string) — Page number for pagination (default 1). - first_name (optional, string) — Filter by first name. - last_name (optional, string) — Filter by last name. - title (optional, string) — Filter by job title or headline. - current_company (optional, string) — Filter by current company ID (comma-separated for multiple). - past_company (optional, string) — Filter by a previously-worked company ID. - school (optional, string) — Filter by school ID. - industry (optional, string) — Filter by industry ID. - geocode_location (optional, string) — Filter by location geocode ID. - profile_language (optional, string) — Filter by profile language (ISO 2-letter code, e.g. 'en'). - service_category (optional, string) — Filter by service-category ID. - follower_of (optional, string) — Return people who follow a specific member URN. ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/people?query=Bill Gates" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/people List people at a LinkedIn company Credit cost: 10 (premium) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). - page (optional, string) — Page number for pagination (default 1). ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/people?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post/comments Get LinkedIn post comments Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn post (or its activity id). - page (optional, string) — Page number for pagination (default 1). - post_type (optional, string) — Upstream post type: 'activity' (default) or 'ugc'. - sort_order (optional, string) — Comment ordering: 'relevance' or 'recent'. ``` curl "https://www.socialcrawl.dev/v1/linkedin/post/comments?url=https://www.linkedin.com/feed/update/urn:li:activity:7244804629786419202" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/posts List a LinkedIn member's posts Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/posts?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/reactions List posts a LinkedIn member reacted to Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/reactions?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post/reposts List reposts of a LinkedIn post Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/post/reposts?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/group/posts List posts in a LinkedIn group Credit cost: 5 (advanced) Parameters: - group_id (required) — LinkedIn numeric group ID. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/group/posts?group_id=62438" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/affiliated-pages List a company's affiliated/showcase pages Credit cost: 5 (advanced) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/affiliated-pages?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post/comments/replies List replies to a LinkedIn comment Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - comment_id (required) — LinkedIn comment ID (from /post/comments). - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/post/comments/replies?url=https://www.linkedin.com/in/williamhgates/&comment_id=7244804629786419202" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/experiences List a member's work experiences Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/experiences?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/educations List a member's education history Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/educations?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/skills List a member's skills Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/skills?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/honors List a member's honors and awards Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/honors?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/certifications List a member's licenses and certifications Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/certifications?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/publications List a member's publications Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/publications?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/volunteers List a member's volunteer experiences Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/volunteers?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/recommendations List recommendations for a member Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) - type (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/recommendations?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/interests/companies List companies a member follows Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/interests/companies?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/interests/groups List groups a member follows Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/interests/groups?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/images List a member's image posts Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/images?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/videos List a member's video posts Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/videos?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/comments List a member's comments Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - cursor (optional, string) - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/comments?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post/reactions List reactors on a LinkedIn post Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. - page (optional, string) - type (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/post/reactions?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/jobs List a company's job postings Credit cost: 10 (premium) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). - page (optional, string) - date_posted (optional, string) - experience_level (optional, string) - job_type (optional, string) - remote (optional, string) - easy_apply (optional, string) - sort_by (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/jobs?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/jobs Search LinkedIn jobs Credit cost: 10 (premium) Parameters: - query (required) — Search keyword. - page (optional, string) - date_posted (optional, string) - experience_level (optional, string) - job_type (optional, string) - remote (optional, string) - easy_apply (optional, string) - sort_by (optional, string) - company (optional, string) - geocode (optional, string) - industry_ids (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/jobs?query=marketing" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/location Resolve a location to a LinkedIn geocode id Credit cost: 1 (standard) Parameters: - query (required) — Search keyword. ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/location?query=marketing" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/schools Search LinkedIn schools Credit cost: 1 (standard) Parameters: - query (required) — Search keyword. - page (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/schools?query=marketing" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/industry Resolve an industry name to a LinkedIn industry id Credit cost: 1 (standard) Parameters: - query (required) — Search keyword. ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/industry?query=marketing" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/about Get a member's profile metadata (joined date, freshness) Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/about?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/contact Get a member's public contact info Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/contact?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/stats Get a member's follower + connection counts Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn profile, company, or post. ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/stats?url=https://www.linkedin.com/in/williamhgates/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/job-count Get a company's open job count Credit cost: 5 (advanced) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/job-count?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/insights Get aggregate insights about a company's members Credit cost: 5 (advanced) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/insights?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/group Get LinkedIn group details Credit cost: 5 (advanced) Parameters: - group_id (required) — LinkedIn numeric group ID. ``` curl "https://www.socialcrawl.dev/v1/linkedin/group?group_id=62438" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/job Get LinkedIn job details Credit cost: 5 (advanced) Parameters: - id (required) — LinkedIn job ID. - include_skills (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/job?id=4019392600" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/company/posts List LinkedIn company posts Credit cost: 5 (advanced) Parameters: - company_id (required) — LinkedIn numeric company ID (from /v1/linkedin/company). - page (optional, string) — Page number for pagination (default 1). - sort_by (optional, string) — Post ordering: 'top' or 'recent'. ``` curl "https://www.socialcrawl.dev/v1/linkedin/company/posts?company_id=1035" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/ad Get LinkedIn ad details Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the LinkedIn ad ``` curl "https://www.socialcrawl.dev/v1/linkedin/ad?url=https://www.linkedin.com/ad-library/detail/666281156" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/ads/search Search LinkedIn ads Credit cost: 5 (advanced) Parameters: - company (optional, string) — The company name to search for. 'Microsoft' for example - keyword (optional, string) — The keyword to search for - companyId (optional, string) — The company id to search for - countries (optional, string) — Comma separated list of countries. Example: US,CA,MX - startDate (optional, string) — Start date to search for. Format: YYYY-MM-DD - endDate (optional, string) — End date to search for. Format: YYYY-MM-DD - paginationToken (optional, string) — Pagination token to paginate through results ``` curl "https://www.socialcrawl.dev/v1/linkedin/ads/search?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/search/posts Search public LinkedIn posts by keyword Credit cost: 5 (advanced) Parameters: - query (required) — Keyword or phrase to search for in public LinkedIn posts. - page (optional, string) - sort_by (optional, string) - date_posted (optional, string) — Date filter based on Google-indexed results. - content_type (optional, string) - from_company (optional, string) - from_member (optional, string) ``` curl "https://www.socialcrawl.dev/v1/linkedin/search/posts?query=ai agents" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/post/transcript Get a LinkedIn post video transcript Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the LinkedIn post to transcribe. ``` curl "https://www.socialcrawl.dev/v1/linkedin/post/transcript?url=https://www.linkedin.com/posts/gemini-35-flash-is-a-step-forward-for-google-ugcPost-7465082215316525056-MHBd/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /linkedin/profile/full LinkedIn company profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - url (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/linkedin/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Linkme ### GET /linkme/page Get Linkme profile Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Linkme page ``` curl "https://www.socialcrawl.dev/v1/linkme/page?url=https://link.me/example" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Linktree ### GET /linktree/page Get Linktree page Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Linktree page ``` curl "https://www.socialcrawl.dev/v1/linktree/page?url=https://linktr.ee/charlidamelio" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Naver ### GET /naver/blog/search Search Naver Blog Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/blog/search?query=소셜크롤" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/news/search Search Naver News Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/news/search?query=삼성전자" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/book/search Search Naver Book Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date|asc|dsc (asc/dsc = price asc/desc). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/book/search?query=데미안" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/encyc/search Search Naver Encyclopedia Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/encyc/search?query=양자역학" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/cafearticle/search Search Naver Cafe articles Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/cafearticle/search?query=주식" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/kin/search Search Naver KnowledgeiN (지식iN) Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date|point. Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/kin/search?query=코로나 증상" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/local/search Search Naver Local (장소 검색) Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: random|comment (display max 5, start max 1). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/local/search?query=강남역 카페" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/shop/search Search Naver Shopping Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date|asc|dsc (asc/dsc = price asc/desc). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/shop/search?query=노트북" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/doc/search Search Naver Academic Documents (전문자료) Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/doc/search?query=딥러닝" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/image/search Search Naver Image Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/image/search?query=한라산" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/webkr/search Search Naver Web (웹문서) Credit cost: 1 (standard) Parameters: - query (required) — Free-text search term (UTF-8). Required. - display (optional, integer) — Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5). - start (optional, integer) — 1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1). - sort (optional, string) — Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort. ``` curl "https://www.socialcrawl.dev/v1/naver/webkr/search?query=기후변화" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /naver/brief One query across the Korean internet (6 Naver corpora) + optional digest. Credit cost: 10 (override; tier advanced) Parameters: - query (required) — Search query (Korean or any language). - corpora (optional, string) — CSV subset of news,blog,cafearticle,kin,shop,webkr (default all six). - display (optional, integer) — Items per corpus (1–100, default 20). - start (optional, integer) — 1-indexed offset per corpus (1–1000, default 1). Prefer `cursor` for paging. - sort (optional, string) — sim (relevance, default) or date; shop also asc/dsc (price); kin also point. - include (optional, string) — Set to `digest` for an LLM English digest with translated quotes. - cursor (optional, string) — Opaque pagination token from a prior response's next_cursor. ``` curl "https://www.socialcrawl.dev/v1/naver/brief?query=삼성전자" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Perplexity ### GET /perplexity/research Web research via Perplexity Sonar Credit cost: 1 (standard) Parameters: - query (required) — Natural-language research prompt. Sonar autonomously searches the live web and grounds the response in real sources. No prompt-engineering required — phrase it as you would to a search engine or research assistant. ``` curl "https://www.socialcrawl.dev/v1/perplexity/research?query=What is the capital of France?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Pillar ### GET /pillar/page Get Pillar page Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Pillar page ``` curl "https://www.socialcrawl.dev/v1/pillar/page?url=https://pillar.io/example" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Pinterest ### GET /pinterest/search Search Pinterest pins Credit cost: 1 (standard) Parameters: - query (required) — Search query - cursor (optional, string) — Cursor - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/pinterest/search?query=home decor ideas" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /pinterest/pin Get Pinterest pin details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Pinterest pin - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/pinterest/pin?url=https://www.pinterest.com/pin/1234567890/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /pinterest/url-stats Get Pinterest save counts for external URLs Credit cost: 1 (standard) Parameters: - urls (required) — Comma-separated list of 1–10 absolute http(s):// URLs, passed to Pinterest verbatim. Variants (https vs http, with/without trailing slash, with/without query string) are counted as different URLs. ``` curl "https://www.socialcrawl.dev/v1/pinterest/url-stats?urls=https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /pinterest/board Get Pinterest board Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Pinterest board - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/lizmrodgers/moms-night/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /pinterest/user/boards List Pinterest user boards Credit cost: 1 (standard) Parameters: - handle (required) — The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/) - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/pinterest/user/boards?handle=pinterest" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Polymarket ### GET /polymarket/research Polymarket prediction markets — multi-query research Credit cost: 5 (advanced) Parameters: - query (required) — The research topic — free-text natural language (e.g. 'last 30 days bitcoin halving', 'kanye west tour'). Framing prefixes like 'last N days' and 'what are people saying about' are stripped automatically before expansion. - limit (optional, integer) — Max results per result type on each fan-out call (events / markets / profiles). Bounds the response size. Defaults to 10. ``` curl "https://www.socialcrawl.dev/v1/polymarket/research?query=trump 2028 election" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Prism ### GET /prism/lookup Universal URL dispatcher: any social/commerce URL → the right detail endpoint's unified response. Credit cost: 0 (override; tier standard) Parameters: - url (required) — Absolute http(s) URL of the post / profile / product to resolve. - include (optional, string) — CSV of optional flags to forward verbatim to the resolved endpoint (e.g. `trim`). Each member must be an optional param of that endpoint. ``` curl "https://www.socialcrawl.dev/v1/prism/lookup?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/comments Every comment on a post, replies nested, server-paginated to completion. Credit cost: 1 (standard) Parameters: - url (required) — Absolute http(s) URL of the post whose comments to harvest. - max (optional, integer) — Stop after roughly this many top-level comments (1–5000, default 1000). Whole pages are returned, so the actual count can slightly exceed this. Drives billing and, for `sort=top`, the depth of the ranking scan. - replies (optional, boolean) — Expand replies for comments that have them, where the platform supports it (default true; TikTok/YouTube/Facebook only). Pair with `replies=false` when you only want the top comments. - cursor (optional, string) — Opaque composite cursor from a prior response's `next_cursor` to resume harvesting. - sort (optional, enum: top | recent) — `recent` (default — natural order) or `top` (most-liked first, ranked by each comment's like count). With `top`, the response adds `sorted_by: "likes_desc"`. - limit (optional, integer) — Cap on how many top-level comments to return after sorting/scanning (1–5000, defaults to `max`). Truncates only the returned set — never what was scanned or billed. The response reports `returned`. ``` curl "https://www.socialcrawl.dev/v1/prism/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/brand-mentions Brand mention volume time-series, sentiment split, top sources, and recent mentions for one keyword. Credit cost: 50 (override; tier advanced) Parameters: - keyword (required) — The brand or term to track. Wrap in quotes for exact-phrase semantics. - date_from (required) — Window start (YYYY-MM-DD). Required by the trend leg. - date_to (optional, string) — Window end (YYYY-MM-DD). Defaults to the latest crawl. - date_group (optional, enum: day | week | month) — Trend bucket size: day (default), week, or month. - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Optional surface filter: ecommerce, news, blogs, message-boards, or organization. - include (optional, string) — Set `digest` to add an LLM narrative summary leg. ``` curl "https://www.socialcrawl.dev/v1/prism/brand-mentions?keyword=socialcrawl&date_from=2026-06-01" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/demand-signals Consumer-demand nowcast: app-review velocity, web mention slope, Reddit velocity, and commerce review levels, fused into a published demand index. Credit cost: 30 (override; tier advanced) Parameters: - keyword (required) — The brand or product to nowcast. Drives the mention, Reddit, and Amazon legs. - google_play_id (optional, string) — Google Play package name (e.g. com.spotify.music) for the app-review velocity axis. - app_store_id (optional, string) — Apple App Store numeric id for the app-review velocity axis. - signals (optional, string) — CSV subset of app_reviews,mentions,reddit,commerce (default all). app_reviews is dropped when no app id is supplied. - amazon_query (optional, string) — Override the Amazon product-search term if it differs from the brand. - country (optional, string) — Location for the app-review legs (default United States); a 2-letter code is also applied to the Amazon leg. - date_from (optional, string) — Window start (YYYY-MM-DD) for the mention-slope leg. Defaults to 30 days ago. - date_to (optional, string) — Window end (YYYY-MM-DD). Defaults to today. - depth (optional, integer) — Reviews per store for the velocity computation (1-600, default 150). ``` curl "https://www.socialcrawl.dev/v1/prism/demand-signals?keyword=spotify" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/campaign Campaign tracker: pre/during/post volume lift, cross-platform engagement, and ranked top amplifiers for a hashtag or phrase. (oneOf: hashtag|phrase) Credit cost: 35 (override; tier advanced) Parameters: - hashtag (optional, string) — The campaign hashtag (with or without #). One of hashtag or phrase is required. - phrase (optional, string) — A campaign slogan/phrase instead of a hashtag. One of hashtag or phrase is required. - window_start (optional, string) — Campaign launch date (YYYY-MM-DD) — the pre/during boundary. Optional; defaults to 30 days ago. - window_end (optional, string) — Campaign end date (YYYY-MM-DD) — the during/post boundary. Defaults to today. - pre_days (optional, integer) — Baseline days before window_start for lift measurement (1-90, default 14). - post_days (optional, integer) — Days after window_end for the post window (0-90, default 14; 0 = no post window). - include (optional, string) — Set amplifier_dates to date YouTube amplifiers via direct youtube/video calls (undated in fusion). - Constraint: one of hashtag, phrase (at least one required) ``` curl "https://www.socialcrawl.dev/v1/prism/campaign?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/ai-visibility AI Share-of-Voice / GEO monitoring: prompt set x reruns to per-brand appearance-% per AI engine plus a cited-domain ranking. Credit cost: 2 (override; tier advanced) Parameters: - brand (optional, string) — The brand whose appearance-% is measured (required). Matched against each answer plus its aliases. - prompts (optional, string) — The category prompts to probe, as a JSON array or a pipe-delimited list (1-20). One of prompts or topic is required. - topic (optional, string) — A topic probed as a single prompt in v1 (one of prompts or topic is required). - competitors (optional, string) — CSV of up to 5 competitors also measured for appearance-% from the same answers. - engines (optional, string) — CSV subset of perplexity,grok (default both) — the grounded-answer engines probed. - runs (optional, integer) — Reruns per (prompt, engine) to measure variance (1-20, default 8). - preset (optional, enum: quick | standard | deep) — quick|standard|deep — sets runs and caps prompts for a flat probe budget. - include (optional, string) — Set web_baseline to cross-join AI-cited domains against your web top domains. - brand_domains (optional, string) — CSV of your own domains so the citation ranking can flag the ones you already rank on. ``` curl "https://www.socialcrawl.dev/v1/prism/ai-visibility?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/crisis-postmortem Crisis post-mortem: a who-said-what-first timeline across web, Reddit, Hacker News, and social, with an origin, peak, propagation sequence, and a grounded narrative. Credit cost: 35 (override; tier advanced) Parameters: - brand (required) — The brand or entity the crisis is about (required). - window_start (optional, string) — Start of the crisis window (YYYY-MM-DD) — the earliest point on the timeline. Optional; defaults to 30 days ago. - window_end (optional, string) — End of the crisis window (YYYY-MM-DD). Defaults to today. - crisis_terms (optional, string) — Optional CSV of up to 5 terms (e.g. recall,defect) that scope the legs to the actual incident. - include (optional, string) — narrative (default on) adds the grounded LLM propagation narrative; pass an empty value for the raw timeline only. ``` curl "https://www.socialcrawl.dev/v1/prism/crisis-postmortem?brand=acme" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/crisis-radar Stateless crisis breach check: a z-score on daily mention volume and negative share, with on-breach confirmation and a severity grade. Credit cost: 15 (override; tier advanced) Parameters: - brand (optional, string) — The brand to watch (required). - sensitivity (optional, string) — Z-score breach threshold (0.5-6, default 2.0). z>=sensitivity on volume or negative-share fires a breach. - confirm (optional, boolean) — true -> on a breach, run the escalation legs and grade severity (+30 credits, charged only when a breach fires). - baseline_days (optional, integer) — Rolling-mean window for the z-score (3-30, default 7). - date_to (optional, string) — The day being evaluated (YYYY-MM-DD). Defaults to today. ``` curl "https://www.socialcrawl.dev/v1/prism/crisis-radar?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/devtool-pulse Developer-brand health: a devtool's repo dossier + Hacker News reaction + Reddit chatter + dev-blog echo, in one call. Credit cost: 20 (override; tier advanced) Parameters: - query (required) — The devtool name to sweep across Hacker News, Reddit, and the dev-blog index (e.g. Bun, Drizzle ORM, tRPC). - repo (optional, string) — The repo to dossier — owner/repo or a github.com/{owner}/{repo} URL. Recommended for a precise dossier. - subreddit (optional, string) — Optional scope for the Reddit leg (bare name, no r/) — switches it to a subreddit search. - include (optional, string) — CSV subset of dossier,hn,reddit,blogs (default all). Trims which legs run, not the flat price. - date_from (optional, string) — Optional window start (YYYY-MM-DD) applied to the time-bounded legs. - date_to (optional, string) — Optional window end (YYYY-MM-DD). ``` curl "https://www.socialcrawl.dev/v1/prism/devtool-pulse?query=Bun" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/leads Ranked feed of public conversations where people seek alternatives to or are switching from a competitor. Credit cost: 50 (override; tier advanced) Parameters: - competitor (required) — The competitor/product to mine alternative-seeking conversations for (≤80 chars). - product_category (optional, string) — Optional disambiguator appended to the social queries to cut cross-domain noise (e.g. 'project management'). - freshness (optional, string) — Recency floor — Nd/Nw/Nm (e.g. 30d) or an ISO date. Default 30d. - include (optional, string) — Set `comments` to attach top-thread Reddit comments to the top leads. - limit (optional, integer) — Max leads in the fused feed (1–100, default 50). ``` curl "https://www.socialcrawl.dev/v1/prism/leads?competitor=notion" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/earned-media A brand's earned-media footprint — news + tech-press + fresh-web clips, deduped and ranked, with an outlet-coverage rollup. Credit cost: 25 (override; tier advanced) Parameters: - brand (required) — The brand/company to map earned media for. - competitor (optional, string) — Optional competitor for a share-of-coverage gap. - date_from (optional, string) — Window start (YYYY-MM-DD). - date_to (optional, string) — Window end (YYYY-MM-DD). - min_domain_rank (optional, integer) — Drop clips from sites below this domain authority. - include (optional, string) — Set `digest` to add an LLM narrative summary. ``` curl "https://www.socialcrawl.dev/v1/prism/earned-media?brand=Vercel" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/truthsocial-pulse A Truth Social handle's pulse — profile, recent posts, per-post detail drill, and the news echo, in one call. Credit cost: 20 (override; tier advanced) Parameters: - handle (required) — The Truth Social handle (no @). - drill (optional, integer) — How many top posts to drill for full detail (0 to skip). - posts (optional, integer) — How many recent posts to pull (window cap). - news_query (optional, string) — Override the content_analysis news keyword (defaults to the handle/display name). - include (optional, string) — CSV subset of posts,news to trim which legs run. - cursor (optional, string) — Opaque pagination cursor for the posts leg. ``` curl "https://www.socialcrawl.dev/v1/prism/truthsocial-pulse?handle=realDonaldTrump" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/launch-echo How a launch landed — the Hacker News reaction (top threads + comments), the dev-blog echo, and an optional repo dossier. Credit cost: 20 (override; tier advanced) Parameters: - query (required) — The launch/product name to measure reception for. - repo (optional, string) — Optional owner/repo or github URL to anchor the dossier. - threads (optional, integer) — How many top HN threads to dig comments for. - date_from (optional, string) — Window start (YYYY-MM-DD). - date_to (optional, string) — Window end (YYYY-MM-DD). - include (optional, string) — CSV subset toggling the comments/blogs/dossier legs. ``` curl "https://www.socialcrawl.dev/v1/prism/launch-echo?query=Bun 1.2" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/audience-overlap How much two TikTok creators' commenter audiences overlap — Jaccard, shared-fan count, and a confidence label. Credit cost: 20 (override; tier advanced) Parameters: - handle_a (required) — First TikTok creator handle. - handle_b (required) — Second TikTok creator handle. - platform (optional, string) — Platform (tiktok only in v1; default tiktok). - videos_per_creator (optional, integer) — Recent videos sampled per creator (1–10, default 5) — caps the commenter pull. - depth (optional, string) — Set `deep` to widen the shared-fan enrichment sample. ``` curl "https://www.socialcrawl.dev/v1/prism/audience-overlap?handle_a=mkbhd&handle_b=mrwhosetheboss" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/reputation A brand's cross-source reputation — Trustpilot + app stores + Google Business + web sentiment, blended into one weighted score with themed pros/cons. Credit cost: 30 (override; tier premium) Parameters: - brand (required) — The brand/business/domain to assess. - sources (optional, string) — CSV subset of trustpilot,google_play,app_store,google,tripadvisor,web (default the core set). - country (optional, string) — Marketplace/locale (DFS location). Defaults to United States. - depth (optional, integer) — Reviews per source (Trustpilot clamped ≤20). - place (optional, string) — Set to enable the place-based legs (Google Business + TripAdvisor). - axis (optional, enum: company | product | both) — Which reputation axis to headline: company, product, or both (default). - app_store_id (optional, string) — App Store id to anchor that axis directly (skips resolver). - google_play_id (optional, string) — Google Play id to anchor that axis directly (skips resolver). - include (optional, string) — Optional leg toggles. ``` curl "https://www.socialcrawl.dev/v1/prism/reputation?brand=Notion" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/employer-brand A company's employer brand — what people say about working there across Reddit, the web, YouTube, Naver, and the company's own LinkedIn voice. Credit cost: 30 (override; tier premium) Parameters: - company (required) — The employer/company name. - linkedin_url (optional, string) — The company's LinkedIn URL — enables the LinkedIn voice axis + the posting-vs-reality gap. - surfaces (optional, string) — CSV subset of the surfaces to include. - phrases (optional, string) — Optional extra Reddit search phrases. - timeframe (optional, string) — Reddit timeframe window. - date_from (optional, string) — Window start (YYYY-MM-DD). - date_to (optional, string) — Window end (YYYY-MM-DD). ``` curl "https://www.socialcrawl.dev/v1/prism/employer-brand?company=Stripe" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/audience-questions The real questions a topic's audience asks — harvested from Reddit + YouTube threads and clustered by intent (who/what/why/how/vs). Credit cost: 30 (override; tier premium) Parameters: - topic (required) — The topic/keyword to mine audience questions for. - platforms (optional, string) — CSV subset of reddit,youtube,web (default reddit,youtube). - max_questions (optional, integer) — Cap on questions returned. - threads_per_source (optional, integer) — How many top threads to dig per source. - timeframe (optional, string) — Recency window. - include (optional, string) — Set `web` to add the universal-search leg. ``` curl "https://www.socialcrawl.dev/v1/prism/audience-questions?topic=kubernetes operators" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/product-reviews A product's reviews across Amazon + Google Shopping + Trustpilot, folded into a cross-marketplace rating + themed pros/cons report. (oneOf: query|asin|gid) Credit cost: 30 (override; tier premium) Parameters: - query (optional, string) — Product name to auto-resolve across marketplaces. - asin (optional, string) — Amazon ASIN to anchor the Amazon axis directly. - gid (optional, string) — Google product id (gid) to anchor the Google Shopping axis (NOT the catalogid). - sources (optional, string) — CSV subset of amazon,google_shopping,trustpilot (default all). - country (optional, string) — Marketplace country (DFS location). - depth (optional, integer) — Reviews per source (Trustpilot clamped ≤20). - competitors (optional, string) — Optional competitor products for a comparison (validated; deeper sweep is a fast-follow). - include (optional, string) — Optional leg toggles. - Constraint: one of query, asin, gid (at least one required) ``` curl "https://www.socialcrawl.dev/v1/prism/product-reviews?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/apps-lookup One app across Google Play + the App Store — resolved, title-matched, and compared into a cross-store rating + listing report. (oneOf: title|google_play_id|app_store_id) Credit cost: 30 (override; tier premium) Parameters: - title (optional, string) — The app title to resolve across both stores. - google_play_id (optional, string) — Google Play app id to anchor that store directly. - app_store_id (optional, string) — App Store app id to anchor that store directly. - stores (optional, string) — CSV subset of google_play,app_store (default both). - country (optional, string) — Store country. - language (optional, string) — Store language. - match_threshold (optional, string) — Title-similarity threshold for the cross-store match guard (0–1, default 0.6). - include (optional, string) — Optional leg toggles. - Constraint: one of title, google_play_id, app_store_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/prism/apps-lookup?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/org-radar A GitHub org's footprint — its top repos each expanded into a full dossier (releases, issue load, top request/complaint), rolled up. Credit cost: 26 (override; tier premium) Parameters: - org (required) — The GitHub org login or a github.com/{org} URL. - repos (optional, integer) — How many top repos to dossier (1–10, default 5) — drives the metered price. - sort (optional, enum: stars | updated | pushed) — Repo ranking: stars (default), updated, or pushed. - include (optional, string) — Optional leg toggles. ``` curl "https://www.socialcrawl.dev/v1/prism/org-radar?org=vercel" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/creator-vet Vet a creator before partnering — engagement quality, commenter authenticity, posting cadence, and controversy signals, optionally across platforms. Credit cost: 50 (override; tier premium) Parameters: - handle (required) — The creator handle to vet. - platform (optional, string) — Primary platform (tiktok/youtube/instagram). - depth (optional, string) — Set `deep` to widen the post + commenter sample. - include (optional, string) — Set `cross_platform` to add the universal cross-platform presence leg (+25cr). ``` curl "https://www.socialcrawl.dev/v1/prism/creator-vet?handle=mkbhd" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/korea-gap What the world is talking about that Korea isn't (and vice versa) — the global vs Korean (Naver) conversation gap for a brand/topic. Credit cost: 40 (override; tier premium) Parameters: - query (required) — The brand/topic to compare across the global and Korean conversations. - include (optional, string) — Members include `social` (the everywhere leg) + `digest`. Drop `social` for the 15cr web-only variant. - date_from (optional, string) — Window start (YYYY-MM-DD). - date_to (optional, string) — Window end (YYYY-MM-DD). - display (optional, integer) — Naver results per corpus. ``` curl "https://www.socialcrawl.dev/v1/prism/korea-gap?query=Stanley cup" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/share-of-voice Engagement-weighted Share of Voice across 2-5 brands, with web+social split, emotion overlay, and ESOV. Credit cost: 40 (override; tier premium) Parameters: - brands (required) — 2-5 competitor brand names (CSV). - category_code (optional, string) — Numeric DFS taxonomy code for true-share-of-category (use content_analysis/categories to look one up). - market_shares (optional, string) — JSON map of real market share per brand (fraction or %), e.g. {"notion":0.4,"coda":0.25,"airtable":0.35}, to compute ESOV. - include (optional, string) — CSV toggles (default `emotions,social`). Drop `social` for the cheaper web-only variant; drop `emotions` to skip the sentiment leg. - page_type (optional, enum: ecommerce | news | blogs | message-boards | organization) — Optional surface filter forwarded to the content_analysis legs. - date_from (optional, string) — Window start (YYYY-MM-DD). Defaults to 90 days ago. - date_to (optional, string) — Window end (YYYY-MM-DD). Defaults to today. ``` curl "https://www.socialcrawl.dev/v1/prism/share-of-voice?brands=notion,coda,airtable" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/review-integrity Cross-source review integrity verdict (statistical, deterministic). (oneOf: query|asin|gid) Credit cost: 30 (override; tier premium) Parameters: - query (optional, string) — Product or brand name to evaluate. - asin (optional, string) — Amazon ASIN to anchor the Amazon axis directly (skips product-search). - gid (optional, string) — Google product id (gid) to anchor the Google Shopping axis (NOT the catalogid product.id). - sources (optional, string) — CSV subset of amazon,google_shopping,trustpilot,web,forums (default all). - country (optional, string) — Marketplace country (DFS location). Defaults to United States. - Constraint: one of query, asin, gid (at least one required) ``` curl "https://www.socialcrawl.dev/v1/prism/review-integrity?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/answers Multi-engine AI consensus: one question → Perplexity + Grok + Tavily answers verbatim, merged citations, and an agreement matrix. Credit cost: 15 (override; tier premium) Parameters: - query (required) — The question, forwarded verbatim to every engine. - engines (optional, string) — CSV subset of perplexity,grok,tavily (default all three). - include (optional, string) — CSV of optional grounding legs: `polymarket` adds market probabilities (trimmed). ``` curl "https://www.socialcrawl.dev/v1/prism/answers?query=will the fed cut rates in september" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/video-intel One video URL → detail + stats + transcript + top comments + commenter sample, across YouTube/TikTok/Rumble/Instagram. Credit cost: 5 (override; tier advanced) Parameters: - url (required) — Absolute http(s) URL of a YouTube, TikTok, Rumble, or Instagram video. - comments (optional, string) — How many top comments to fetch (0–50, default 20). `0` skips the comments leg. - include (optional, string) — CSV of optional costed legs: `transcript` (adds the dedicated transcript leg, +10cr, refunded when null) and/or `commenter_profiles` (≤3 commenter mini-profiles, TikTok/Instagram in v1). ``` curl "https://www.socialcrawl.dev/v1/prism/video-intel?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/voice One person's public posts across X, Threads, Bluesky, and Truth Social, time-merged. Credit cost: 5 (override; tier advanced) Parameters: - handle (required) — The handle to look up across all four microblogs (a single leading @ is stripped). - platforms (optional, string) — CSV subset of twitter,threads,bluesky,truthsocial (default all four). - cursor (optional, string) — Opaque per-platform pagination token from a prior response's cursors_by_platform (twitter is a single non-paginatable page). - include (optional, string) — CSV subset of posts_by_platform,merged_timeline,computed to trim the payload (posts_by_platform is always returned). ``` curl "https://www.socialcrawl.dev/v1/prism/voice?handle=nasa" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/app-reviews Cross-store app review intelligence (Google Play + App Store) — translated, clustered, sentiment-scored. Credit cost: 15 (override; tier advanced) Parameters: - google_play_id (optional, string) — Google Play package name (e.g. com.spotify.music). - app_store_id (optional, string) — App Store numeric app id (e.g. 324684580). - query (optional, string) — App name to auto-resolve the top hit on each requested store (when no id is given). - country (optional, string) — Storefront country (DFS location name or numeric code). Defaults to the DFS default location. - language (optional, string) — Language code (e.g. en). - depth (optional, integer) — Reviews per store (default 150 Google / 50 Apple, max 600). The App Store returns ~50 at depth 40. - stores (optional, string) — CSV subset of google_play,app_store. Defaults to whichever ids/query resolve. - include (optional, string) — CSV of topics,sentiment_timeline,feature_requests,responses (default all). Omitting topics+feature_requests skips the LLM step. ``` curl "https://www.socialcrawl.dev/v1/prism/app-reviews?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/creator-card One handle, unified author cards across TikTok, Instagram, YouTube, X (and more). Credit cost: 5 (override; tier advanced) Parameters: - handle (required) — The handle to look up across every requested platform (a single leading @ is stripped). - platforms (optional, string) — CSV subset of tiktok,instagram,youtube,twitter,threads,bluesky,truthsocial (default the first four). Unknown platforms are ignored. - include (optional, string) — CSV subset of cards,totals to trim the payload (cards is always returned). ``` curl "https://www.socialcrawl.dev/v1/prism/creator-card?handle=mrbeast" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/handle-audit Should you pull this handle? One call scores a handle across platforms, ranks the best ones, and projects the data volume + credit cost to pull it. Credit cost: 5 (override; tier advanced) Parameters: - handle (required) — The handle to audit across every requested platform. Accepts a bare handle, a leading @, or a full profile URL (the platform is sniffed from the host). - platforms (optional, string) — CSV subset of tiktok,instagram,youtube,twitter,threads,bluesky,truthsocial (default the first four). Unknown platforms are ignored. Max 8. - sample (optional, string) — Recent posts sampled per found platform for the engagement + activity metrics (default 10, max 25). ``` curl "https://www.socialcrawl.dev/v1/prism/handle-audit?handle=mrbeast" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/post-stats Up to 100 mixed-platform post URLs → current engagement per URL, failed URLs refunded. Credit cost: 1 (override; tier standard) Parameters: - urls (required) — JSON array of 1–100 absolute http(s) post URLs (mixed platforms allowed). - include (optional, string) — CSV subset of views,likes,comments,shares,saves to trim each row's engagement block. ``` curl "https://www.socialcrawl.dev/v1/prism/post-stats?urls=["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/comment-lookup Re-check up to 25 known comments in one call — per-item results, failed items refunded. Credit cost: 2 (override; tier standard) Parameters: - items (required) — JSON array of 1–25 lookup items. Each item is `{ "comment_url": "…" }` or `{ "platform": "tiktok"|"instagram", "post_url": "…", "comment_id": "…" }`, optionally with `parent_comment_id`, `position_hint`, and `deep_scan`. ``` curl "https://www.socialcrawl.dev/v1/prism/comment-lookup?items=[{"comment_url":"https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670"},{"platform":"instagram","post_url":"https://www.instagram.com/p/CnpPou9hWqq/","comment_id":"18007013966365752"}]" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /prism/profiles Up to 50 (platform, handle) pairs → one canonical Author per row, failed handles refunded. Credit cost: 1 (override; tier standard) Parameters: - items (required) — JSON array of 1–50 items. Each item is `{ "platform": "tiktok", "handle": "@scout2015", "custom_id"?: "…" }`. `handle` accepts an @handle, a bare handle, or a pasted profile URL. ``` curl "https://www.socialcrawl.dev/v1/prism/profiles?items=[{"platform":"tiktok","handle":"@scout2015"},{"platform":"linkedin","handle":"williamhgates","custom_id":"vet-1"}]" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Reddit ### GET /reddit/subreddit List Reddit subreddit posts Credit cost: 1 (standard) Parameters: - subreddit (required) — Subreddit name without the r/ prefix - timeframe (optional, enum: all | day | week | month | year) — Timeframe to get posts from. Applied with sort=top (auto-selected when you omit sort). - sort (optional, enum: best | hot | new | top | rising) — Sort order - after (optional, string) — After to get more posts. Get 'after' from previous response. - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/reddit/subreddit?subreddit=technology" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/subreddit/details Get Reddit subreddit details (oneOf: subreddit|url) Credit cost: 1 (standard) Parameters: - subreddit (optional, string) — Subreddit name without the r/ prefix. Case-sensitive — use the subreddit's canonical casing (e.g. `AskReddit`). - url (optional, string) — Subreddit URL - Constraint: one of subreddit, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/search Search Reddit posts Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find Reddit posts - sort (optional, enum: relevance | new | top | comment_count) — Sort by - timeframe (optional, enum: all | day | week | month | year) — Timeframe - after (optional, string) — Used to paginate to next page - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/reddit/search?query=best programming languages 2024" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/post/comments List Reddit post comments Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the Reddit post to fetch comments for - cursor (optional, string) — Cursor to get more comments, or replies. - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/reddit/post/comments?url=https://www.reddit.com/r/technology/comments/abc123/example_post/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/subreddit/search Search within a subreddit Credit cost: 1 (standard) Parameters: - subreddit (required) — Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL) - query (optional, string) — Search query to find matching content - sort (optional, enum: relevance | hot | top | new | comments) — Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new - timeframe (optional, enum: all | year | month | week | day | hour) — Timeframe to filter results - cursor (optional, string) — Cursor to get more results. Get 'cursor' from previous response. ``` curl "https://www.socialcrawl.dev/v1/reddit/subreddit/search?subreddit=technology" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/post/transcript Get a Reddit video post transcript Credit cost: 10 (premium) Parameters: - url (required) — Reddit post URL or direct v.redd.it video URL. - language (optional, string) — 2-letter language code. Defaults to `en`. ``` curl "https://www.socialcrawl.dev/v1/reddit/post/transcript?url=https://www.reddit.com/r/youseeingthisshit/comments/1oiu9xm/football_nostalgiasaints_punter_head_coach_cant/" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /reddit/omni-search Reddit VoC sweep: one keyword → threads across all of Reddit with subreddit attribution and top comments inline. Credit cost: 1 (standard) Parameters: - query (required) — Keyword or phrase to sweep across Reddit. - threads (optional, integer) — How many top threads to expand comments for (1–8, default 8). - sort (optional, enum: relevance | new | top | comment_count) — Search sort order (relevance | new | top | comment_count). - timeframe (optional, enum: all | day | week | month | year) — Time window for the search (all | day | week | month | year). - subreddit (optional, string) — Scope the sweep to one subreddit (bare name, no r/ prefix). - cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper. - include (optional, string) — CSV subset of subreddits,comments (default both). ``` curl "https://www.socialcrawl.dev/v1/reddit/omni-search?query=best mechanical keyboard" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Rumble ### GET /rumble/search Search Rumble videos Credit cost: 1 (standard) Parameters: - query (required) — Search query. - cursor (optional, string) — Cursor from the previous response — the next page number (e.g. `2`). ``` curl "https://www.socialcrawl.dev/v1/rumble/search?query=funny cats" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /rumble/channel/videos List videos for a Rumble channel (oneOf: handle|url) Credit cost: 1 (standard) Parameters: - handle (optional, string) — Rumble channel handle. - url (optional, string) — Rumble channel URL. - cursor (optional, string) — Cursor from the previous response — the next page number (e.g. `2`). - Constraint: one of handle, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/rumble/channel/videos?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /rumble/video Get a Rumble video Credit cost: 1 (standard) Parameters: - url (required) — Rumble video URL. ``` curl "https://www.socialcrawl.dev/v1/rumble/video?url=https://rumble.com/v79xhhm-discovery-example.html" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /rumble/video/transcript Get a Rumble video transcript Credit cost: 10 (premium) Parameters: - url (required) — Rumble video URL. ``` curl "https://www.socialcrawl.dev/v1/rumble/video/transcript?url=https://rumble.com/v784xoi-president-donald-j.-trump-and-secwar-pete-hegseth-hold-a-press-conference-a.html" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /rumble/video/comments List top-level comments on a Rumble video Credit cost: 1 (standard) Parameters: - url (required) — Rumble video URL. ``` curl "https://www.socialcrawl.dev/v1/rumble/video/comments?url=https://rumble.com/v792vns-example.html" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Search ### GET /search/everywhere Universal social search across 12 platforms Credit cost: 20 (override; tier standard) Parameters: - query (required) — Search query (1–512 chars) - lookback_days (optional, integer) — Days to look back (1–365+, default 30); mutually exclusive with from_date/to_date. - from_date (optional, string) — ISO YYYY-MM-DD lower bound; mutually exclusive with lookback_days. - to_date (optional, string) — ISO YYYY-MM-DD upper bound; defaults to today when from_date is set alone. - sources (optional, string) — Optional CSV allowlist of source names (mutually exclusive with exclude). - exclude (optional, string) — Optional CSV blocklist of source names (mutually exclusive with sources). ``` curl "https://www.socialcrawl.dev/v1/search/everywhere?query=kanye west" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /search/forums Fused forum search across Reddit, Hacker News, and Naver 지식iN/카페 — with top comments inline on hero threads by default. Credit cost: 10 (override; tier standard) Parameters: - query (required) — Search query (2–256 chars), forwarded to every forum search. - sources (optional, string) — Optional CSV allowlist of forum sources (reddit, hackernews, naver_kin, naver_cafe). Mutually exclusive with exclude. - exclude (optional, string) — Optional CSV blocklist of forum sources. Mutually exclusive with sources. - comments (optional, string) — Comment enrichment toggle (on|off, default on). 'off' returns thread-only. - timeframe (optional, string) — Recency window passed to Reddit; HN filtered client-side (all|day|week|month|year, default all). - lookback_days (optional, integer) — Alt recency window in days (1–365); HN filtered client-side. ``` curl "https://www.socialcrawl.dev/v1/search/forums?query=airpods pro 3 battery" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Snapchat ### GET /snapchat/profile Get Snapchat user profile Credit cost: 1 (standard) Parameters: - handle (required) — Snapchat username ``` curl "https://www.socialcrawl.dev/v1/snapchat/profile?handle=djkhaled305" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Spotify ### GET /spotify/artist Get a Spotify artist (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Spotify artist ID. - url (optional, string) — Spotify artist URL. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/spotify/artist?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /spotify/track Get a Spotify track (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Spotify track ID. - url (optional, string) — Spotify track URL. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/spotify/track?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /spotify/album Get a Spotify album (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Spotify album ID. - url (optional, string) — Spotify album URL. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/spotify/album?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /spotify/search Search Spotify Credit cost: 1 (standard) Parameters: - query (required) — Search query. ``` curl "https://www.socialcrawl.dev/v1/spotify/search?query=my first million" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /spotify/podcast Get a Spotify podcast (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Spotify podcast (show) ID. - url (optional, string) — Spotify podcast (show) URL. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/spotify/podcast?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /spotify/podcast/episodes List a Spotify podcast's episodes (oneOf: id|url) Credit cost: 1 (standard) Parameters: - id (optional, string) — Spotify podcast (show) ID. - url (optional, string) — Spotify podcast (show) URL. - cursor (optional, integer) — Cursor returned by the previous response. Omit for page 1. - Constraint: one of id, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Tavily ### GET /tavily/search Tavily web search with optional LLM-generated answer Credit cost: 1 (standard) Parameters: - query (required) — The search query — natural-language free text. - search_depth (optional, enum: basic | advanced | fast | ultra-fast) — Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking. - topic (optional, enum: general | news | finance) — Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data. - time_range (optional, enum: day | week | month | year | d | w | m | y) — Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`). - max_results (optional, integer) — Number of results to return (1–20). Defaults to 5. - chunks_per_source (optional, integer) — Max relevant chunks returned per source (1–5). Only honoured when `search_depth=advanced`. Defaults to 3. - include_images (optional, boolean) — Include images alongside the result content. - include_image_descriptions (optional, boolean) — Include AI-generated descriptions for the returned images. - include_answer (optional, boolean) — Include an LLM-generated answer string synthesised from the top sources. - include_raw_content (optional, boolean) — Include the raw HTML/text alongside the cleaned content. - include_domains (optional, string) — Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`). - exclude_domains (optional, string) — Comma-separated list of domains to exclude from results. - country (optional, string) — ISO 3166-1 alpha-2 country code to bias results toward. - start_date (optional, string) — Inclusive lower bound on result publish date (YYYY-MM-DD). - end_date (optional, string) — Inclusive upper bound on result publish date (YYYY-MM-DD). ``` curl "https://www.socialcrawl.dev/v1/tavily/search?query=claude opus 4.7 release notes" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tavily/extract Extract clean content from one or more URLs Credit cost: 1 (standard) Parameters: - urls (required) — Comma-separated list of URLs to extract (max 20). - extract_depth (optional, enum: basic | advanced) — Extraction strategy. `basic` is the default and faster; `advanced` handles harder pages but takes longer. - format (optional, enum: markdown | text) — Output format for the extracted content. `markdown` (default) preserves structure; `text` is plain. - include_images (optional, boolean) — Include images extracted from each URL. - include_favicon (optional, boolean) — Include the favicon URL for each page. - timeout (optional, integer) — Per-URL timeout in seconds (1–60). ``` curl "https://www.socialcrawl.dev/v1/tavily/extract?urls=https://en.wikipedia.org/wiki/Lionel_Messi" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tavily/map Map a website's sitegraph Credit cost: 1 (standard) Parameters: - url (required) — Root URL to begin mapping. - max_depth (optional, integer) — Maximum link depth from the root URL. Defaults to 1. - max_breadth (optional, integer) — Maximum number of links followed per level (per page). Defaults to 20. - limit (optional, integer) — Total number of links the mapper will process before stopping. Defaults to 50. - instructions (optional, string) — Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation'). - select_paths (optional, string) — Comma-separated regex patterns — only include URLs whose path matches. - select_domains (optional, string) — Comma-separated regex patterns — only include URLs whose domain matches. - exclude_paths (optional, string) — Comma-separated regex patterns — exclude URLs whose path matches. - exclude_domains (optional, string) — Comma-separated regex patterns — exclude URLs whose domain matches. - allow_external (optional, boolean) — Whether to follow / return links to external domains. Defaults to true. - timeout (optional, integer) — Maximum time in seconds (10–150). - categories (optional, string) — Comma-separated list of category hints to bias mapping toward. ``` curl "https://www.socialcrawl.dev/v1/tavily/map?url=https://docs.tavily.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tavily/crawl Crawl a website with LLM-driven path selection Credit cost: 1 (standard) Parameters: - url (required) — Root URL to begin crawling. - max_depth (optional, integer) — Maximum link depth from the root URL. Defaults to 1. - max_breadth (optional, integer) — Maximum number of links followed per level (per page). Defaults to 20. - limit (optional, integer) — Total number of pages the crawler will process before stopping. Defaults to 50. - instructions (optional, string) — Natural-language instructions for the crawler (e.g. 'Find all product pages with pricing'). - select_paths (optional, string) — Comma-separated regex patterns — only crawl URLs whose path matches. - select_domains (optional, string) — Comma-separated regex patterns — only crawl URLs whose domain matches. - exclude_paths (optional, string) — Comma-separated regex patterns — skip URLs whose path matches. - exclude_domains (optional, string) — Comma-separated regex patterns — skip URLs whose domain matches. - allow_external (optional, boolean) — Whether to follow links to external domains. Defaults to true. - extract_depth (optional, enum: basic | advanced) — Per-page extraction strategy. `basic` is faster; `advanced` handles harder pages. - format (optional, enum: markdown | text) — Output format for extracted content. `markdown` (default) or `text`. - categories (optional, string) — Comma-separated list of category hints to bias the crawl toward. ``` curl "https://www.socialcrawl.dev/v1/tavily/crawl?url=https://docs.tavily.com" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Threads ### GET /threads/profile Get Threads user profile Credit cost: 1 (standard) Parameters: - handle (required) — Threads username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/threads/profile?handle=zuck" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /threads/user/posts List Threads user posts Credit cost: 1 (standard) Parameters: - handle (required) — Threads username without the @ symbol - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/threads/user/posts?handle=zuck" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /threads/post Get Threads post details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Threads post - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/threads/post?url=https://www.threads.net/@zuck/post/CwABCDEFGHI" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /threads/search Search Threads posts Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find Threads posts - start_date (optional, string) — Start date to search for - end_date (optional, string) — End date to search for - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/threads/search?query=artificial intelligence" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /threads/search/users Search Threads users Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find Threads users ``` curl "https://www.socialcrawl.dev/v1/threads/search/users?query=tech" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Tiktok ### GET /tiktok/profile Get TikTok user profile (oneOf: handle|user_id) Credit cost: 1 (standard) Parameters: - handle (optional, string) — TikTok username without the @ symbol. - user_id (optional, string) — TikTok numeric user ID. Use this for faster responses. - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/tiktok/profile?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/profile/videos List TikTok user videos Credit cost: 1 (standard) Parameters: - handle (required) — TikTok username without the @ symbol - user_id (optional, string) — TikTok user id. Use this for faster responses. - sort_by (optional, enum: latest | popular) — What to sort by - max_cursor (optional, string) — Cursor to get more videos. Get 'max_cursor' from previous response. - region (optional, string) — Region (Country) you want the proxy in. Defaults to US. - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/tiktok/profile/videos?handle=charlidamelio" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/post Get TikTok post details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the TikTok video - region (optional, string) — Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc - trim (optional, boolean) — Set to true to get a trimmed response - download_media (optional, boolean) — Set to true to also download the video/images and get back permanent, durable media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving — the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched. ``` curl "https://www.socialcrawl.dev/v1/tiktok/post?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/post/comments List TikTok post comments Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the TikTok video to fetch comments for - cursor (optional, integer) — Cursor to get more comments. Get 'cursor' from previous response. - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/video/comment/replies List TikTok comment replies Credit cost: 1 (standard) Parameters: - comment_id (required) — TikTok comment ID. This is the cid from the comments endpoint. - url (required) — TikTok video URL. This is the url from the comments endpoint. - cursor (optional, integer) — Cursor to get more replies. Get 'cursor' from previous response. ``` curl "https://www.socialcrawl.dev/v1/tiktok/video/comment/replies?comment_id=7623828115408274207&url=https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/comment Look up one TikTok comment by URL or id Credit cost: 2 (override; tier standard) Parameters: - comment_url (optional, string) — A TikTok comment URL: `https://www.tiktok.com/@{handle}/video/{videoId}?comment_id={cid}`, the `m.tiktok.com/v/{id}.html?...&share_comment_id={cid}` share form, or a `vm.tiktok.com/{code}` / `tiktok.com/t/{code}` shortlink. Mutually exclusive with `post_url`+`comment_id`. - post_url (optional, string) — The post URL (`https://www.tiktok.com/@{handle}/video/{videoId}`). Combine with `comment_id`, or with `author_username`/`text_contains` for a search. - comment_id (optional, string) — The target comment's numeric id (the `cid` from the comments endpoint). Requires `post_url`. - parent_comment_id (optional, string) — The parent comment's numeric id — supply this when the target is a reply so it can be resolved directly via the native replies endpoint. - author_username (optional, string) — Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id. - text_contains (optional, string) — Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id. - deep_scan (optional, boolean) — Widen the scan budget for deeply-buried comments (raises the page ceiling and deadline). Bills 6 credits instead of 2. - position_hint (optional, string) — Opaque token from a prior lookup's `lookup.position_hint`. Passing it back probes the comment's last-known location first, making a re-check of an already-found comment cheap. - max (optional, integer) — For `author_username`/`text_contains` search: max matches to return (1–20, default 5). ``` curl "https://www.socialcrawl.dev/v1/tiktok/comment?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/search Search TikTok videos by keyword Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find TikTok videos - date_posted (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame - sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by - region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc - cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response. - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/tiktok/search?query=cooking recipes" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/trending Get TikTok trending feed Credit cost: 5 (advanced) Parameters: - region (required) — ISO 3166-1 alpha-2 country code (e.g., US, GB, KR) - trim (optional, boolean) — Set to true to get a trimmed response. ``` curl "https://www.socialcrawl.dev/v1/tiktok/trending?region=US" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/search/hashtag Search TikTok by hashtag Credit cost: 1 (standard) Parameters: - hashtag (required) — Hashtag to search for without the # symbol - region (optional, string) — Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there. - cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response. - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/tiktok/search/hashtag?hashtag=fyp" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/search/top TikTok top search results Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase - publish_time (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame TikTok was posted - sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by - region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc - cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response. ``` curl "https://www.socialcrawl.dev/v1/tiktok/search/top?query=dance challenge" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/search/users Search TikTok users Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find TikTok users - cursor (optional, integer) — Cursor to get more users. Get 'cursor' from previous response. - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/user/audience Get TikTok user audience demographics Credit cost: 5 (advanced) Parameters: - handle (required) — TikTok username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/tiktok/user/audience?handle=charlidamelio" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/user/followers List TikTok user followers (oneOf: handle|user_id) Credit cost: 1 (standard) Parameters: - handle (optional, string) — TikTok username without the @ symbol - user_id (optional, string) — User id. Use this for faster response times. - min_time (optional, integer) — Used to paginate. Get 'min_time' from previous response. - trim (optional, boolean) — Set to true to get a trimmed response - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/tiktok/user/followers?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/user/following List TikTok user following Credit cost: 1 (standard) Parameters: - handle (required) — TikTok username without the @ symbol - trim (optional, boolean) — Set to true to get a trimmed response ``` curl "https://www.socialcrawl.dev/v1/tiktok/user/following?handle=stoolpresidente" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/user/live Get TikTok user live stream Credit cost: 1 (standard) Parameters: - handle (required) — TikTok username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/tiktok/user/live?handle=charlidamelio" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/post/transcript Get TikTok video transcript Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the TikTok video - language (optional, string) — Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh' - use_ai_as_fallback (optional, string) — Set to 'true' to use AI as a fallback to get the transcript if the transcript is not found. Costs 10 credits to use this feature. And only if the video is under 2 minutes. ``` curl "https://www.socialcrawl.dev/v1/tiktok/post/transcript?url=https://www.tiktok.com/@stoolpresidente/video/7499229683859426602" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/song Get TikTok song details Credit cost: 1 (standard) Parameters: - clipId (required) — TikTok sound/song clip ID ``` curl "https://www.socialcrawl.dev/v1/tiktok/song?clipId=7439295283975702544" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/song/videos List TikTok videos using a song Credit cost: 1 (standard) Parameters: - clipId (optional, string) — TikTok sound/song clip ID - cursor (optional, integer) — The cursor to get the next page of results. ``` curl "https://www.socialcrawl.dev/v1/tiktok/song/videos?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/profile/region Get TikTok profile region Credit cost: 1 (standard) Parameters: - handle (required) — TikTok username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/tiktok/profile/region?handle=stoolpresidente" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktok/profile/full TikTok profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - handle (optional, string) - user_id (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/tiktok/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Tiktokshop ### GET /tiktokshop/product Get TikTok Shop product details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the TikTok Shop product page - region (optional, string) — Region the proxy will be set to so you can access products from that country. Use 2 letter country codes like US, GB, FR, etc. For England, don't use UK, use GB. ``` curl "https://www.socialcrawl.dev/v1/tiktokshop/product?url=https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktokshop/product/reviews List TikTok Shop product reviews (oneOf: url|product_id) Credit cost: 1 (standard) Parameters: - url (optional, string) — Full URL of the TikTok Shop product page - product_id (optional, string) — The ID of the product (required if url is not provided) - region (optional, string) — ISO 3166-1 alpha-2 region for the product (e.g. `US`). Important when the product is regionally scoped. - Constraint: one of url, product_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/tiktokshop/product/reviews?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktokshop/products List TikTok Shop products Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the TikTok Shop page - sort_by (optional, enum: top | new_releases) — Sort products by best-selling (`top`) or newest (`new_releases`). Defaults to `top`. - region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to get shop products from. Defaults to US if not provided. ``` curl "https://www.socialcrawl.dev/v1/tiktokshop/products?url=https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktokshop/search Search TikTok Shop products Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase to find TikTok Shop products - page (optional, integer) — Page number to retrieve - region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to search shop products in. ``` curl "https://www.socialcrawl.dev/v1/tiktokshop/search?query=phone case" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tiktokshop/user/showcase List TikTok user showcase products Credit cost: 1 (standard) Parameters: - handle (required) — The handle of the user - region (optional, string) — Region to put the proxy in - cursor (optional, string) — The cursor to the next page of products ``` curl "https://www.socialcrawl.dev/v1/tiktokshop/user/showcase?handle=mrtiktokreviews" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Tripadvisor ### GET /tripadvisor/search Search TripAdvisor businesses & places Credit cost: 1 (standard) Parameters: - q (required) — Business category, company name, or prominent place (e.g. 'pizza restaurant'). - location (optional, string) — Full location name (e.g. 'New York,New York,United States'). Default: United States. Results are location-bound. - language (optional, string) — Optional language code to narrow results, e.g. 'en'. - depth (optional, integer) — Number of results to retrieve (multiples of 30, default 30, max 60 on this synchronous endpoint). ``` curl "https://www.socialcrawl.dev/v1/tripadvisor/search?q=pizza restaurant" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /tripadvisor/reviews Get TripAdvisor reviews for a place Credit cost: 1 (standard) Parameters: - url_path (required) — The TripAdvisor `url_path` of the place (from a search result), e.g. 'Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html'. - depth (optional, integer) — Number of reviews to retrieve (multiples of 10, default 10, max 30 on this synchronous endpoint). - sort_by (optional, enum: most_recent | detailed_reviews) — Review ordering: `most_recent` or `detailed_reviews`. - rating (optional, enum: excellent | very_good | average | poor | terrible) — Filter by traveler rating bucket: excellent | very_good | average | poor | terrible. - visit_type (optional, enum: families | couples | solo | business | friends) — Filter by traveler type: families | couples | solo | business | friends. - search_reviews_keyword (optional, string) — Only return reviews containing this keyword. - translate (optional, boolean) — Translate reviews to the place's domain language (default true). The `translated` flag + `original_language` are always returned. ``` curl "https://www.socialcrawl.dev/v1/tripadvisor/reviews?url_path=Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Trustpilot ### GET /trustpilot/business-search Search Trustpilot businesses Credit cost: 1 (standard) Parameters: - query (required) — Business name or keyword (e.g. 'nike'). Matches companies, not products; do not pass a bare domain. - depth (optional, integer) — Number of business results to retrieve (default 20, multiples of 10, max 140). More results = longer task time. ``` curl "https://www.socialcrawl.dev/v1/trustpilot/business-search?query=nike" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /trustpilot/reviews Get Trustpilot reviews for a business Credit cost: 5 (advanced) Parameters: - domain (required) — The business's domain on Trustpilot (e.g. 'www.nike.com' or 'booking.com'), from business-search. - depth (optional, integer) — Number of reviews to retrieve (default 20, multiples of 20, max 200). There is no pagination beyond 200. - sort (optional, enum: recency | relevance) — Review ordering: `recency` (newest first, default) or `relevance`. ``` curl "https://www.socialcrawl.dev/v1/trustpilot/reviews?domain=www.nike.com" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Truthsocial ### GET /truthsocial/profile Get Truth Social user profile Credit cost: 1 (standard) Parameters: - handle (required) — Truth Social username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/truthsocial/profile?handle=realDonaldTrump" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /truthsocial/user/posts List Truth Social user posts (oneOf: handle|user_id) Credit cost: 1 (standard) Parameters: - handle (optional, string) — Truth Social username without the @ symbol - user_id (optional, string) — Truth Social user id. Use this for faster response times. Trumps is 107780257626128497. It is the 'id' field in the profile endpoint. - next_max_id (optional, string) — Used to paginate to next page - trim (optional, boolean) — Set to true for a trimmed down version of the response - Constraint: one of handle, user_id (at least one required) ``` curl "https://www.socialcrawl.dev/v1/truthsocial/user/posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /truthsocial/post Get Truth Social post details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Truth Social post ``` curl "https://www.socialcrawl.dev/v1/truthsocial/post?url=https://truthsocial.com/@realDonaldTrump/posts/123456789" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Twitch ### GET /twitch/profile Get Twitch streamer profile Credit cost: 1 (standard) Parameters: - handle (required) — Twitch username ``` curl "https://www.socialcrawl.dev/v1/twitch/profile?handle=ninja" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitch/clip Get Twitch clip details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Twitch clip ``` curl "https://www.socialcrawl.dev/v1/twitch/clip?url=https://www.twitch.tv/ninja/clip/ExampleClipSlug" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitch/user/videos List a Twitch user's videos Credit cost: 1 (standard) Parameters: - handle (required) — Twitch username. - filter_by (optional, enum: HIGHLIGHT | UPLOAD) — Filter the returned videos by type — `HIGHLIGHT` or `UPLOAD`. (Archived past broadcasts are not currently available upstream.) - sort_by (optional, enum: TIME | VIEWS) — Sort order — `TIME` (newest first) or `VIEWS`. ``` curl "https://www.socialcrawl.dev/v1/twitch/user/videos?handle=ishowspeed" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitch/user/schedule Get a Twitch user's stream schedule Credit cost: 1 (standard) Parameters: - handle (required) — Twitch username. ``` curl "https://www.socialcrawl.dev/v1/twitch/user/schedule?handle=kaicenat" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Twitter ### GET /twitter/profile Get Twitter user profile Credit cost: 1 (standard) Parameters: - handle (required) — Twitter username without the @ symbol ``` curl "https://www.socialcrawl.dev/v1/twitter/profile?handle=elonmusk" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/user/tweets List Twitter user tweets Credit cost: 1 (standard) Parameters: - handle (required) — Twitter username without the @ symbol - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/twitter/user/tweets?handle=elonmusk" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/tweet Get Twitter tweet details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the tweet - trim (optional, boolean) — Set to true for a trimmed down version of the response ``` curl "https://www.socialcrawl.dev/v1/twitter/tweet?url=https://x.com/elonmusk/status/1234567890" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/community Get Twitter community details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Twitter/X community ``` curl "https://www.socialcrawl.dev/v1/twitter/community?url=https://x.com/i/communities/1926186499399139650" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/community/tweets List Twitter community tweets Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the Twitter/X community ``` curl "https://www.socialcrawl.dev/v1/twitter/community/tweets?url=https://x.com/i/communities/1234567890" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/tweet/transcript Get Twitter video transcript Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the tweet containing a video ``` curl "https://www.socialcrawl.dev/v1/twitter/tweet/transcript?url=https://x.com/TheoVon/status/1916982720317821050" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/ai-search AI-powered X (Twitter) search via xAI Grok Credit cost: 5 (advanced) Parameters: - query (required) — Natural-language prompt describing what you want to learn from X. The model autonomously searches X using the x_search tool with any handle / date filters you provide. - from_handles (optional, string) — Comma-separated X handles (max 10). Restricts the search to posts from these accounts only. Mutually exclusive with exclude_handles. - exclude_handles (optional, string) — Comma-separated X handles (max 10) to exclude from search results. Mutually exclusive with from_handles. - from_date (optional, string) — ISO 8601 start date (YYYY-MM-DD). Limits the search window to posts on or after this date. - to_date (optional, string) — ISO 8601 end date (YYYY-MM-DD). Limits the search window to posts on or before this date. ``` curl "https://www.socialcrawl.dev/v1/twitter/ai-search?query=What is @elonmusk saying about xAI this week?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /twitter/profile/full X (Twitter) profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - handle (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/twitter/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Utility ### GET /utility/age-gender Detect age and gender Credit cost: 10 (premium) Parameters: - url (required) — Social profile URL whose avatar should be analyzed (e.g. a Twitter/X profile URL) ``` curl "https://www.socialcrawl.dev/v1/utility/age-gender?url=https://twitter.com/levelsio" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Web ### GET /web/scrape Scrape a web page Credit cost: 1 (override; tier standard) Parameters: - url (required) — Public URL to fetch. - formats (optional, string) — Comma-separated output formats such as markdown,screenshot. - only_main_content (optional, boolean) - wait_for (optional, integer) - mobile (optional, boolean) - timeout (optional, integer) - max_age (optional, integer) - location_country (optional, string) - screenshot_full_page (optional, boolean) - include_tags (optional, string) - exclude_tags (optional, string) - proxy (optional, enum: basic | auto | enhanced) — Proxy tier: basic, auto, or enhanced. - pdf_parse (optional, boolean) - block_ads (optional, boolean) - remove_base64_images (optional, boolean) ``` curl "https://www.socialcrawl.dev/v1/web/scrape?url=https://example.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/search Search the web Credit cost: 2 (override; tier standard) Parameters: - query (required) — Search query. - sources (optional, string) — Comma-separated sources: web,news,images. - categories (optional, string) - limit (optional, integer) — Results per source, from 1 to 100. - country (optional, string) - location (optional, string) - time_range (optional, string) - sort_by_date (optional, boolean) - include_domains (optional, string) - exclude_domains (optional, string) - include_content (optional, boolean) ``` curl "https://www.socialcrawl.dev/v1/web/search?query=social media data api" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/map Map URLs on a site Credit cost: 1 (override; tier standard) Parameters: - url (required) — Site URL to map. - search (optional, string) — Optional path or keyword filter. - limit (optional, integer) — Maximum URLs to return, up to 5000. - sitemap (optional, enum: include | skip | only) - include_subdomains (optional, boolean) - ignore_query_parameters (optional, boolean) - fresh (optional, boolean) ``` curl "https://www.socialcrawl.dev/v1/web/map?url=https://example.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/extract Extract structured data from a web page (oneOf: schema|prompt) Credit cost: 5 (override; tier advanced) Parameters: - url (required) — Public URL to extract from. - schema (optional, string) — JSON object schema describing the data to return. - prompt (optional, string) — Plain-language extraction instruction. - only_main_content (optional, boolean) - timeout (optional, integer) - max_age (optional, integer) - proxy (optional, enum: basic | auto | enhanced) - Constraint: one of schema, prompt (at least one required) ``` curl "https://www.socialcrawl.dev/v1/web/extract?url=https://example.com/pricing" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/crawl Start an async web crawl Credit cost: 1 (override; tier standard) Parameters: - url (required) — Root URL to crawl. - limit (optional, integer) — Maximum pages to crawl. - max_depth (optional, integer) - allow_backward_links (optional, boolean) - allow_external_links (optional, boolean) - include_paths (optional, string) - exclude_paths (optional, string) - webhook_url (optional, string) — Optional webhook URL for terminal job updates. - formats (optional, string) ``` curl "https://www.socialcrawl.dev/v1/web/crawl?url=https://example.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/batch-scrape Start an async batch scrape Credit cost: 1 (override; tier standard) Parameters: - urls (required) — Array or comma-separated list of public URLs to scrape. - ignore_invalid_urls (optional, boolean) — Skip invalid URLs instead of failing the job. - formats (optional, string) - only_main_content (optional, boolean) - proxy (optional, enum: basic | auto | enhanced) - webhook_url (optional, string) ``` curl "https://www.socialcrawl.dev/v1/web/batch-scrape?urls=https://example.com/a,https://example.com/b" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/jobs List async web jobs Credit cost: 0 (override; tier standard) Parameters: - limit (optional, integer) — Page size, capped at 100. - cursor (optional, string) — Previous response cursor. ``` curl "https://www.socialcrawl.dev/v1/web/jobs?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/jobs/{job_id} Get an async web job Credit cost: 0 (override; tier standard) Parameters: - job_id (required) — Job id (job_...) returned by POST /v1/web/crawl, POST /v1/web/batch-scrape, or POST /v1/web/agent as data.job_id. ``` curl "https://www.socialcrawl.dev/v1/web/jobs/{job_id}?job_id=job_9f3k2n8d1" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/jobs/{job_id} Cancel an async web job Credit cost: 0 (override; tier standard) Parameters: - job_id (required) — Job id (job_...) returned by POST /v1/web/crawl, POST /v1/web/batch-scrape, or POST /v1/web/agent as data.job_id. ``` curl "https://www.socialcrawl.dev/v1/web/jobs/{job_id}?job_id=job_9f3k2n8d1" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/agent Start an async web agent job Credit cost: 25 (override; tier premium) Parameters: - url (required) — Starting URL folded into the agent instruction. - prompt (required) — Task instruction. - model (optional, enum: spark-1-mini | spark-1-pro) — Firecrawl Spark model: spark-1-mini or spark-1-pro. ``` curl "https://www.socialcrawl.dev/v1/web/agent?url=https://example.com&prompt=Find the pricing page." \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors Create a web monitor Credit cost: 0 (override; tier standard) Parameters: - url (required) — URL or root target to monitor. - name (optional, string) — Human-readable monitor name. - mode (optional, enum: scrape | search) — Monitor target type. - cadence_minutes (optional, integer) — Check interval in minutes: 5-60, or a whole number of hours up to 1440 (120, 180, ...). Hour cadences are scheduled as cron. - schedule_text (optional, string) — Plain-language schedule, such as every 15 minutes. - schedule_cron (optional, string) — Cron schedule. Mutually exclusive with schedule_text. - timezone (optional, string) — IANA timezone for the schedule. - webhook_url (optional, string) - query (optional, string) - goal (optional, string) - retention_days (optional, integer) - judge_enabled (optional, boolean) ``` curl "https://www.socialcrawl.dev/v1/web/monitors?url=https://example.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors List web monitors Credit cost: 0 (override; tier standard) Parameters: - cursor (optional, string) — Pagination cursor. - limit (optional, integer) — Page size. ``` curl "https://www.socialcrawl.dev/v1/web/monitors?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors/{monitor_id} Get a web monitor Credit cost: 0 (override; tier standard) Parameters: - monitor_id (required) — Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id. ``` curl "https://www.socialcrawl.dev/v1/web/monitors/{monitor_id}?monitor_id=wm_5d1p8s3k7" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors/{monitor_id} Update a web monitor Credit cost: 0 (override; tier standard) Parameters: - monitor_id (required) — Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id. - status (optional, enum: active | paused) - cadence_minutes (optional, integer) - schedule_text (optional, string) - schedule_cron (optional, string) - timezone (optional, string) ``` curl "https://www.socialcrawl.dev/v1/web/monitors/{monitor_id}?monitor_id=wm_5d1p8s3k7" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors/{monitor_id} Delete a web monitor Credit cost: 0 (override; tier standard) Parameters: - monitor_id (required) — Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id. ``` curl "https://www.socialcrawl.dev/v1/web/monitors/{monitor_id}?monitor_id=wm_5d1p8s3k7" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/monitors/{monitor_id}/checks List web monitor checks Credit cost: 0 (override; tier standard) Parameters: - monitor_id (required) — Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id. - limit (optional, integer) ``` curl "https://www.socialcrawl.dev/v1/web/monitors/{monitor_id}/checks?monitor_id=wm_5d1p8s3k7" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/sessions Create an interactive web session Credit cost: 5 (override; tier advanced) Parameters: - url (required) — URL to open in the session after creation. - ttl_seconds (optional, integer) — Session TTL in seconds. - activity_ttl_seconds (optional, integer) - stream_web_view (optional, boolean) ``` curl "https://www.socialcrawl.dev/v1/web/sessions?url=https://example.com" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/sessions List interactive web sessions Credit cost: 0 (override; tier standard) Parameters: - limit (optional, integer) — Page size. ``` curl "https://www.socialcrawl.dev/v1/web/sessions?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/sessions/{session_id} Get an interactive web session Credit cost: 0 (override; tier standard) Parameters: - session_id (required) — Session id (ws_...) returned by POST /v1/web/sessions as data.session_id. ``` curl "https://www.socialcrawl.dev/v1/web/sessions/{session_id}?session_id=ws_3g7x1v5m2" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/sessions/{session_id}/execute Execute an interaction in a web session Credit cost: 0 (override; tier standard) Parameters: - session_id (required) — SocialCrawl session id. - code (required) — Code to execute in the browser sandbox. - language (optional, enum: node | python | bash) — Execution language: node, python, or bash. - timeout (optional, integer) — Execution timeout in seconds. ``` curl "https://www.socialcrawl.dev/v1/web/sessions/{session_id}/execute?session_id=ws_3g7x1v5m2&code=await page.goto("https://example.com"); console.log(await page.title());" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/sessions/{session_id} Close an interactive web session Credit cost: 0 (override; tier standard) Parameters: - session_id (required) — Session id (ws_...) returned by POST /v1/web/sessions as data.session_id. ``` curl "https://www.socialcrawl.dev/v1/web/sessions/{session_id}?session_id=ws_3g7x1v5m2" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /web/parse Parse an uploaded document Credit cost: 1 (override; tier standard) Parameters: - file (required) — Multipart file field. - filename (optional, string) - mime_type (optional, string) — Optional MIME type override. - url (optional, string) ``` curl "https://www.socialcrawl.dev/v1/web/parse?file=document.pdf" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Youtube ### GET /youtube/channel Get YouTube channel info (oneOf: channelId|handle|url) Credit cost: 1 (standard) Parameters: - channelId (optional, string) — YouTube channel ID. Can pass a channelId, handle or url - handle (optional, string) — YouTube channel handle without the @ symbol - url (optional, string) — YouTube channel URL. Can pass a channelId, handle or url - hl (optional, string) — Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr'). - forUsername (optional, string) — Legacy YouTube username (pre-handle) to look up. - Constraint: one of channelId, handle, url (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channel/videos List YouTube channel videos (oneOf: channelId|handle) Credit cost: 1 (standard) Parameters: - channelId (optional, string) — YouTube channel ID - handle (optional, string) — YouTube channel handle without the @ symbol - sort (optional, enum: latest | popular) — Sort by latest or popular - continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response. - includeExtras (optional, string) — This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly. - is_paid_promotions (optional, string) — Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement surface — returns normal videos where the creator disclosed a paid promotion. - Constraint: one of channelId, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel/videos?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video Get YouTube video details Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the YouTube video - language (optional, string) — Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc. - hl (optional, string) — Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr'). ``` curl "https://www.socialcrawl.dev/v1/youtube/video?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/videos Batch get YouTube video details (up to 1000) Credit cost: 5 (advanced) Parameters: - ids (required) — JSON array of BARE YouTube video ids (11 characters each, e.g. 'dQw4w9WgXcQ'), 1 to 1000 per request. Unlike GET /v1/youtube/video, full watch URLs are not accepted here. - hl (optional, string) — Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko'). - include_localizations (optional, boolean) — When true, includes per-language title/description localizations in each item's ext. ``` curl "https://www.socialcrawl.dev/v1/youtube/videos?ids=dQw4w9WgXcQ,9bZkp7q19f0" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channels Batch get YouTube channel details (up to 1000) Credit cost: 5 (advanced) Parameters: - ids (required) — JSON array of BARE YouTube channel ids (24 characters, starting with 'UC', e.g. 'UC_x5XG1OV2P6uZZ5FSM9Ttw'), 1 to 1000 per request. Unlike GET /v1/youtube/channel, channel URLs/handles are not accepted here. - hl (optional, string) — Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko'). - include_localizations (optional, boolean) — When true, includes per-language localizations in each item's ext. ``` curl "https://www.socialcrawl.dev/v1/youtube/channels?ids=UC_x5XG1OV2P6uZZ5FSM9Ttw,UCX6OQ3DkcsbYNE6H8uQQuVA" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/transcripts Up to 100 YouTube video ids → one transcript per row, failed ids refunded. Credit cost: 3 (override; tier standard) Parameters: - ids (required) — JSON array of 1–100 BARE YouTube video ids (11 characters each, e.g. 'dQw4w9WgXcQ'). Full watch URLs are not accepted here. - language (optional, string) — Preferred caption-track language (2-letter code, e.g. 'en', 'ko'). Falls back to the default track when absent or unavailable. - format (optional, string) — `text` (default) returns the whole transcript as one joined string; `segments` returns timestamped `[{start_ms, duration_ms, text}]`. ``` curl "https://www.socialcrawl.dev/v1/youtube/transcripts?ids=dQw4w9WgXcQ,9bZkp7q19f0" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/sponsors Detect sponsors of a YouTube video Credit cost: 10 (premium) Parameters: - url (required) — Full URL of the YouTube video or short - language (optional, string) — 2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/sponsors?url=https://www.youtube.com/watch?v=AVO0ifle-OU" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/comments List YouTube video comments Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the YouTube video to fetch comments for - continuationToken (optional, string) — Continuation token to get more comments. Get 'continuationToken' from previous response. - order (optional, enum: top | newest) — Order of comments - searchTerm (optional, string) — Filter comments to those containing this search term. - format (optional, enum: html | plainText) — Text format for comment bodies — 'html' (default) or 'plainText'. - max_results (optional, integer) — Maximum number of comments to return per page. - channel_id (optional, string) — YouTube channel id to fetch channel-level community comments for (instead of a video's comments). ``` curl "https://www.socialcrawl.dev/v1/youtube/video/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/comment/replies List YouTube comment replies Credit cost: 1 (standard) Parameters: - continuationToken (required) — Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate. - format (optional, enum: html | plainText) — Text format for reply bodies — 'html' (default) or 'plainText'. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/comment/replies?continuationToken=Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIa..." \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/search Search YouTube Credit cost: 1 (standard) Parameters: - query (required) — Search keyword or phrase. - uploadDate (optional, enum: today | this_week | this_month | this_year) — Upload date filter. - sortBy (optional, enum: relevance | popular) — Sort order — relevance or popular. - type (optional, enum: videos | shorts | channels | playlists) — Type of content to return. - duration (optional, enum: under_3_min | between_3_and_20_min | over_20_min) — Video duration filter. Only applies to videos (not shorts). - region (optional, string) — 2-letter country code of the country to put the proxy in. - continuationToken (optional, string) — Continuation token to get more results. Get `continuationToken` from a previous response. - includeExtras (optional, string) — Set to `true` to include like + comment count and description. For full per-video details use `/v1/youtube/video`. Slows the response slightly. ``` curl "https://www.socialcrawl.dev/v1/youtube/search?query=javascript tutorial" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channel/shorts List YouTube channel shorts (oneOf: channelId|handle) Credit cost: 1 (standard) Parameters: - handle (optional, string) — YouTube channel handle without the @ symbol - channelId (optional, string) — Can pass channelId or handle - sort (optional, enum: newest | popular) — Sort by newest or popular - continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response. - Constraint: one of channelId, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel/shorts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/community-post Get YouTube community post Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the YouTube community post ``` curl "https://www.socialcrawl.dev/v1/youtube/community-post?url=https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/playlist Get YouTube playlist Credit cost: 1 (standard) Parameters: - playlist_id (required) — YouTube playlist ID - cursor (optional, string) — Pagination cursor from a previous response — fetches the next page. - channel_id (optional, string) — YouTube channel id — pages that channel's uploads instead of a playlist. ``` curl "https://www.socialcrawl.dev/v1/youtube/playlist?playlist_id=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/search/hashtag Search YouTube by hashtag Credit cost: 1 (standard) Parameters: - hashtag (required) — Hashtag to search for without the # symbol - continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response. - type (optional, enum: all | shorts) — Search for all types of content or only shorts ``` curl "https://www.socialcrawl.dev/v1/youtube/search/hashtag?hashtag=shorts" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/shorts/trending Get trending YouTube shorts Credit cost: 5 (advanced) ``` curl "https://www.socialcrawl.dev/v1/youtube/shorts/trending?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/transcript Get YouTube video transcript Credit cost: 3 (override; tier standard) Parameters: - url (required) — Full URL of the YouTube video - language (optional, string) — 2 letter language code, ie 'en', 'es', 'fr' etc. If no caption track matches the language you specify, the request returns 404 RESOURCE_NOT_FOUND (reason `no_captions`) at 0 credits. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channel/playlists List a YouTube channel's playlists (oneOf: channelId|handle) Credit cost: 1 (standard) Parameters: - channelId (optional, string) — YouTube channel ID. - handle (optional, string) — YouTube channel handle (with or without @). - continuationToken (optional, string) — Continuation token from a previous response — fetches the next page. - Constraint: one of channelId, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel/playlists?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channel/lives List a YouTube channel's live streams (oneOf: channelId|handle) Credit cost: 1 (standard) Parameters: - channelId (optional, string) — YouTube channel ID. - handle (optional, string) — YouTube channel handle (with or without @). - continuationToken (optional, string) — Continuation token from a previous response — fetches the next page. - Constraint: one of channelId, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel/lives?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/channel/community-posts List a YouTube channel's community posts (oneOf: channelId|handle) Credit cost: 1 (standard) Parameters: - channelId (optional, string) — YouTube channel ID. - handle (optional, string) — YouTube channel handle (with or without @). - continuationToken (optional, string) — Continuation token from a previous response — fetches the next page. - Constraint: one of channelId, handle (at least one required) ``` curl "https://www.socialcrawl.dev/v1/youtube/channel/community-posts?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/videos/trending Get trending YouTube videos Credit cost: 1 (standard) Parameters: - region (optional, string) — ISO 3166-1 alpha-2 country code (e.g. US, GB, KR). - category (optional, string) — YouTube video category id (e.g. 10 = Music, 24 = Entertainment). - language (optional, string) — Localization language (ISO 639-1) for titles/metadata. - max_results (optional, integer) — Maximum number of videos to return (1–50). - cursor (optional, string) — Pagination cursor from a previous response — fetches the next page. ``` curl "https://www.socialcrawl.dev/v1/youtube/videos/trending?" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/playlist/items List the videos in a YouTube playlist Credit cost: 1 (standard) Parameters: - playlist_id (required) — YouTube playlist id (the value after `list=` in a playlist URL). - cursor (optional, string) — Pagination cursor from a previous response — fetches the next page. - channel_id (optional, string) — YouTube channel id — pages that channel's uploads instead of a playlist. ``` curl "https://www.socialcrawl.dev/v1/youtube/playlist/items?playlist_id=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/search/advanced Advanced YouTube video search Credit cost: 1 (standard) Parameters: - query (required) — Search query. - order (optional, string) — Sort order: date, rating, relevance (default), title, videoCount, viewCount. - duration (optional, string) — Video length: short (<4m), medium (4–20m), long (>20m), any. - event_type (optional, string) — Broadcast type: live, upcoming, completed. - license (optional, string) — License filter: creativeCommon, youtube, any. - category (optional, string) — YouTube video category id (e.g. 10 = Music). - region (optional, string) — ISO 3166-1 alpha-2 country code. - language (optional, string) — Preferred result language (ISO 639-1). - published_after (optional, string) — RFC-3339 datetime lower bound (e.g. 2026-01-01T00:00:00Z). - published_before (optional, string) — RFC-3339 datetime upper bound. - channel_id (optional, string) — Restrict results to a single channel id. - max_results (optional, integer) — Maximum number of videos to return (1–50). - cursor (optional, string) — Pagination cursor from a previous response — fetches the next page. - safe_search (optional, string) — Safe-search filter: none, moderate, strict. - video_caption (optional, string) — Caption filter: any, closedCaption, none. - video_definition (optional, string) — Quality filter: any, high, standard. - video_dimension (optional, string) — Dimension filter: 2d, 3d, any. - video_embeddable (optional, string) — Restrict to embeddable videos: true, any. - video_type (optional, string) — Type filter: any, episode, movie. - topic_id (optional, string) — Restrict to a Freebase topic id (e.g. /m/04rlf for music). - location (optional, string) — Latitude,longitude center for a geo search (e.g. 37.42307,-122.08427). Must be used together with location_radius. - location_radius (optional, string) — Radius around location with a unit suffix (e.g. 50km, 10mi). Must be used together with location. ``` curl "https://www.socialcrawl.dev/v1/youtube/search/advanced?query=lofi hip hop" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/search/suggestions Get YouTube search suggestions Credit cost: 1 (standard) Parameters: - query (required) — Partial search query to autocomplete. - region (optional, string) — ISO 3166-1 alpha-2 country code to localize suggestions. ``` curl "https://www.socialcrawl.dev/v1/youtube/search/suggestions?query=lofi" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/audio Get a YouTube video's audio file streams Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the YouTube video. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/audio?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/files Get a YouTube video's video file streams Credit cost: 5 (advanced) Parameters: - url (required) — Full URL of the YouTube video. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/files?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/subtitles Get a YouTube video's subtitle files Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the YouTube video. - format (optional, string) — Subtitle file format filter (e.g. srt, vtt, ttml, json3, srv1). ``` curl "https://www.socialcrawl.dev/v1/youtube/video/subtitles?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/video/thumbnails Get a YouTube video's thumbnail files Credit cost: 1 (standard) Parameters: - url (required) — Full URL of the YouTube video. ``` curl "https://www.socialcrawl.dev/v1/youtube/video/thumbnails?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \ -H "x-api-key: sc_your_api_key_here" ``` ### GET /youtube/profile/full YouTube profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - handle (optional, string) - channelId (optional, string) - url (optional, string) - posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25). - cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window. - include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. ``` curl "https://www.socialcrawl.dev/v1/youtube/profile/full?" \ -H "x-api-key: sc_your_api_key_here" ``` --- ## Error Codes | Code | Status | Description | |---|---|---| | MISSING_API_KEY | 401 | No x-api-key header provided | | INVALID_API_KEY | 401 | API key is malformed or not found | | INSUFFICIENT_CREDITS | 402 | Not enough credits — purchase more at https://www.socialcrawl.dev | | INVALID_REQUEST | 400 | Missing required parameters | | ENDPOINT_NOT_FOUND | 404 | Unknown platform or resource | | RESOURCE_NOT_FOUND | 404 | The requested item was not found on the platform | | CONCURRENCY_LIMIT | 429 | Too many simultaneous requests (max 50 per key) | | UPSTREAM_ERROR | 502 | Platform returned an error — credits refunded | | SERVICE_UNAVAILABLE | 503 | Circuit breaker open — try again shortly, credits refunded | | INTERNAL_ERROR | 500 | Unexpected error — credits refunded |