{ "openapi": "3.1.0", "info": { "title": "ScrapeField API", "version": "1.0.0", "summary": "One API for Google Maps, LinkedIn, Instagram and TikTok.", "description": "One key, one invoice, four platforms — and each platform's data in its own shape. A Google Maps place is named the way Google's Places API names it, an Instagram post the way the Graph API does, a TikTok video the way TikTok's own APIs do; LinkedIn, which has no public data API, uses the words on its pages.\n\n**Conventions.** The same everywhere: the `{ data, meta }` envelope, snake_case, ISO 8601 UTC timestamps, the platform's own ids as strings, and every documented key present on every object.\n\n**Pricing.** Every endpoint has a published credit cost, carried here as `x-credits`. Multiply by your volume to get your bill — there are no plans and no tiers, just credits. A call we fail is refunded automatically and the reversal appears in your usage ledger.\n\n**Pagination.** Cursor only. Pass `meta.next_cursor` back as `cursor`; `null` means the last page.\n\n**Nulls.** A field is `null` when the platform does not expose it — never 0 and never a guess.", "contact": { "name": "Support", "url": "https://scrapefield.com/support" } }, "servers": [ { "url": "https://scrapefield.com/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Google Maps" }, { "name": "LinkedIn" }, { "name": "Instagram" }, { "name": "TikTok" } ], "paths": { "/google-maps/places": { "get": { "operationId": "search_places", "summary": "Search Google Maps for businesses and places", "description": "Find businesses and places on Google Maps by a text query, optionally around a point. Each result is the full listing: place_id, name, categories, formatted_address, location, rating and user_ratings_total, phone, website, opening_hours and business_status — named as in Google's Places API. Use this to build a list of businesses in an area; use google-maps/place when you already have a place_id.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 3, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_places", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What to search for, e.g. \"coffee shops in Brooklyn\" or \"dentist\".", "schema": { "type": "string", "example": "coffee shops in Brooklyn" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of the point to search around.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of the point to search around.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "radius_m", "in": "query", "required": false, "description": "Search radius in metres around lat/lng.", "schema": { "type": "integer", "minimum": 100, "maximum": 50000, "default": 5000 } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter country code to bias results, e.g. `us`.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Two-letter language code for localised text, e.g. `en`, `de`.", "schema": { "type": "string", "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/google_maps_place" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/place": { "get": { "operationId": "get_place", "summary": "Get one Google Maps place in full", "description": "Fetch one Google Maps listing in full: name, categories, formatted_address, location, rating, user_ratings_total, rating_distribution, price_level, phone numbers, website, opening_hours, popular_times, the About tab and business_status. Accepts a Google place_id — from a search, the Places API or anywhere else — or a Google Maps URL.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 3, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_place", "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID, e.g. from a search result or the Places API.", "schema": { "type": "string", "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" } }, { "name": "url", "in": "query", "required": false, "description": "A Google Maps URL for the place.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Two-letter language code for localised text, e.g. `en`, `de`.", "schema": { "type": "string", "default": "en" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/google_maps_place" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/reviews": { "get": { "operationId": "get_place_reviews", "summary": "Get the reviews for a place", "description": "Fetch Google reviews for one place: rating, text, language, publish_time, the author (with their Local Guide badge and review count), photos and the owner_response where there is one. Use this for review monitoring and sentiment work.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 3, "x-cache-ttl-seconds": 21600, "x-mcp-tool": "get_place_reviews", "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID.", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "A Google Maps URL for the place.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Order of the reviews.", "schema": { "type": "string", "enum": [ "relevant", "newest", "highest", "lowest" ], "default": "relevant" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/google_maps_review" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/photos": { "get": { "operationId": "get_place_photos", "summary": "Get the photos for a place", "description": "Fetch the photos on one place's listing: URL, dimensions and who uploaded each. The URLs point at Google's CDN; we do not rehost images.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 2 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 2, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_place_photos", "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID.", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "A Google Maps URL for the place.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/google_maps_photo" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/profile": { "get": { "operationId": "get_linkedin_profile", "summary": "Get a public LinkedIn profile", "description": "Fetch a public LinkedIn profile: full_name, headline, about, location, follower_count, connection_count, current_company, experience, education and skills — as a logged-out visitor sees them. Use this to enrich a person from their profile URL.\n\nGive exactly one of `url` or `vanity_name` to identify the profile.\n\nCosts 10 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 10, "x-cache-ttl-seconds": 43200, "x-mcp-tool": "get_linkedin_profile", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The profile URL, e.g. `https://www.linkedin.com/in/someone`.", "schema": { "type": "string", "example": "https://www.linkedin.com/in/example" } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/in/` in the URL, e.g. `someone`.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/linkedin_profile" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/company": { "get": { "operationId": "get_linkedin_company", "summary": "Get a public LinkedIn company page", "description": "Fetch a public LinkedIn company page: name, tagline, description, website, industry, company_size, employees_on_linkedin, headquarters, company_type, founded, specialties and follower_count. Use this to enrich a company from its LinkedIn URL.\n\nGive exactly one of `url` or `vanity_name` to identify the company.\n\nCosts 6 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 6, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_linkedin_company", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The company page URL.", "schema": { "type": "string" } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/company/` in the URL, e.g. `acme-inc`.", "schema": { "type": "string", "example": "example-co" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/linkedin_company" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/posts": { "get": { "operationId": "get_linkedin_posts", "summary": "Get recent posts from a person or company", "description": "Fetch recent public posts by one person or company: text, images, video, document or article, published_at, and reaction_count (with the breakdown by kind), comment_count and repost_count.\n\nGive exactly one of `profile_url` or `company_url` to identify the author.\n\nCosts 6 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 6, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_posts", "parameters": [ { "name": "profile_url", "in": "query", "required": false, "description": "A person's profile URL.", "schema": { "type": "string" } }, { "name": "company_url", "in": "query", "required": false, "description": "A company page URL.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–20.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/linkedin_post" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/jobs": { "get": { "operationId": "search_linkedin_jobs", "summary": "Search public job postings", "description": "Search public LinkedIn job postings by keyword and location. Returns title, company, location, workplace_type, employment_type, seniority_level, salary where shown, listed_at and the description.\n\nCosts 4 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 4, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "search_linkedin_jobs", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Job title or keywords, e.g. \"backend engineer\".", "schema": { "type": "string", "example": "backend engineer" } }, { "name": "location", "in": "query", "required": false, "description": "Place name, e.g. \"Berlin\" or \"United States\".", "schema": { "type": "string" } }, { "name": "workplace_type", "in": "query", "required": false, "description": "Only roles of this kind, as LinkedIn's filter names them.", "schema": { "type": "string", "enum": [ "on-site", "hybrid", "remote" ] } }, { "name": "posted_within_days", "in": "query", "required": false, "description": "Only roles posted in the last N days.", "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–25.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/linkedin_job" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/profile": { "get": { "operationId": "get_instagram_profile", "summary": "Get a public Instagram profile", "description": "Fetch a public Instagram account: username, name, biography, bio_links, followers_count, follows_count, media_count, is_verified, is_private, is_business_account, category and the business contact buttons — named as in Instagram's Graph API. Use this for creator discovery and audience sizing.\n\nGive exactly one of `username` or `url` to identify the profile.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 3, "x-cache-ttl-seconds": 43200, "x-mcp-tool": "get_instagram_profile", "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username, without the leading @.", "schema": { "type": "string", "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/instagram_profile" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/posts": { "get": { "operationId": "get_instagram_posts", "summary": "Get recent posts from a profile", "description": "Fetch recent public posts and Reels by one Instagram account: shortcode, permalink, media_type, caption, timestamp, media_url, carousel children, like_count, comments_count, view_count, hashtags, mentions and the paid-partnership label.\n\nGive exactly one of `username` or `url` to identify the profile.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 3, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_instagram_posts", "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username, without the leading @.", "schema": { "type": "string", "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–24.", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/instagram_post" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/post": { "get": { "operationId": "get_instagram_post", "summary": "Get one post", "description": "Fetch one Instagram post or Reel by its URL or shortcode: caption, media, username, timestamp, like_count, comments_count and view_count.\n\nGive exactly one of `url` or `shortcode` to identify the post.\n\nCosts 2 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 2, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_instagram_post", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post URL.", "schema": { "type": "string" } }, { "name": "shortcode", "in": "query", "required": false, "description": "The shortcode from the URL, e.g. `C1a2B3c4D5e`.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/instagram_post" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/comments": { "get": { "operationId": "get_instagram_comments", "summary": "Get the comments on a post", "description": "Fetch comments on one Instagram post: username, text, timestamp, like_count, reply_count and parent_id for replies. Use this for social listening and campaign verification.\n\nGive exactly one of `url` or `shortcode` to identify the post.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 3, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_instagram_comments", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post URL.", "schema": { "type": "string" } }, { "name": "shortcode", "in": "query", "required": false, "description": "The post shortcode.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/instagram_comment" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/hashtag": { "get": { "operationId": "get_instagram_hashtag", "summary": "Get recent posts for a hashtag", "description": "Fetch recent public posts carrying one hashtag, each a full post. Use this for trend and campaign monitoring.\n\nCosts 4 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 4, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_instagram_hashtag", "parameters": [ { "name": "tag", "in": "query", "required": true, "description": "The hashtag, without the leading #.", "schema": { "type": "string", "example": "sourdough" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–24.", "schema": { "type": "integer", "minimum": 1, "maximum": 24, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/instagram_post" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/profile": { "get": { "operationId": "get_tiktok_profile", "summary": "Get a public TikTok profile", "description": "Fetch a public TikTok account: username, display_name, bio_description, bio_url, is_verified, follower_count, following_count, likes_count and video_count — named as in TikTok's own APIs. Use this for creator discovery and audience sizing.\n\nGive exactly one of `username` or `url` to identify the profile.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 3, "x-cache-ttl-seconds": 43200, "x-mcp-tool": "get_tiktok_profile", "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username, without the leading @.", "schema": { "type": "string", "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/tiktok_profile" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/videos": { "get": { "operationId": "get_tiktok_videos", "summary": "Get recent videos from a profile", "description": "Fetch recent public videos by one TikTok account: video_description, create_time, duration, cover_image_url, view_count, like_count, comment_count, share_count, favorites_count, hashtag_names and the sound.\n\nGive exactly one of `username` or `url` to identify the profile.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 3, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_tiktok_videos", "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username, without the leading @.", "schema": { "type": "string", "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–30.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/tiktok_video" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/video": { "get": { "operationId": "get_tiktok_video", "summary": "Get one video", "description": "Fetch one TikTok video by URL or id: video_description, username, create_time, duration, the counts, the sound and whether duets and stitches are allowed.\n\nGive exactly one of `url` or `id` to identify the video.\n\nCosts 2 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 2, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_tiktok_video", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The video URL.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "The numeric video id.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/tiktok_video" }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/comments": { "get": { "operationId": "get_tiktok_comments", "summary": "Get the comments on a video", "description": "Fetch comments on one TikTok video: username, text, create_time, like_count, reply_count and parent_comment_id for replies.\n\nGive exactly one of `url` or `id` to identify the video.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 3, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_tiktok_comments", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The video URL.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "The numeric video id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/tiktok_comment" } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/search": { "get": { "operationId": "search_tiktok", "summary": "Search TikTok", "description": "Search TikTok by keyword. Returns videos by default; `type=user` returns accounts and `type=hashtag` returns hashtags. Use this for trend research and creator discovery when you do not already have a username.\n\nCosts 4 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 4, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "search_tiktok", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What to search for.", "schema": { "type": "string", "example": "sourdough starter" } }, { "name": "type", "in": "query", "required": false, "description": "What kind of result to return.", "schema": { "type": "string", "enum": [ "video", "user", "hashtag" ], "default": "video" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results to return, 1–30.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": false, "description": "Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/tiktok_video" }, { "$ref": "#/components/schemas/tiktok_profile" }, { "$ref": "#/components/schemas/tiktok_hashtag" } ], "description": "`type=video` returns `tiktok_video`; `type=user` returns `tiktok_profile`; `type=hashtag` returns `tiktok_hashtag`." } }, "meta": { "$ref": "#/components/schemas/meta" } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "429": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key: `Authorization: Bearer sf_live_…`" } }, "responses": { "error": { "description": "Something went wrong. `error.code` is stable; `error.message` says what to do next.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "schemas": { "meta": { "type": "object", "required": [ "request_id", "credits_charged", "cached", "fetched_at", "next_cursor" ], "properties": { "request_id": { "type": "string", "description": "Quote this if you contact support." }, "credits_charged": { "type": "integer", "description": "The endpoint's published cost, or 0 for a call we failed." }, "credits_remaining": { "type": "integer" }, "cached": { "type": "boolean" }, "fetched_at": { "type": "string", "format": "date-time", "description": "When the data was actually fetched — the original time on a cache hit, so freshness is always visible." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page. `null` on the last page." } } }, "google_maps_place": { "type": "object", "required": [ "place_id", "name", "category", "categories", "formatted_address", "address", "location", "plus_code", "rating", "user_ratings_total", "rating_distribution", "price_level", "formatted_phone_number", "international_phone_number", "website", "url", "business_status", "opening_hours", "popular_times", "about", "claimed", "photo" ], "properties": { "place_id": { "type": "string", "description": "Google's place ID — the same one the Places API and every Maps URL use." }, "name": { "type": "string", "description": "As the listing shows it." }, "category": { "type": [ "string", "null" ], "description": "The category printed under the name, e.g. \"Coffee shop\"." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Every category on the listing, the main one first." }, "formatted_address": { "type": [ "string", "null" ], "description": "The address as one line, as Google formats it." }, "address": { "type": "object", "required": [ "street", "city", "region", "postal_code", "country_code" ], "properties": { "street": { "type": [ "string", "null" ], "description": "Street and number." }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ], "description": "State, province or region." }, "postal_code": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2, e.g. `US`." } }, "additionalProperties": false, "description": "The same address in parts." }, "location": { "type": "object", "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." } }, "additionalProperties": false, "description": "The pin." }, "plus_code": { "type": [ "string", "null" ], "description": "The global plus code, e.g. `87G8P2QX+RV`." }, "rating": { "type": [ "number", "null" ], "description": "The star rating, 1.0–5.0. `null` until the place has ratings." }, "user_ratings_total": { "type": [ "integer", "null" ], "description": "How many ratings the star rating is the average of." }, "rating_distribution": { "type": [ "object", "null" ], "required": [ "1", "2", "3", "4", "5" ], "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } }, "additionalProperties": false, "description": "How many ratings of each star value, as the listing's bar chart shows them." }, "price_level": { "type": [ "integer", "null" ], "description": "0 (free) to 4 (very expensive), as the Places API counts it." }, "formatted_phone_number": { "type": [ "string", "null" ], "description": "The phone number in local format." }, "international_phone_number": { "type": [ "string", "null" ], "description": "With the country code, e.g. `+1 718-555-0142`." }, "website": { "type": [ "string", "null" ], "format": "uri", "description": "The business's own site." }, "url": { "type": "string", "format": "uri", "description": "The place on Google Maps." }, "business_status": { "type": "string", "enum": [ "OPERATIONAL", "CLOSED_TEMPORARILY", "CLOSED_PERMANENTLY" ], "description": "As the Places API reports it." }, "opening_hours": { "type": [ "object", "null" ], "required": [ "weekday_text", "periods" ], "properties": { "weekday_text": { "type": "array", "items": { "type": "string" }, "description": "Seven lines, Monday first, as the listing prints them." }, "periods": { "type": "array", "items": { "type": "object", "required": [ "open", "close" ], "properties": { "open": { "type": "object", "required": [ "day", "time" ], "properties": { "day": { "type": "integer", "description": "0 is Sunday." }, "time": { "type": "string", "description": "24-hour `HHMM`, local time." } }, "additionalProperties": false }, "close": { "type": [ "object", "null" ], "required": [ "day", "time" ], "properties": { "day": { "type": "integer", "description": "0 is Sunday." }, "time": { "type": "string", "description": "24-hour `HHMM`, local time." } }, "additionalProperties": false } }, "additionalProperties": false }, "description": "The same hours as data. A place open around the clock has one period with no `close`." } }, "additionalProperties": false, "description": "Regular opening hours. `null` when the listing has none." }, "popular_times": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "day", "busyness" ], "properties": { "day": { "type": "integer", "description": "0 is Sunday." }, "busyness": { "type": "array", "items": { "type": "integer" }, "description": "Twenty-four values, midnight first, 0–100 relative to the place's busiest hour." } }, "additionalProperties": false }, "description": "The \"Popular times\" chart. `null` for places too quiet to have one." }, "about": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "The listing's About tab, by heading: `service_options`, `accessibility`, `amenities`, `payments` and so on — only the headings the place has." }, "claimed": { "type": [ "boolean", "null" ], "description": "Whether the owner has claimed the listing. Unclaimed ones offer \"Own this business?\"." }, "photo": { "type": [ "object", "null" ], "required": [ "url", "width", "height", "author_name", "author_url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The image on Google's CDN. We do not rehost images." }, "width": { "type": [ "integer", "null" ], "description": "Pixels." }, "height": { "type": [ "integer", "null" ], "description": "Pixels." }, "author_name": { "type": [ "string", "null" ], "description": "Who uploaded it, as the listing credits them. `null` for the owner's own photos." }, "author_url": { "type": [ "string", "null" ], "format": "uri", "description": "Their Google Maps contributor page." } }, "additionalProperties": false, "description": "The listing's main photo." } }, "additionalProperties": false, "description": "One business or place, as its Google Maps listing shows it." }, "google_maps_review": { "type": "object", "required": [ "review_id", "place_id", "author", "rating", "text", "language", "publish_time", "like_count", "photos", "owner_response" ], "properties": { "review_id": { "type": "string", "description": "Google's id for the review." }, "place_id": { "type": "string", "description": "The place it is about." }, "author": { "type": "object", "required": [ "name", "url", "profile_photo_url", "is_local_guide", "review_count", "photo_count" ], "properties": { "name": { "type": "string", "description": "As shown on the review." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Their Google Maps contributor page." }, "profile_photo_url": { "type": [ "string", "null" ], "format": "uri" }, "is_local_guide": { "type": "boolean", "description": "Whether they carry the Local Guide badge." }, "review_count": { "type": [ "integer", "null" ], "description": "How many reviews they have written, as the review shows." }, "photo_count": { "type": [ "integer", "null" ], "description": "How many photos they have posted." } }, "additionalProperties": false }, "rating": { "type": "integer", "description": "1 to 5." }, "text": { "type": [ "string", "null" ], "description": "`null` for a rating with no words." }, "language": { "type": [ "string", "null" ], "description": "Two-letter code of the language it was written in." }, "publish_time": { "type": "string", "format": "date-time", "description": "When it was posted." }, "like_count": { "type": [ "integer", "null" ], "description": "How many people marked it helpful." }, "photos": { "type": "array", "items": { "type": "object", "required": [ "url", "width", "height", "author_name", "author_url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The image on Google's CDN. We do not rehost images." }, "width": { "type": [ "integer", "null" ], "description": "Pixels." }, "height": { "type": [ "integer", "null" ], "description": "Pixels." }, "author_name": { "type": [ "string", "null" ], "description": "Who uploaded it, as the listing credits them. `null` for the owner's own photos." }, "author_url": { "type": [ "string", "null" ], "format": "uri", "description": "Their Google Maps contributor page." } }, "additionalProperties": false, "description": "One photo on a place's listing." }, "description": "Photos attached to the review." }, "owner_response": { "type": [ "object", "null" ], "required": [ "text", "publish_time" ], "properties": { "text": { "type": "string" }, "publish_time": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false, "description": "The \"Response from the owner\", where there is one." } }, "additionalProperties": false, "description": "One Google review of a place." }, "google_maps_photo": { "type": "object", "required": [ "url", "width", "height", "author_name", "author_url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The image on Google's CDN. We do not rehost images." }, "width": { "type": [ "integer", "null" ], "description": "Pixels." }, "height": { "type": [ "integer", "null" ], "description": "Pixels." }, "author_name": { "type": [ "string", "null" ], "description": "Who uploaded it, as the listing credits them. `null` for the owner's own photos." }, "author_url": { "type": [ "string", "null" ], "format": "uri", "description": "Their Google Maps contributor page." } }, "additionalProperties": false, "description": "One photo on a place's listing." }, "linkedin_profile": { "type": "object", "required": [ "vanity_name", "url", "full_name", "first_name", "last_name", "headline", "about", "location", "profile_picture_url", "follower_count", "connection_count", "open_to_work", "current_company", "experience", "education", "skills" ], "properties": { "vanity_name": { "type": "string", "description": "The part after `/in/` in the profile URL." }, "url": { "type": "string", "format": "uri", "description": "The profile." }, "full_name": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ], "description": "The line under the name." }, "about": { "type": [ "string", "null" ], "description": "The About section." }, "location": { "type": [ "string", "null" ], "description": "As printed, e.g. \"Berlin, Germany\"." }, "profile_picture_url": { "type": [ "string", "null" ], "format": "uri" }, "follower_count": { "type": [ "integer", "null" ] }, "connection_count": { "type": [ "integer", "null" ], "description": "LinkedIn stops counting at 500: a value of 500 means \"500+\"." }, "open_to_work": { "type": [ "boolean", "null" ], "description": "Whether the profile shows the #OpenToWork frame." }, "current_company": { "type": [ "object", "null" ], "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The company page, where it has one." } }, "additionalProperties": false, "description": "The employer shown at the top of the profile." }, "experience": { "type": "array", "items": { "type": "object", "required": [ "title", "company", "employment_type", "location", "start_date", "end_date", "description" ], "properties": { "title": { "type": "string" }, "company": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The company page, where it has one." } }, "additionalProperties": false, "description": "The employer." }, "employment_type": { "type": [ "string", "null" ], "description": "As printed: \"Full-time\", \"Contract\", …" }, "location": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ], "description": "`YYYY-MM`, or `YYYY` where the profile gives only a year." }, "end_date": { "type": [ "string", "null" ], "description": "`YYYY-MM` or `YYYY`; `null` for a current role, or where the profile gives no date." }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "description": "Positions, most recent first." }, "education": { "type": "array", "items": { "type": "object", "required": [ "school", "degree", "field_of_study", "start_year", "end_year" ], "properties": { "school": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The company page, where it has one." } }, "additionalProperties": false, "description": "The school, and its LinkedIn page where it has one." }, "degree": { "type": [ "string", "null" ] }, "field_of_study": { "type": [ "string", "null" ] }, "start_year": { "type": [ "integer", "null" ] }, "end_year": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "description": "Schools, most recent first." }, "skills": { "type": "array", "items": { "type": "string" }, "description": "As listed on the profile." } }, "additionalProperties": false, "description": "A public LinkedIn profile, as a logged-out visitor sees it." }, "linkedin_company": { "type": "object", "required": [ "company_id", "vanity_name", "url", "name", "tagline", "description", "website", "industry", "company_size", "employees_on_linkedin", "headquarters", "company_type", "founded", "specialties", "follower_count", "logo_url" ], "properties": { "company_id": { "type": "string", "description": "LinkedIn's numeric id for the company." }, "vanity_name": { "type": "string", "description": "The part after `/company/` in the page URL." }, "url": { "type": "string", "format": "uri", "description": "The company page." }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ], "description": "The line under the name." }, "description": { "type": [ "string", "null" ], "description": "The About overview." }, "website": { "type": [ "string", "null" ], "format": "uri" }, "industry": { "type": [ "string", "null" ] }, "company_size": { "type": [ "string", "null" ], "description": "The band LinkedIn prints, e.g. \"51-200 employees\"." }, "employees_on_linkedin": { "type": [ "integer", "null" ], "description": "How many members list it as their employer." }, "headquarters": { "type": [ "object", "null" ], "required": [ "city", "geographic_area", "country" ], "properties": { "city": { "type": [ "string", "null" ] }, "geographic_area": { "type": [ "string", "null" ], "description": "State or region." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." } }, "additionalProperties": false }, "company_type": { "type": [ "string", "null" ], "description": "As printed: \"Privately Held\", \"Public Company\", …" }, "founded": { "type": [ "integer", "null" ], "description": "The year." }, "specialties": { "type": "array", "items": { "type": "string" } }, "follower_count": { "type": [ "integer", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" } }, "additionalProperties": false, "description": "A public LinkedIn company page." }, "linkedin_post": { "type": "object", "required": [ "urn", "url", "author", "text", "published_at", "reaction_count", "reactions", "comment_count", "repost_count", "images", "video", "document", "article", "is_repost" ], "properties": { "urn": { "type": "string", "description": "LinkedIn's id for the post, e.g. `urn:li:activity:7243…`." }, "url": { "type": "string", "format": "uri", "description": "The post." }, "author": { "type": "object", "required": [ "name", "type", "headline", "url" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "person", "company" ] }, "headline": { "type": [ "string", "null" ], "description": "The person's headline, or the company's follower line." }, "url": { "type": "string", "format": "uri", "description": "Their profile or company page." } }, "additionalProperties": false }, "text": { "type": [ "string", "null" ], "description": "The post's text." }, "published_at": { "type": "string", "format": "date-time" }, "reaction_count": { "type": "integer", "description": "All reactions together." }, "reactions": { "type": [ "object", "null" ], "required": [ "like", "celebrate", "support", "love", "insightful", "funny" ], "properties": { "like": { "type": "integer" }, "celebrate": { "type": "integer" }, "support": { "type": "integer" }, "love": { "type": "integer" }, "insightful": { "type": "integer" }, "funny": { "type": "integer" } }, "additionalProperties": false, "description": "By kind, where LinkedIn shows the breakdown." }, "comment_count": { "type": "integer" }, "repost_count": { "type": "integer" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Image URLs, in order." }, "video": { "type": [ "object", "null" ], "required": [ "url", "duration" ], "properties": { "url": { "type": "string", "format": "uri" }, "duration": { "type": [ "integer", "null" ], "description": "Seconds." } }, "additionalProperties": false }, "document": { "type": [ "object", "null" ], "required": [ "title", "page_count" ], "properties": { "title": { "type": "string" }, "page_count": { "type": [ "integer", "null" ] } }, "additionalProperties": false, "description": "An attached PDF or slide deck." }, "article": { "type": [ "object", "null" ], "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false, "description": "A shared link." }, "is_repost": { "type": "boolean", "description": "Whether this is someone else's post reposted without comment." } }, "additionalProperties": false, "description": "A public LinkedIn post." }, "linkedin_job": { "type": "object", "required": [ "job_id", "url", "title", "company", "location", "workplace_type", "employment_type", "seniority_level", "salary", "listed_at", "easy_apply", "description" ], "properties": { "job_id": { "type": "string", "description": "LinkedIn's numeric id — the number in `/jobs/view/…`." }, "url": { "type": "string", "format": "uri", "description": "The posting." }, "title": { "type": "string" }, "company": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The company page, where it has one." } }, "additionalProperties": false, "description": "Who is hiring." }, "location": { "type": [ "string", "null" ], "description": "As printed, e.g. \"Berlin, Germany\"." }, "workplace_type": { "type": [ "string", "null" ], "enum": [ "On-site", "Hybrid", "Remote", null ] }, "employment_type": { "type": [ "string", "null" ], "description": "\"Full-time\", \"Part-time\", \"Contract\", …" }, "seniority_level": { "type": [ "string", "null" ], "description": "\"Entry level\", \"Mid-Senior level\", …" }, "salary": { "type": [ "string", "null" ], "description": "As printed, where the posting shows one, e.g. \"€70K/yr - €90K/yr\"." }, "listed_at": { "type": "string", "format": "date-time", "description": "When it was posted." }, "easy_apply": { "type": [ "boolean", "null" ], "description": "Whether it takes applications on LinkedIn. `null` where the listing does not say." }, "description": { "type": [ "string", "null" ], "description": "The full description, as text." } }, "additionalProperties": false, "description": "A public LinkedIn job posting." }, "instagram_profile": { "type": "object", "required": [ "id", "username", "name", "biography", "website", "bio_links", "profile_picture_url", "followers_count", "follows_count", "media_count", "is_verified", "is_private", "is_business_account", "category", "business_email", "business_phone_number", "highlight_reel_count" ], "properties": { "id": { "type": "string", "description": "Instagram's numeric id for the account." }, "username": { "type": "string", "description": "Without the @." }, "name": { "type": [ "string", "null" ], "description": "The display name." }, "biography": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ], "format": "uri", "description": "The link in the bio." }, "bio_links": { "type": "array", "items": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "description": "Every link in the bio." }, "profile_picture_url": { "type": [ "string", "null" ], "format": "uri" }, "followers_count": { "type": "integer" }, "follows_count": { "type": "integer" }, "media_count": { "type": "integer", "description": "Posts on the grid." }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean", "description": "A private account shows its counts and nothing else." }, "is_business_account": { "type": "boolean", "description": "A business or creator account." }, "category": { "type": [ "string", "null" ], "description": "The label under the name, e.g. \"Bakery\" or \"Public figure\"." }, "business_email": { "type": [ "string", "null" ], "description": "Behind the Email button, where a business account shows one." }, "business_phone_number": { "type": [ "string", "null" ], "description": "Behind the Call button." }, "highlight_reel_count": { "type": "integer", "description": "Story highlights on the profile." } }, "additionalProperties": false, "description": "A public Instagram account." }, "instagram_post": { "type": "object", "required": [ "id", "shortcode", "permalink", "media_type", "media_product_type", "caption", "timestamp", "username", "media_url", "thumbnail_url", "children", "video_duration", "like_count", "comments_count", "view_count", "hashtags", "mentions", "location", "is_paid_partnership" ], "properties": { "id": { "type": "string", "description": "Instagram's numeric id for the post." }, "shortcode": { "type": "string", "description": "The code in the URL, e.g. `C1a2B3c4D5e`." }, "permalink": { "type": "string", "format": "uri", "description": "The post." }, "media_type": { "type": "string", "enum": [ "IMAGE", "VIDEO", "CAROUSEL_ALBUM" ], "description": "As the Graph API names them." }, "media_product_type": { "type": "string", "enum": [ "FEED", "REELS" ], "description": "A grid post or a Reel." }, "caption": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When it was posted." }, "username": { "type": "string", "description": "Who posted it." }, "media_url": { "type": "string", "format": "uri", "description": "The image, or the video file. A carousel's first item." }, "thumbnail_url": { "type": [ "string", "null" ], "format": "uri", "description": "The cover of a video." }, "children": { "type": "array", "items": { "type": "object", "required": [ "media_type", "media_url" ], "properties": { "media_type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ] }, "media_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "description": "A carousel's items, in order. Empty for a single image or video." }, "video_duration": { "type": [ "number", "null" ], "description": "Seconds." }, "like_count": { "type": [ "integer", "null" ], "description": "`null` when the owner has hidden it." }, "comments_count": { "type": "integer" }, "view_count": { "type": [ "integer", "null" ], "description": "Views, for videos and Reels." }, "hashtags": { "type": "array", "items": { "type": "string" }, "description": "The caption's hashtags, without the #." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "The usernames the caption mentions, without the @." }, "location": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false, "description": "The location tag." }, "is_paid_partnership": { "type": "boolean", "description": "Whether it carries the \"Paid partnership\" label." } }, "additionalProperties": false, "description": "A public Instagram post or Reel." }, "instagram_comment": { "type": "object", "required": [ "id", "media_id", "parent_id", "username", "text", "timestamp", "like_count", "reply_count" ], "properties": { "id": { "type": "string" }, "media_id": { "type": "string", "description": "The post it is on." }, "parent_id": { "type": [ "string", "null" ], "description": "The comment it replies to. `null` for a top-level comment." }, "username": { "type": "string" }, "text": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "like_count": { "type": "integer" }, "reply_count": { "type": "integer" } }, "additionalProperties": false, "description": "A comment on an Instagram post." }, "tiktok_profile": { "type": "object", "required": [ "username", "display_name", "bio_description", "bio_url", "avatar_url", "profile_url", "is_verified", "follower_count", "following_count", "likes_count", "video_count" ], "properties": { "username": { "type": "string", "description": "Without the @." }, "display_name": { "type": [ "string", "null" ] }, "bio_description": { "type": [ "string", "null" ] }, "bio_url": { "type": [ "string", "null" ], "format": "uri", "description": "The link in the bio." }, "avatar_url": { "type": [ "string", "null" ], "format": "uri" }, "profile_url": { "type": "string", "format": "uri", "description": "The profile." }, "is_verified": { "type": "boolean" }, "follower_count": { "type": "integer" }, "following_count": { "type": "integer" }, "likes_count": { "type": "integer", "description": "Likes across all their videos." }, "video_count": { "type": "integer" } }, "additionalProperties": false, "description": "A public TikTok account." }, "tiktok_video": { "type": "object", "required": [ "id", "share_url", "username", "video_description", "create_time", "duration", "cover_image_url", "play_url", "view_count", "like_count", "comment_count", "share_count", "favorites_count", "hashtag_names", "region_code", "music", "duet_enabled", "stitch_enabled" ], "properties": { "id": { "type": "string", "description": "TikTok's numeric id — the number at the end of the URL." }, "share_url": { "type": "string", "format": "uri", "description": "The video." }, "username": { "type": "string", "description": "Who posted it." }, "video_description": { "type": [ "string", "null" ], "description": "The caption." }, "create_time": { "type": "string", "format": "date-time", "description": "When it was posted." }, "duration": { "type": "integer", "description": "Seconds." }, "cover_image_url": { "type": [ "string", "null" ], "format": "uri" }, "play_url": { "type": [ "string", "null" ], "format": "uri", "description": "The video file on TikTok's CDN. TikTok signs it and it stops working after a while, so fetch it soon. We do not rehost videos." }, "view_count": { "type": "integer" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "favorites_count": { "type": [ "integer", "null" ], "description": "Saves. `null` where the page does not show them." }, "hashtag_names": { "type": "array", "items": { "type": "string" }, "description": "Without the #." }, "region_code": { "type": [ "string", "null" ], "description": "Where it was posted from, ISO 3166-1 alpha-2." }, "music": { "type": [ "object", "null" ], "required": [ "id", "title", "author", "original" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "original": { "type": "boolean", "description": "An original sound rather than a track." } }, "additionalProperties": false, "description": "The sound." }, "duet_enabled": { "type": "boolean" }, "stitch_enabled": { "type": "boolean" } }, "additionalProperties": false, "description": "A public TikTok video." }, "tiktok_comment": { "type": "object", "required": [ "id", "video_id", "parent_comment_id", "username", "text", "create_time", "like_count", "reply_count" ], "properties": { "id": { "type": "string" }, "video_id": { "type": "string", "description": "The video it is on." }, "parent_comment_id": { "type": [ "string", "null" ], "description": "The comment it replies to. `null` for a top-level comment." }, "username": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "string", "format": "date-time" }, "like_count": { "type": "integer" }, "reply_count": { "type": "integer" } }, "additionalProperties": false, "description": "A comment on a TikTok video." }, "tiktok_hashtag": { "type": "object", "required": [ "hashtag_name", "url", "video_count", "view_count" ], "properties": { "hashtag_name": { "type": "string", "description": "Without the #." }, "url": { "type": "string", "format": "uri", "description": "The hashtag page." }, "video_count": { "type": [ "integer", "null" ] }, "view_count": { "type": [ "integer", "null" ] } }, "additionalProperties": false, "description": "A TikTok hashtag, from a search." }, "error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "permission_error", "not_found", "rate_limit", "upstream_error", "internal_error" ] }, "code": { "type": "string", "description": "Stable and documented. Branch on this, not on the message.", "enum": [ "key_in_url", "missing_api_key", "invalid_api_key", "insufficient_credits", "scope_not_allowed", "fresh_not_available", "disposable_email", "signup_rate_limit", "invalid_link", "link_used", "link_expired", "email_rate_limit", "sign_in_rate_limit", "account_closed", "unverified_account", "unknown_endpoint", "missing_parameter", "missing_one_of", "invalid_parameter", "invalid_cursor", "profile_not_found", "place_not_found", "subject_suppressed", "results_expired", "post_not_found", "concurrency_limit", "upstream_unavailable", "internal_error" ] }, "message": { "type": "string", "description": "Written for a human and says what to do next. May change." }, "docs": { "type": "string" }, "request_id": { "type": "string" } } } } } } } }