{ "openapi": "3.1.0", "info": { "title": "ScrapeField API", "version": "1.0.0", "summary": "One API for Google Maps, LinkedIn, Instagram, TikTok and X.", "description": "One key, one invoice, five 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, an X post the way X's API v2 does; LinkedIn, which has no official data API, uses the words it prints.\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. A page holds at most `limit` rows, sometimes fewer; an endpoint without `limit` has a fixed page size, given in its description. A cursor lasts as long as the answer is cached (hours); after that it is refused with `invalid_cursor`.\n\n**Demo.** Any data endpoint answers with no key when you add `?demo=true`: a fixed answer in the same shape, charged nothing.\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/contact", "email": "support@scrapefield.com" } }, "servers": [ { "url": "https://api.scrapefield.com/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Google Maps" }, { "name": "LinkedIn" }, { "name": "Instagram" }, { "name": "TikTok" }, { "name": "X" }, { "name": "Account" }, { "name": "Catalogue" } ], "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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What to search for, e.g. \"coffee shops in Brooklyn\" or \"dentist\".", "schema": { "type": "string", "maxLength": 2048, "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", "pattern": "^(?:[A-Za-z]{2})$", "maxLength": 2048 } }, { "name": "language", "in": "query", "required": false, "description": "Two-letter language code for localised text, e.g. `en`, `de`.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z]{2}(-[A-Za-z]{2})?)$", "maxLength": 2048, "default": "en" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–20. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$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, the About tab and business_status. popular_times is in the object, and null where the source does not give it. 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", "security": [ { "bearerAuth": [] }, {} ], "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", "pattern": "^(?:[A-Za-z0-9_-]{10,1000})$", "maxLength": 2048, "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" } }, { "name": "url", "in": "query", "required": false, "description": "The full URL of the place on Google Maps, which carries its id. A short maps.app.goo.gl link does not, so open it and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:https?://((www|maps)\\.)?google\\.[a-z]{2,3}(\\.[a-z]{2})?/maps\\S*(place_id[:=]|query_place_id=|!1s0x[0-9a-fA-F]+:0x)\\S*)$", "maxLength": 2048 } }, { "name": "language", "in": "query", "required": false, "description": "Two-letter language code for localised text, e.g. `en`, `de`.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z]{2}(-[A-Za-z]{2})?)$", "maxLength": 2048, "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/reviews": { "get": { "operationId": "get_place_reviews", "summary": "Get the reviews of a Google Maps 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. The first page has up to 8 reviews, and each page after it up to 20. Use this for review monitoring and sentiment work.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 6 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 6, "x-cache-ttl-seconds": 21600, "x-mcp-tool": "get_place_reviews", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{10,1000})$", "maxLength": 2048, "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" } }, { "name": "url", "in": "query", "required": false, "description": "The full URL of the place on Google Maps, which carries its id. A short maps.app.goo.gl link does not, so open it and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:https?://((www|maps)\\.)?google\\.[a-z]{2,3}(\\.[a-z]{2})?/maps\\S*(place_id[:=]|query_place_id=|!1s0x[0-9a-fA-F]+:0x)\\S*)$", "maxLength": 2048 } }, { "name": "sort", "in": "query", "required": false, "description": "Order of the reviews.", "schema": { "type": "string", "enum": [ "relevance", "newest", "highest", "lowest" ], "default": "relevance" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–20. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/photos": { "get": { "operationId": "get_place_photos", "summary": "Get the photos of a Google Maps place", "description": "Fetch the photos on one place's listing, as URLs on Google's CDN; we do not rehost images. Dimensions and uploader are in the object, and null where the source does not give them.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 4 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 4, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_place_photos", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{10,1000})$", "maxLength": 2048, "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" } }, { "name": "url", "in": "query", "required": false, "description": "The full URL of the place on Google Maps, which carries its id. A short maps.app.goo.gl link does not, so open it and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:https?://((www|maps)\\.)?google\\.[a-z]{2,3}(\\.[a-z]{2})?/maps\\S*(place_id[:=]|query_place_id=|!1s0x[0-9a-fA-F]+:0x)\\S*)$", "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–20. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/google-maps/posts": { "get": { "operationId": "get_place_posts", "summary": "Get an owner's posts on a Google Maps place", "description": "Fetch the updates the owner posted on one place's listing, newest first: the text, the day, an image and where it links, such as an offer or an event. Use this to watch what a competitor announces.\n\nGive exactly one of `place_id` or `url` to identify the place.\n\nCosts 4 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Google Maps" ], "x-credits": 4, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_place_posts", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "place_id", "in": "query", "required": false, "description": "Google's place ID.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{10,1000})$", "maxLength": 2048, "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" } }, { "name": "url", "in": "query", "required": false, "description": "The full URL of the place on Google Maps, which carries its id. A short maps.app.goo.gl link does not, so open it and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:https?://((www|maps)\\.)?google\\.[a-z]{2,3}(\\.[a-z]{2})?/maps\\S*(place_id[:=]|query_place_id=|!1s0x[0-9a-fA-F]+:0x)\\S*)$", "maxLength": 2048 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/profile": { "get": { "operationId": "get_linkedin_profile", "summary": "Get a LinkedIn profile", "description": "Fetch a LinkedIn profile: full_name, headline, about, location, follower_count, connection_count, current_company, experience, education and skills. With `detail=with_email`, also look for their work email, each address checked with its mail server. 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 11 credits (7 for `detail=main`, 33 for `detail=with_email`), whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 11, "x-credits-by": { "parameter": "detail", "credits": { "main": 7, "with_email": 33 } }, "x-cache-ttl-seconds": 43200, "x-mcp-tool": "get_linkedin_profile", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The public profile URL, e.g. `https://www.linkedin.com/in/someone`. A member-id URL (`/in/ACoAA…` or `/in/ACwAA…`), as reactions and Sales Navigator give, works too.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/in/[^/?#\\s]{3,100}([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/in/example" } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/in/` in the public URL, e.g. `someone`. A member id (`ACoAA…`) works too.", "schema": { "type": "string", "pattern": "^(?:[^/?#\\s]{3,100})$", "maxLength": 2048 } }, { "name": "detail", "in": "query", "required": false, "description": "`main` is the profile as LinkedIn first shows it, without opening a section: up to 5 positions, 2 schools and 2 skills, for less. `with_email` is the whole profile and a search for their work email, in `emails`, for more.", "schema": { "type": "string", "enum": [ "full", "main", "with_email" ], "default": "full" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/company": { "get": { "operationId": "get_linkedin_company", "summary": "Get a LinkedIn company page", "description": "Fetch a 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 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 3, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_linkedin_company", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The company page URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s]+([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/company/` in the URL, e.g. `acme-inc`.", "schema": { "type": "string", "pattern": "^(?:[^/?#\\s]{2,100})$", "maxLength": 2048, "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/employee-stats": { "get": { "operationId": "get_linkedin_employee_stats", "summary": "Count a company's people on LinkedIn", "description": "Fetch the counts on a company's People tab: where its people live, what they do, where they studied, what they are skilled at, each as a list of names and member counts. Use this to size a team, or to see where a company hires.\n\nGive exactly one of `url` or `vanity_name` or `company_id` to identify the company.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 604800, "x-mcp-tool": "get_linkedin_employee_stats", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The company page URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s]+([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/company/` in the URL.", "schema": { "type": "string", "pattern": "^(?:[^/?#\\s]{2,100})$", "maxLength": 2048 } }, { "name": "company_id", "in": "query", "required": false, "description": "LinkedIn's numeric id for the company: `company_id` in linkedin/company. The fastest of the three.", "schema": { "type": "string", "pattern": "^(?:\\d{1,12})$", "maxLength": 2048, "example": "1035" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_employee_stats" }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/employees": { "get": { "operationId": "get_linkedin_company_people", "summary": "Get the people at a company, from LinkedIn", "description": "Fetch the people who list a company as their employer, 25 a page from Sales Navigator, which hides no one: each person's name, location and profile, and their current roles, each with its title, employer and `company_id`, and start month. The same object, and price, as linkedin/people with `source=sales_navigator`. Takes the company's numeric id, `company_id` in linkedin/company. Use this to map a company's team or to find who to contact.\n\nCosts 170 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 170, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_linkedin_company_people", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "company_id", "in": "query", "required": true, "description": "LinkedIn's numeric id for the company: `company_id` in linkedin/company.", "schema": { "type": "string", "pattern": "^(?:\\d{1,12})$", "maxLength": 2048, "example": "1035" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_lead" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/people": { "get": { "operationId": "search_linkedin_people", "summary": "Search people on LinkedIn", "description": "Find people by name, title, company, school or place. With `source=public` (the default), LinkedIn's own people search: it finds people well by name, but hides many other results as \"LinkedIn Member\", and those are left out. With `source=sales_navigator`, Sales Navigator's lead search: every match, with each person's current roles, at a higher price. 10 a page, or 25 with Sales Navigator. A page takes about 3 seconds, or about 5 with Sales Navigator, and now and then up to 25. Give at least one of `query`, `first_name`, `last_name`, `title`, `current_company`, `past_company`, `school` or `location`. Use linkedin/profile on a result for the whole profile.\n\nCosts 7 credits (170 for `source=sales_navigator`), whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-credits-by": { "parameter": "source", "credits": { "sales_navigator": 170 } }, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_linkedin_people", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Words to search for, as in LinkedIn's search box.", "schema": { "type": "string", "maxLength": 2048, "example": "data engineer" } }, { "name": "first_name", "in": "query", "required": false, "description": "Their first name, as their profile gives it.", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "last_name", "in": "query", "required": false, "description": "Their last name, as their profile gives it.", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "title", "in": "query", "required": false, "description": "Words in their current title, e.g. \"head of data\".", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "current_company", "in": "query", "required": false, "description": "Where they work now: a company page URL or `company_id`. Several, comma-separated.", "schema": { "type": "string", "pattern": "^(?:((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12})(,((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12}))*)$", "maxLength": 2048 } }, { "name": "past_company", "in": "query", "required": false, "description": "Where they worked before, as `current_company`.", "schema": { "type": "string", "pattern": "^(?:((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12})(,((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12}))*)$", "maxLength": 2048 } }, { "name": "school", "in": "query", "required": false, "description": "Where they studied: a school page URL or its id. Several, comma-separated.", "schema": { "type": "string", "pattern": "^(?:((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12})(,((https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s,]+([/?#][^\\s,]*)?|\\d{1,12}))*)$", "maxLength": 2048 } }, { "name": "location", "in": "query", "required": false, "description": "A place name, e.g. \"Berlin\" or \"Germany\".", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "source", "in": "query", "required": false, "description": "`public` is LinkedIn's people search; `sales_navigator` is Sales Navigator's lead search, which hides no one and gives current roles, at a higher price.", "schema": { "type": "string", "enum": [ "public", "sales_navigator" ], "default": "public" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/linkedin_member" }, { "$ref": "#/components/schemas/linkedin_lead" } ], "description": "`source=public` returns `linkedin_member`; `source=sales_navigator` returns `linkedin_lead`." } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/services": { "get": { "operationId": "search_linkedin_services", "summary": "Find people who offer services on LinkedIn", "description": "Find people who list a service on their profile, by what they offer and where: \"web design\" in \"California\". LinkedIn hides no one in this search, so it finds people that `linkedin/people` hides. Each result is a person, with their headline and place, 10 a page.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_linkedin_services", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The service, e.g. \"web design\" or \"bookkeeping\".", "schema": { "type": "string", "maxLength": 2048, "example": "web design" } }, { "name": "location", "in": "query", "required": false, "description": "A place name, e.g. \"California\".", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_member" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/companies": { "get": { "operationId": "search_linkedin_companies", "summary": "Search companies on LinkedIn", "description": "Find companies by name or keywords, place and size, up to 50 a page. Each result has the company's id, page, industry, place and followers; linkedin/company gives the whole page, and linkedin/employees its people.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_linkedin_companies", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Words in the company's name.", "schema": { "type": "string", "maxLength": 2048, "example": "coffee roasters" } }, { "name": "location", "in": "query", "required": false, "description": "A place name, e.g. \"Berlin\".", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "company_size", "in": "query", "required": false, "description": "Only companies of these sizes, as LinkedIn bands them: `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`. Several, comma-separated.", "schema": { "type": "string", "pattern": "^(?:(1-10|11-50|51-200|201-500|501-1000|1001-5000|5001-10000|10001\\+)(,(1-10|11-50|51-200|201-500|501-1000|1001-5000|5001-10000|10001\\+))*)$", "maxLength": 2048 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_company_result" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/posts": { "get": { "operationId": "get_linkedin_posts", "summary": "Get or search LinkedIn posts", "description": "Fetch recent posts by one person or company, or with `query` every public post with those words: text, images, video, document or article, and published_at. A person's posts also carry reaction_count (with the breakdown by kind), comment_count and repost_count; a company's carry the text and the date, with the counts null, at a much lower price. For the counts on one of them, call linkedin/post.\n\nGive exactly one of `url` or `company_url` or `query` to identify the author.\n\nCosts 7 credits (3 with `company_url`), whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-credits-by": { "parameter": "company_url", "credits": { "*": 3 } }, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_posts", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "A person's public profile URL. Their latest posts, on one page.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/in/[^/?#\\s]{3,100}([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/in/example-person" } }, { "name": "company_url", "in": "query", "required": false, "description": "A company page URL. Up to 7 pages of 10.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(company|school|showcase)/[^/?#\\s]+([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/company/example-co" } }, { "name": "query", "in": "query", "required": false, "description": "Words in the post: every public post that has them, newest first.", "schema": { "type": "string", "maxLength": 2048, "example": "electric cars" } }, { "name": "posted_within", "in": "query", "required": false, "description": "Only posts from the last day, week or month.", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–100. A page can hold fewer while `next_cursor` is set: read until it is null.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/post": { "get": { "operationId": "get_linkedin_post", "summary": "Get one LinkedIn post", "description": "Fetch one post by its URL: its text, images, author, published_at, reaction_count and comment_count. repost_count and the reactions by kind are null: the source gives the total only. Use linkedin/comments for its comments and linkedin/reactions for who reacted.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 3, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_post", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The post's URL: `https://www.linkedin.com/posts/…-activity--…`, or `https://www.linkedin.com/feed/update/urn:li:activity:`. A link by the share's id works too: `urn:li:ugcPost:`, `urn:li:share:` or `/posts/…-ugcPost--…`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(posts/[^/?#\\s]*(?:activity|ugcPost|share)-\\d{16,22}[^/?#\\s]*|feed/update/urn:li:(?:activity|ugcPost|share):\\d{16,22})([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/feed/update/urn:li:activity:7243000000000000000" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/comments": { "get": { "operationId": "get_linkedin_post_comments", "summary": "Get the comments on a LinkedIn post", "description": "Fetch the comments on one post, up to 100 a page: each comment's text, author (name, headline, profile), published_at, like_count, reply_count and its own `url`, which opens the post at that comment. With `comment_url`, the replies to one comment. Use this to see who engages with a post and what they say.\n\nGive exactly one of `url` or `comment_url` to identify the subject.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_linkedin_post_comments", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL, as for linkedin/post.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(posts/[^/?#\\s]*(?:activity|ugcPost|share)-\\d{16,22}[^/?#\\s]*|feed/update/urn:li:(?:activity|ugcPost|share):\\d{16,22})([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/feed/update/urn:li:activity:7243000000000000000" } }, { "name": "comment_url", "in": "query", "required": false, "description": "A comment's URL, as LinkedIn's \"Copy link to comment\" gives it: the replies to that comment.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/feed/update/urn:li:(activity|ugcPost|share):\\d{16,22}/?\\?(\\S*&)?commentUrn=\\S+)$", "maxLength": 2048, "example": "https://www.linkedin.com/feed/update/urn:li:activity:7243000000000000000?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7243000000000000000%2C7243000000000000001%29" } }, { "name": "sort", "in": "query", "required": false, "description": "Most relevant first, or newest first.", "schema": { "type": "string", "enum": [ "relevance", "newest" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/reactions": { "get": { "operationId": "get_linkedin_post_reactions", "summary": "Get who reacted to a LinkedIn post", "description": "Fetch who reacted to one post, up to 100 a page: each person's or company page's name, headline and link, and which reaction. With `comment_url`, who reacted to one comment. LinkedIn lists people who react by member id, so `actor.url` is usually a member-id link (`/in/ACoAA…`) with `vanity_name` null; linkedin/profile takes it.\n\nGive exactly one of `url` or `comment_url` to identify the subject.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_post_reactions", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL, as for linkedin/post.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/(posts/[^/?#\\s]*(?:activity|ugcPost|share)-\\d{16,22}[^/?#\\s]*|feed/update/urn:li:(?:activity|ugcPost|share):\\d{16,22})([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/feed/update/urn:li:activity:7243000000000000000" } }, { "name": "comment_url", "in": "query", "required": false, "description": "A comment's URL: who reacted to that comment.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/feed/update/urn:li:(activity|ugcPost|share):\\d{16,22}/?\\?(\\S*&)?commentUrn=\\S+)$", "maxLength": 2048, "example": "https://www.linkedin.com/feed/update/urn:li:activity:7243000000000000000?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7243000000000000000%2C7243000000000000001%29" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_reaction" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/activity": { "get": { "operationId": "get_linkedin_activity", "summary": "Get a person's LinkedIn comments and reactions", "description": "Fetch what one person did recently on other people's posts: with `type=comments`, the comments they wrote and when; with `type=reactions`, the posts they reacted to and how. Each item carries the post, with its author and counts, when they did it, and for a comment its own `comment_url`, which opens the post at that comment. The newest first, up to 100 a page, with `next_cursor` for older ones. Use this for sales signals: who a prospect engages with, and on what.\n\nGive exactly one of `url` or `vanity_name` to identify the profile.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_activity", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The person's public profile URL. A member-id link (`/in/ACoAA…` or `/in/ACwAA…`), as reactions and Sales Navigator give, works too.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/in/[^/?#\\s]{3,100}([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://www.linkedin.com/in/example" } }, { "name": "vanity_name", "in": "query", "required": false, "description": "The part after `/in/` in their public URL. A member id (`ACoAA…`) works too.", "schema": { "type": "string", "pattern": "^(?:[^/?#\\s]{3,100})$", "maxLength": 2048 } }, { "name": "type", "in": "query", "required": false, "description": "Their comments, or their reactions.", "schema": { "type": "string", "enum": [ "comments", "reactions" ], "default": "comments" } }, { "name": "posted_within", "in": "query", "required": false, "description": "Only comments from the last day, week or month. With `type=comments` only.", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_activity" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/jobs": { "get": { "operationId": "search_linkedin_jobs", "summary": "Search LinkedIn job postings", "description": "Search LinkedIn job postings by keyword and location, with LinkedIn's own filters. Returns each posting's title, company, location, listed_at, URL, and workplace_type and easy_apply where the list shows them. employment_type, seniority_level, salary and description are null: linkedin/job gives them.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 3, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "search_linkedin_jobs", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Job title or keywords, e.g. \"backend engineer\".", "schema": { "type": "string", "maxLength": 2048, "example": "backend engineer" } }, { "name": "location", "in": "query", "required": false, "description": "Place name, e.g. \"Berlin\" or \"United States\".", "schema": { "type": "string", "maxLength": 2048 } }, { "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", "in": "query", "required": false, "description": "Only roles posted in the last day, week or month.", "schema": { "type": "string", "enum": [ "day", "week", "month" ] } }, { "name": "employment_type", "in": "query", "required": false, "description": "Only roles of this kind.", "schema": { "type": "string", "enum": [ "full-time", "part-time", "contract", "temporary", "internship" ] } }, { "name": "experience_level", "in": "query", "required": false, "description": "Only roles at this level, as LinkedIn's filter names them.", "schema": { "type": "string", "enum": [ "internship", "entry", "associate", "mid-senior", "director", "executive" ] } }, { "name": "company_id", "in": "query", "required": false, "description": "Only one company's roles: `company_id` in linkedin/company.", "schema": { "type": "string", "pattern": "^(?:\\d{1,12})$", "maxLength": 2048 } }, { "name": "easy_apply", "in": "query", "required": false, "description": "Only roles that take applications on LinkedIn.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "Most relevant first, or newest first.", "schema": { "type": "string", "enum": [ "relevance", "newest" ] } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–25. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/job": { "get": { "operationId": "get_linkedin_job", "summary": "Get one LinkedIn job posting in full", "description": "Fetch one LinkedIn job posting by its id or URL: title, company, location, employment_type, seniority_level, salary where the posting shows one, and the full description — the fields linkedin/jobs leaves null, and workplace_type, listed_at and easy_apply where the posting shows them. Use it on the job_id of a search result.\n\nGive exactly one of `id` or `url` to identify the job.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 3, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_linkedin_job", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "LinkedIn's numeric id for the posting: `job_id` in a search result, and the number at the end of `/jobs/view/…`.", "schema": { "type": "string", "pattern": "^(?:\\d{6,20})$", "maxLength": 2048, "example": "4468618386" } }, { "name": "url", "in": "query", "required": false, "description": "The posting's URL, e.g. `https://www.linkedin.com/jobs/view/4468618386/`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/jobs/(view/([^/?#]*-)?\\d{6,20}/?([?#].*)?|[^?#]*\\?(.*&)?currentJobId=\\d{6,20}(&.*)?))$", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/ads": { "get": { "operationId": "search_linkedin_ads", "summary": "Search LinkedIn's Ad Library", "description": "Search the ads LinkedIn shows in its public Ad Library, by advertiser, by words in the ad or by company id, optionally by country and date: each ad's advertiser, format, headline, text, image or video, call to action, where it leads, when it ran, its impressions range and its targeting, about 25 a page. Use this to watch what a competitor advertises.\n\nGive exactly one of `advertiser` or `company_id` or `query` to identify the search.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 3, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_linkedin_ads", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "advertiser", "in": "query", "required": false, "description": "The advertiser's name, as the library searches it. It matches loosely: a person whose name contains it can appear.", "schema": { "type": "string", "maxLength": 2048, "example": "Ferrari" } }, { "name": "company_id", "in": "query", "required": false, "description": "LinkedIn's numeric id for the company, `company_id` in linkedin/company: that company's ads only.", "schema": { "type": "string", "pattern": "^(?:\\d{1,12})$", "maxLength": 2048, "example": "1035" } }, { "name": "query", "in": "query", "required": false, "description": "Words in the ad.", "schema": { "type": "string", "maxLength": 2048, "example": "electric cars" } }, { "name": "countries", "in": "query", "required": false, "description": "Only ads shown in these countries: two-letter codes, comma-separated, e.g. `US,GB`.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z]{2}(,[A-Za-z]{2})*)$", "maxLength": 2048 } }, { "name": "start_date", "in": "query", "required": false, "description": "Only ads shown on or after this day, `YYYY-MM-DD`, within the last year. With `end_date`.", "schema": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2})$", "maxLength": 2048 } }, { "name": "end_date", "in": "query", "required": false, "description": "Only ads shown on or before this day, `YYYY-MM-DD`, before today. With `start_date`.", "schema": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2})$", "maxLength": 2048 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_ad" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/ad": { "get": { "operationId": "get_linkedin_ad", "summary": "Get one ad from LinkedIn's Ad Library", "description": "Fetch one ad in full by its id or URL: what linkedin/ads gives, and where it was seen, country by country, with its targeting.\n\nGive exactly one of `id` or `url` to identify the ad.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_linkedin_ad", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "query", "required": false, "description": "The Ad Library's id for the ad: `id` in linkedin/ads.", "schema": { "type": "string", "pattern": "^(?:\\d{4,20})$", "maxLength": 2048, "example": "1572822563" } }, { "name": "url", "in": "query", "required": false, "description": "The ad's page in the Ad Library: `https://www.linkedin.com/ad-library/detail/`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/ad-library/detail/\\d{4,20}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_ad" }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/group": { "get": { "operationId": "get_linkedin_group", "summary": "Get one LinkedIn group", "description": "Fetch one group: its name, members, description, rules, when it was made and whether its posts are public. Its posts, by `group_url` on linkedin/posts, are not available yet.\n\nGive exactly one of `url` or `id` to identify the group.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_linkedin_group", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The group's URL: `https://www.linkedin.com/groups//`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?([a-z]{1,3}\\.)?linkedin\\.com/groups/\\d{1,15}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The number in the group's URL.", "schema": { "type": "string", "pattern": "^(?:\\d{1,15})$", "maxLength": 2048, "example": "1976445" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_group" }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/linkedin/groups": { "get": { "operationId": "search_linkedin_groups", "summary": "Search LinkedIn groups", "description": "Find groups by keywords: each one's name, URL, members and summary, 10 a page.\n\nCosts 7 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "LinkedIn" ], "x-credits": 7, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "search_linkedin_groups", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Words to search for.", "schema": { "type": "string", "maxLength": 2048, "example": "data engineering" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_group" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/profile": { "get": { "operationId": "get_instagram_profile", "summary": "Get an Instagram profile", "description": "Fetch an 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9._]{1,30})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?instagram\\.com/[A-Za-z0-9._]{1,30}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/posts": { "get": { "operationId": "get_instagram_posts", "summary": "Get recent posts from an Instagram profile", "description": "Fetch recent 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9._]{1,30})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?instagram\\.com/[A-Za-z0-9._]{1,30}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–24. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/post": { "get": { "operationId": "get_instagram_post", "summary": "Get one Instagram 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 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_post", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?instagram\\.com/([A-Za-z0-9._]{1,30}/)?(p|reel|reels|tv)/[A-Za-z0-9_-]{5,40}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "shortcode", "in": "query", "required": false, "description": "The shortcode from the URL, e.g. `C1a2B3c4D5e`.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{5,40})$", "maxLength": 2048, "example": "C1a2B3c4D5e" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/comments": { "get": { "operationId": "get_instagram_comments", "summary": "Get the comments on an Instagram 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?instagram\\.com/([A-Za-z0-9._]{1,30}/)?(p|reel|reels|tv)/[A-Za-z0-9_-]{5,40}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "shortcode", "in": "query", "required": false, "description": "The post shortcode.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z0-9_-]{5,40})$", "maxLength": 2048, "example": "C1a2B3c4D5e" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–50. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/hashtag": { "get": { "operationId": "get_instagram_hashtag", "summary": "Get recent posts for an Instagram hashtag", "description": "Fetch recent posts carrying one hashtag, each a full post. Use this for trend and campaign monitoring.\n\nCosts 64 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "Instagram" ], "x-credits": 64, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_instagram_hashtag", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "tag", "in": "query", "required": true, "description": "The hashtag, without the leading #.", "schema": { "type": "string", "pattern": "^(?:#?[^\\s#/?&]{1,100})$", "maxLength": 2048, "example": "sourdough" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–24. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/instagram/search": { "get": { "operationId": "search_instagram_accounts", "summary": "Search Instagram accounts", "description": "Find Instagram accounts by a keyword: each account's username, name and link, the most relevant first, one page. The search answers from a search index, so it gives no counts: call `instagram/profile` with a username for the whole account. Use this to find creators and brands when you do not have a username.\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": 86400, "x-mcp-tool": "search_instagram_accounts", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Words to search for, e.g. \"sourdough bakery\".", "schema": { "type": "string", "maxLength": 2048, "example": "ferrari" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–50. A page can hold fewer while `next_cursor` is set: read until it is null.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_search_result" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/profile": { "get": { "operationId": "get_tiktok_profile", "summary": "Get a TikTok profile", "description": "Fetch a 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9._]{2,24})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?tiktok\\.com/@[A-Za-z0-9._]{2,24}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/followers": { "get": { "operationId": "get_tiktok_followers", "summary": "Get a TikTok account's followers or following", "description": "Fetch an account's followers, newest first, or with `type=following` the accounts it follows: each a profile with its follower and video counts, about 50 a page. Use this to see who an audience is, or who a creator watches.\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": 21600, "x-mcp-tool": "get_tiktok_followers", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9._]{2,24})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?tiktok\\.com/@[A-Za-z0-9._]{2,24}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "type", "in": "query", "required": false, "description": "Who follows the account, or whom it follows.", "schema": { "type": "string", "enum": [ "followers", "following" ], "default": "followers" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/videos": { "get": { "operationId": "get_tiktok_videos", "summary": "Get recent videos from a TikTok profile", "description": "Fetch recent 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9._]{2,24})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?tiktok\\.com/@[A-Za-z0-9._]{2,24}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–30. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/video": { "get": { "operationId": "get_tiktok_video", "summary": "Get one TikTok 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 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_video", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The video URL, `https://www.tiktok.com/@…/video/…`. A short `vm.tiktok.com` link is not read: open it, and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?tiktok\\.com/@[A-Za-z0-9._]{1,24}/video/\\d{8,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The numeric video id.", "schema": { "type": "string", "pattern": "^(?:\\d{8,25})$", "maxLength": 2048, "example": "7301234567890123456" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/comments": { "get": { "operationId": "get_tiktok_comments", "summary": "Get the comments on a TikTok 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", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The video URL, `https://www.tiktok.com/@…/video/…`. A short `vm.tiktok.com` link is not read: open it, and copy the address it leads to.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|m)\\.)?tiktok\\.com/@[A-Za-z0-9._]{1,24}/video/\\d{8,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The numeric video id.", "schema": { "type": "string", "pattern": "^(?:\\d{8,25})$", "maxLength": 2048, "example": "7301234567890123456" } }, { "name": "limit", "in": "query", "required": false, "description": "At most this many results, 1–50. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$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 3 credits (13 for `type=hashtag`), whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "TikTok" ], "x-credits": 3, "x-credits-by": { "parameter": "type", "credits": { "hashtag": 13 } }, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "search_tiktok", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What to search for.", "schema": { "type": "string", "maxLength": 2048, "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": "At most this many results, 1–30. A page can hold fewer while `next_cursor` is set: read until it is null.", "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", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/trending": { "get": { "operationId": "get_tiktok_trending", "summary": "Get the videos trending on TikTok in a country", "description": "Fetch the videos TikTok's trending feed shows in one country now, each a full video. One page, which changes from call to call. Use this to see what is spreading.\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": 1800, "x-mcp-tool": "get_tiktok_trending", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "region", "in": "query", "required": false, "description": "Two-letter country code, e.g. `US`, `GB`, `DE`.", "schema": { "type": "string", "pattern": "^(?:[A-Za-z]{2})$", "maxLength": 2048, "default": "US", "example": "US" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/tiktok/ads": { "get": { "operationId": "search_tiktok_ads", "summary": "Search TikTok's Ad Library", "description": "Search the ads in TikTok's public Ad Library by keyword: each ad's advertiser, title, industry, when it first and last ran, its video or images, the audience range and impressions, about 12 a page. TikTok's library holds ads shown in Europe. Use this to watch what a brand or a category advertises.\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": "search_tiktok_ads", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "A brand, an advertiser or words in the ad.", "schema": { "type": "string", "maxLength": 2048, "example": "nike" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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_ad" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/profile": { "get": { "operationId": "get_x_profile", "summary": "Get an X profile", "description": "Fetch an X account: username, name, description, location, the link in the profile, verified, created_at, and public_metrics (followers_count, following_count, tweet_count and more) — named as in X's own API v2. Use this to size an account or enrich a handle.\n\nGive exactly one of `username` or `url` to identify the account.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 3, "x-cache-ttl-seconds": 43200, "x-mcp-tool": "get_x_profile", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9_]{1,15})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL, on x.com or twitter.com.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_user" }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/posts": { "get": { "operationId": "get_x_posts", "summary": "Get an X account's or community's posts", "description": "Fetch an account's newest posts, about 20 a page with `next_cursor` for older ones; or, with `community_url`, the latest posts in a community, one window. Each post has its text, created_at, public_metrics (likes, reposts, replies, quotes, bookmarks, views), media, hashtags and mentions.\n\nGive exactly one of `username` or `url` or `community_url` to identify the source.\n\nCosts 13 credits (3 with `community_url`), whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 13, "x-credits-by": { "parameter": "community_url", "credits": { "*": 3 } }, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_x_posts", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The account's username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9_]{1,15})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The account's profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "community_url", "in": "query", "required": false, "description": "A community's URL, `https://x.com/i/communities/`: its latest posts.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/i/communities/\\d{5,25}([/?#]\\S*)?)$", "maxLength": 2048, "example": "https://x.com/i/communities/1471580197908586507" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/post": { "get": { "operationId": "get_x_post", "summary": "Get one post from X", "description": "Fetch one post by its URL or id: its text, author, created_at, public_metrics with views, media, hashtags and mentions, and the post it replies to or quotes.\n\nGive exactly one of `url` or `id` to identify the post.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 3, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_x_post", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL, `https://x.com//status/`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}/status(es)?/\\d{5,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The number after /status/ in its URL.", "schema": { "type": "string", "pattern": "^(?:\\d{5,25})$", "maxLength": 2048, "example": "1930652241230168143" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/replies": { "get": { "operationId": "get_x_replies", "summary": "Get the replies to an X post", "description": "Fetch the replies to one post, about 30 a page: each is a post, with its author, text, likes and replies, and `referenced_tweets` naming the post it answers.\n\nGive exactly one of `url` or `id` to identify the post.\n\nCosts 13 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 13, "x-cache-ttl-seconds": 3600, "x-mcp-tool": "get_x_replies", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}/status(es)?/\\d{5,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The post's id.", "schema": { "type": "string", "pattern": "^(?:\\d{5,25})$", "maxLength": 2048, "example": "1930652241230168143" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/retweeters": { "get": { "operationId": "get_x_retweeters", "summary": "Get who reposted an X post", "description": "Fetch the accounts that reposted one post, about 20 a page, each with its counts and bio. X's API calls this \"retweeted by\".\n\nGive exactly one of `url` or `id` to identify the post.\n\nCosts 13 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 13, "x-cache-ttl-seconds": 10800, "x-mcp-tool": "get_x_retweeters", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}/status(es)?/\\d{5,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The post's id.", "schema": { "type": "string", "pattern": "^(?:\\d{5,25})$", "maxLength": 2048, "example": "1930652241230168143" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_user" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/followers": { "get": { "operationId": "get_x_followers", "summary": "Get an X account's followers or following", "description": "Fetch an account's followers, about 70 a page, or with `type=following` the accounts it follows: each an account, with its counts and bio. Use this to see who an audience is.\n\nGive exactly one of `username` or `url` to identify the account.\n\nCosts 13 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 13, "x-cache-ttl-seconds": 21600, "x-mcp-tool": "get_x_followers", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "username", "in": "query", "required": false, "description": "The username. A leading @ is fine.", "schema": { "type": "string", "pattern": "^(?:@?[A-Za-z0-9_]{1,15})$", "maxLength": 2048, "example": "nasa" } }, { "name": "url", "in": "query", "required": false, "description": "The profile URL.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/[A-Za-z0-9_]{1,15}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "type", "in": "query", "required": false, "description": "Who follows the account, or whom it follows.", "schema": { "type": "string", "enum": [ "followers", "following" ], "default": "followers" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_user" } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/search": { "get": { "operationId": "search_x", "summary": "Search X", "description": "Search X as its own search box does, newest first, about 20 a page; X's search operators work inside `query` (`from:nasa`, `since:2026-09-01`, `lang:en`). `type=user` finds accounts instead. Use this to follow a topic, a brand or a campaign.\n\nCosts 13 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 13, "x-cache-ttl-seconds": 1800, "x-mcp-tool": "search_x", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Words, a phrase, or X's search operators.", "schema": { "type": "string", "maxLength": 2048, "example": "nasa artemis" } }, { "name": "type", "in": "query", "required": false, "description": "Posts, or accounts.", "schema": { "type": "string", "enum": [ "post", "user" ], "default": "post" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` from the previous page. Omit for the first page.", "schema": { "type": "string", "maxLength": 2048 } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_post" }, { "$ref": "#/components/schemas/x_user" } ], "description": "`type=post` returns `x_post`; `type=user` returns `x_user`." } }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/x/community": { "get": { "operationId": "get_x_community", "summary": "Get an X community", "description": "Fetch one community: its name, description, member_count, created_at, join_policy, rules and creator. `x/posts` with `community_url` gives its posts.\n\nGive exactly one of `url` or `id` to identify the community.\n\nCosts 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.", "tags": [ "X" ], "x-credits": 3, "x-cache-ttl-seconds": 86400, "x-mcp-tool": "get_x_community", "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The community's URL, `https://x.com/i/communities/`.", "schema": { "type": "string", "pattern": "^(?:(https?://)?((www|mobile)\\.)?(x|twitter)\\.com/i/communities/\\d{5,25}([/?#]\\S*)?)$", "maxLength": 2048 } }, { "name": "id", "in": "query", "required": false, "description": "The number in its URL.", "schema": { "type": "string", "pattern": "^(?:\\d{5,25})$", "maxLength": 2048, "example": "1926186499399139650" } }, { "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 } }, { "name": "demo", "in": "query", "required": false, "description": "With no key: a fixed demo answer in the same shape, charged nothing.", "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/x_community" }, "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" }, "500": { "$ref": "#/components/responses/error" }, "501": { "$ref": "#/components/responses/error" }, "502": { "$ref": "#/components/responses/error" } } } }, "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "The balance, the limits and this key", "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "account_id", "credits_remaining", "concurrency_limit", "key" ], "properties": { "account_id": { "type": "string" }, "plan": { "type": "string" }, "credits_remaining": { "type": "integer" }, "credits_granted": { "type": "integer" }, "period_start": { "type": "string", "format": "date-time" }, "concurrency_limit": { "type": "integer", "description": "Calls this account may have running at once." }, "concurrency_in_use": { "type": "integer" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "The platforms this key may call; empty means all." } } }, "usage_by_endpoint": { "type": "object", "description": "The newest 500 calls by endpoint, on the platforms this key may call.", "additionalProperties": { "type": "object", "properties": { "calls": { "type": "integer" }, "credits": { "type": "integer" }, "cached": { "type": "integer" }, "refunded": { "type": "integer" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } } } }, "/usage": { "get": { "operationId": "listUsage", "tags": [ "Account" ], "summary": "The usage ledger, newest first: one row a call", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "Rows on the platforms this key may call.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "request_id": { "type": "string" }, "endpoint": { "type": "string" }, "credits": { "type": "integer", "description": "0 for a refunded call." }, "refunded": { "type": "boolean" }, "credits_refunded": { "type": "integer" }, "cached": { "type": "boolean" }, "status": { "type": "integer" }, "duration_ms": { "type": "integer" } } } } } } } } }, "400": { "$ref": "#/components/responses/error" }, "401": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } } } }, "/endpoints": { "get": { "operationId": "listEndpoints", "tags": [ "Catalogue" ], "summary": "Every endpoint: its price, parameters and what it returns", "security": [ {} ], "responses": { "200": { "description": "The endpoint table.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string" }, "surface": { "type": "string" }, "summary": { "type": "string" }, "available": { "type": "boolean", "description": "Whether a call can be served now: false for an endpoint not offered yet, and for one that cannot be served this minute, as `/v1/status` shows." }, "unavailable_because": { "type": "string", "description": "Why it is not available, when it is not." }, "credits": { "type": "integer" }, "credits_by": { "type": "object", "properties": { "parameter": { "type": "string" }, "credits": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "returns": { "type": "string" }, "list": { "type": "boolean" }, "cache_ttl_seconds": { "type": "integer" }, "parameters": { "type": "array", "items": { "type": "object" } } } } } } } } } } } } }, "/errors": { "get": { "operationId": "listErrors", "tags": [ "Catalogue" ], "summary": "Every error code: when it happens and what to do", "security": [ {} ], "responses": { "200": { "description": "The error catalogue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "method_not_allowed", "permission_error", "not_found", "rate_limit", "upstream_error", "not_available", "internal_error" ] }, "when": { "type": "string" }, "fix": { "type": "string" } } } } } } } } } } } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "Catalogue" ], "summary": "Whether each endpoint is working now", "security": [ {} ], "responses": { "200": { "description": "The state of the API.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "operational", "degraded", "unavailable" ] }, "checked_at": { "type": "string", "format": "date-time" }, "measured_at": { "type": "string", "format": "date-time", "description": "When the 30-day numbers were read: at most a minute before `checked_at`." }, "surfaces": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string" }, "state": { "type": "string", "enum": [ "operational", "degraded", "unavailable" ] }, "credits": { "type": "integer" }, "success_rate": { "type": [ "number", "null" ], "description": "Answered calls of all counted, in percent, the last 30 days. Null below 50 calls." }, "p50_ms": { "type": [ "integer", "null" ], "description": "The median answer time, the last 30 days. Null below 50 calls." }, "p95_ms": { "type": [ "integer", "null" ], "description": "95 of 100 answers came in this time or less, the last 30 days. Null below 50 calls." }, "calls_30d": { "type": "integer" } } } } } } } } } } } } } } }, "/signup": { "post": { "operationId": "startSignup", "tags": [ "Account" ], "summary": "Ask for an account and a key for the person you work for", "security": [ {} ], "description": "No key needed. We email the person a link; they sign in and type `user_code`, which you show them. Then poll `GET /signup` with `id` as the bearer token. An account an agent starts has no free credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The person's address. The account is theirs." }, "agent": { "type": "string", "maxLength": 60, "description": "What you are called, as they know you: shown to them in the email." } } } } } }, "responses": { "202": { "description": "The request, waiting for the person.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "user_code", "status", "expires_at" ], "properties": { "id": { "type": "string", "description": "A secret worth a key: send it as the bearer token of `GET /signup`, never in a URL." }, "user_code": { "type": "string", "description": "Show this to the person: they type it to approve you." }, "status": { "type": "string", "enum": [ "pending" ] }, "expires_at": { "type": "string", "format": "date-time" }, "retry_after": { "type": "integer", "description": "Seconds to wait between polls." }, "next": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "500": { "$ref": "#/components/responses/error" } } }, "get": { "operationId": "pollSignup", "tags": [ "Account" ], "summary": "Whether the person approved you; the key, once", "description": "Send the request's `id` as `Authorization: Bearer sfsu_…`. `approved` carries `api_key` once; later polls say `delivered`.", "responses": { "200": { "description": "How the request stands.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "delivered", "expired", "cancelled" ] }, "api_key": { "type": "string", "description": "With `approved` only, once." }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" } } }, "credits_remaining": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "retry_after": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/error" }, "403": { "$ref": "#/components/responses/error" }, "404": { "$ref": "#/components/responses/error" }, "500": { "$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. 0 for a demo answer, and for a list emptied because everyone in it asked not to be served. A failed call has no `meta`: it answers with an error, and is refunded." }, "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. It lasts as long as the answer is cached." }, "demo": { "type": "boolean", "description": "Present, and true, on a demo answer (`?demo=true` with no key)." }, "note": { "type": "string", "description": "On a demo answer: what it is, and what a live call costs." } } }, "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": "One category." }, "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. `null` where the source gives the address as one line: see `formatted_address`." }, "city": { "type": [ "string", "null" ], "description": "City or town." }, "region": { "type": [ "string", "null" ], "description": "State, province or region." }, "postal_code": { "type": [ "string", "null" ], "description": "Postal or ZIP code." }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2, e.g. `US`." } }, "additionalProperties": false, "description": "The same address in parts. Where the source gives the address as one line, only `country_code` is filled." }, "location": { "type": [ "object", "null" ], "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "description": "Latitude." }, "lng": { "type": "number", "description": "Longitude." } }, "additionalProperties": false, "description": "The pin. `null` when the source does not give it." }, "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", "description": "One-star ratings." }, "2": { "type": "integer", "description": "Two-star ratings." }, "3": { "type": "integer", "description": "Three-star ratings." }, "4": { "type": "integer", "description": "Four-star ratings." }, "5": { "type": "integer", "description": "Five-star ratings." } }, "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": "One day, e.g. \"Monday: 8:30 AM – 5:30 PM\" or \"Sunday: Closed\"." }, "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, "description": "When it opens." }, "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, "description": "When it closes." } }, "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": "One hour, 0–100." }, "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": "One item, e.g. \"Takeout\"." }, "description": "The items under one heading, as the listing prints them." }, "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", "null" ], "description": "As shown on the review. `null` where the source gives none." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Their Google Maps contributor page." }, "profile_photo_url": { "type": [ "string", "null" ], "format": "uri", "description": "Their profile photo." }, "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, "description": "Who wrote the review." }, "rating": { "type": [ "integer", "null" ], "description": "1 to 5. `null` when the source gives no rating." }, "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", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "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", "description": "The owner's reply." }, "publish_time": { "type": [ "string", "null" ], "format": "date-time", "description": "When the owner replied. `null` when the source does not say." } }, "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." }, "google_maps_post": { "type": "object", "required": [ "text", "date", "image_url", "link_url" ], "properties": { "text": { "type": [ "string", "null" ], "description": "The post's text." }, "date": { "type": [ "string", "null" ], "description": "`YYYY-MM-DD`: the day the listing shows; it gives no time." }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The post's image." }, "link_url": { "type": [ "string", "null" ], "format": "uri", "description": "Where the post links, such as a booking page." } }, "additionalProperties": false, "description": "An update the owner posted on a Google Maps 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", "emails" ], "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", "description": "The name, as the profile shows it." }, "first_name": { "type": [ "string", "null" ], "description": "The given name." }, "last_name": { "type": [ "string", "null" ], "description": "The family name." }, "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", "description": "The profile photo." }, "follower_count": { "type": [ "integer", "null" ], "description": "How many members follow the profile." }, "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", "null" ], "description": "As the listing prints it." }, "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", "is_current", "description" ], "properties": { "title": { "type": [ "string", "null" ], "description": "As the position shows it. `null` where the profile gives none." }, "company": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "As the listing prints it." }, "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" ], "description": "Where the role is based, as printed." }, "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: `is_current` tells which." }, "is_current": { "type": [ "boolean", "null" ], "description": "`true` where the profile says the role runs to the present, `false` where it gives an end date, `null` where it gives no dates." }, "description": { "type": [ "string", "null" ], "description": "What the profile says about the role." } }, "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", "null" ], "description": "As the listing prints it." }, "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" ], "description": "As printed, e.g. \"Bachelor of Science - BS\"." }, "field_of_study": { "type": [ "string", "null" ], "description": "As printed, e.g. \"Computer Science\"." }, "start_year": { "type": [ "integer", "null" ], "description": "The year they started." }, "end_year": { "type": [ "integer", "null" ], "description": "The year they finished, or expect to." } }, "additionalProperties": false }, "description": "Schools, most recent first." }, "skills": { "type": "array", "items": { "type": "string", "description": "One skill." }, "description": "As listed on the profile." }, "emails": { "type": "array", "items": { "type": "object", "required": [ "email", "status", "deliverable", "catch_all", "free_provider" ], "properties": { "email": { "type": "string", "description": "The address." }, "status": { "type": [ "string", "null" ], "description": "`valid` when their mail server accepts it; `risky` when the server accepts every address, so this one cannot be confirmed." }, "deliverable": { "type": [ "boolean", "null" ], "description": "Whether mail to it should arrive." }, "catch_all": { "type": [ "boolean", "null" ], "description": "Whether the domain accepts any address at all, which makes a check meaningless." }, "free_provider": { "type": [ "boolean", "null" ], "description": "Whether it is at a free mail service, such as Gmail, rather than an employer's domain." } }, "additionalProperties": false, "description": "One address." }, "description": "Their work email, found with `detail=with_email` only, best first; empty otherwise, or when none is found." } }, "additionalProperties": false, "description": "A LinkedIn profile." }, "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", "description": "The company's name, as the page shows it." }, "tagline": { "type": [ "string", "null" ], "description": "The line under the name." }, "description": { "type": [ "string", "null" ], "description": "The About overview." }, "website": { "type": [ "string", "null" ], "format": "uri", "description": "The company's own site." }, "industry": { "type": [ "string", "null" ], "description": "As the page prints it, e.g. \"Software Development\"." }, "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" ], "description": "The city." }, "geographic_area": { "type": [ "string", "null" ], "description": "State or region." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." } }, "additionalProperties": false, "description": "Where the company has its head office, as the page gives it." }, "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", "description": "One specialty." }, "description": "The specialties the page lists." }, "follower_count": { "type": [ "integer", "null" ], "description": "How many members follow the page." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The company's logo." } }, "additionalProperties": false, "description": "A 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", "null" ], "description": "`null` where the source names only the page." }, "type": { "type": "string", "enum": [ "person", "company" ], "description": "Whether a person or a company page posted it." }, "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, "description": "Who posted it: a person or a company page." }, "text": { "type": [ "string", "null" ], "description": "The post's text." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` where the source does not say." }, "reaction_count": { "type": [ "integer", "null" ], "description": "All reactions together. `null` where the source does not give the counts." }, "reactions": { "type": [ "object", "null" ], "required": [ "like", "celebrate", "support", "love", "insightful", "funny" ], "properties": { "like": { "type": "integer", "description": "Like reactions." }, "celebrate": { "type": "integer", "description": "Celebrate reactions." }, "support": { "type": "integer", "description": "Support reactions." }, "love": { "type": "integer", "description": "Love reactions." }, "insightful": { "type": "integer", "description": "Insightful reactions." }, "funny": { "type": "integer", "description": "Funny reactions." } }, "additionalProperties": false, "description": "By kind, where LinkedIn shows the breakdown." }, "comment_count": { "type": [ "integer", "null" ], "description": "How many comments. `null` where the source does not give it." }, "repost_count": { "type": [ "integer", "null" ], "description": "How many reposts. `null` where the source does not give it." }, "images": { "type": "array", "items": { "type": "string", "format": "uri", "description": "One image." }, "description": "Image URLs, in order." }, "video": { "type": [ "object", "null" ], "required": [ "url", "duration" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The video file." }, "duration": { "type": [ "integer", "null" ], "description": "Seconds." } }, "additionalProperties": false, "description": "A video in the post." }, "document": { "type": [ "object", "null" ], "required": [ "title", "page_count" ], "properties": { "title": { "type": "string", "description": "The document's title." }, "page_count": { "type": [ "integer", "null" ], "description": "How many pages it has." } }, "additionalProperties": false, "description": "An attached PDF or slide deck." }, "article": { "type": [ "object", "null" ], "required": [ "title", "url" ], "properties": { "title": { "type": [ "string", "null" ], "description": "The title the link's preview shows." }, "url": { "type": "string", "format": "uri", "description": "Where the link leads." } }, "additionalProperties": false, "description": "A shared link." }, "is_repost": { "type": [ "boolean", "null" ], "description": "Whether this is someone else's post reposted without comment. `null` where the source does not say." } }, "additionalProperties": false, "description": "A LinkedIn post." }, "linkedin_comment": { "type": "object", "required": [ "id", "url", "post_urn", "parent_id", "text", "author", "published_at", "like_count", "reply_count" ], "properties": { "id": { "type": "string", "description": "LinkedIn's id for the comment." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The comment's own link, as LinkedIn's \"Copy link to comment\" gives it: it opens the post at this comment, and linkedin/comments and linkedin/reactions take it as `comment_url`. `null` for a reply whose link the source does not give." }, "post_urn": { "type": [ "string", "null" ], "description": "The post it is on, e.g. `urn:li:activity:7243…`." }, "parent_id": { "type": [ "string", "null" ], "description": "The comment it answers, for a reply." }, "text": { "type": [ "string", "null" ], "description": "The comment's text." }, "author": { "type": "object", "required": [ "type", "vanity_name", "url", "full_name", "headline", "location", "services" ], "properties": { "type": { "type": "string", "enum": [ "person", "company" ], "description": "A company page can comment and react as itself." }, "vanity_name": { "type": [ "string", "null" ], "description": "The public name in the URL: after `/in/` for a person, after `/company/` for a company. `null` where LinkedIn gives only an id." }, "url": { "type": "string", "format": "uri", "description": "Their page. Where LinkedIn lists a person by member id, as it does a post's reactors, this is a member-id link (`/in/ACoAA…`)." }, "full_name": { "type": [ "string", "null" ], "description": "The person's name, or the company's." }, "headline": { "type": [ "string", "null" ], "description": "The line under the name. For a company, LinkedIn prints its follower count here." }, "location": { "type": [ "string", "null" ], "description": "As printed. `null` in most lists." }, "services": { "type": "array", "items": { "type": "string", "description": "One service." }, "description": "What they offer, for someone found by linkedin/services. Empty in other lists." } }, "additionalProperties": false, "description": "Who wrote it." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "like_count": { "type": [ "integer", "null" ], "description": "Reactions to the comment, all kinds together." }, "reply_count": { "type": [ "integer", "null" ], "description": "How many replies it has." } }, "additionalProperties": false, "description": "A comment on a LinkedIn post." }, "linkedin_reaction": { "type": "object", "required": [ "kind", "actor" ], "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "like", "celebrate", "support", "love", "insightful", "funny", null ], "description": "As LinkedIn's reaction menu names them. `null` for a kind it adds later." }, "actor": { "type": "object", "required": [ "type", "vanity_name", "url", "full_name", "headline", "location", "services" ], "properties": { "type": { "type": "string", "enum": [ "person", "company" ], "description": "A company page can comment and react as itself." }, "vanity_name": { "type": [ "string", "null" ], "description": "The public name in the URL: after `/in/` for a person, after `/company/` for a company. `null` where LinkedIn gives only an id." }, "url": { "type": "string", "format": "uri", "description": "Their page. Where LinkedIn lists a person by member id, as it does a post's reactors, this is a member-id link (`/in/ACoAA…`)." }, "full_name": { "type": [ "string", "null" ], "description": "The person's name, or the company's." }, "headline": { "type": [ "string", "null" ], "description": "The line under the name. For a company, LinkedIn prints its follower count here." }, "location": { "type": [ "string", "null" ], "description": "As printed. `null` in most lists." }, "services": { "type": "array", "items": { "type": "string", "description": "One service." }, "description": "What they offer, for someone found by linkedin/services. Empty in other lists." } }, "additionalProperties": false, "description": "Who reacted: a person, or a company page." } }, "additionalProperties": false, "description": "A reaction to a LinkedIn post: who, and which." }, "linkedin_activity": { "type": "object", "required": [ "type", "comment", "comment_url", "reaction", "at", "post_url", "post" ], "properties": { "type": { "type": "string", "enum": [ "comment", "reaction" ], "description": "What the person did." }, "comment": { "type": [ "string", "null" ], "description": "For a comment: its text." }, "comment_url": { "type": [ "string", "null" ], "format": "uri", "description": "For a comment: its own link, which opens the post at this comment. `null` for a reaction, and where the source does not give it." }, "reaction": { "type": [ "string", "null" ], "enum": [ "like", "celebrate", "support", "love", "insightful", "funny", null ], "description": "For a reaction: which." }, "at": { "type": [ "string", "null" ], "format": "date-time", "description": "When they commented or reacted. `null` where the source does not say, as for some reactions." }, "post_url": { "type": "string", "format": "uri", "description": "The post or article they commented on or reacted to." }, "post": { "type": [ "object", "null" ], "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", "null" ], "description": "`null` where the source names only the page." }, "type": { "type": "string", "enum": [ "person", "company" ], "description": "Whether a person or a company page posted it." }, "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, "description": "Who posted it: a person or a company page." }, "text": { "type": [ "string", "null" ], "description": "The post's text." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` where the source does not say." }, "reaction_count": { "type": [ "integer", "null" ], "description": "All reactions together. `null` where the source does not give the counts." }, "reactions": { "type": [ "object", "null" ], "required": [ "like", "celebrate", "support", "love", "insightful", "funny" ], "properties": { "like": { "type": "integer", "description": "Like reactions." }, "celebrate": { "type": "integer", "description": "Celebrate reactions." }, "support": { "type": "integer", "description": "Support reactions." }, "love": { "type": "integer", "description": "Love reactions." }, "insightful": { "type": "integer", "description": "Insightful reactions." }, "funny": { "type": "integer", "description": "Funny reactions." } }, "additionalProperties": false, "description": "By kind, where LinkedIn shows the breakdown." }, "comment_count": { "type": [ "integer", "null" ], "description": "How many comments. `null` where the source does not give it." }, "repost_count": { "type": [ "integer", "null" ], "description": "How many reposts. `null` where the source does not give it." }, "images": { "type": "array", "items": { "type": "string", "format": "uri", "description": "One image." }, "description": "Image URLs, in order." }, "video": { "type": [ "object", "null" ], "required": [ "url", "duration" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The video file." }, "duration": { "type": [ "integer", "null" ], "description": "Seconds." } }, "additionalProperties": false, "description": "A video in the post." }, "document": { "type": [ "object", "null" ], "required": [ "title", "page_count" ], "properties": { "title": { "type": "string", "description": "The document's title." }, "page_count": { "type": [ "integer", "null" ], "description": "How many pages it has." } }, "additionalProperties": false, "description": "An attached PDF or slide deck." }, "article": { "type": [ "object", "null" ], "required": [ "title", "url" ], "properties": { "title": { "type": [ "string", "null" ], "description": "The title the link's preview shows." }, "url": { "type": "string", "format": "uri", "description": "Where the link leads." } }, "additionalProperties": false, "description": "A shared link." }, "is_repost": { "type": [ "boolean", "null" ], "description": "Whether this is someone else's post reposted without comment. `null` where the source does not say." } }, "additionalProperties": false, "description": "The post, with its author and counts. `null` for an article, whose author the source does not give: `post_url` says where it was." } }, "additionalProperties": false, "description": "Something a person did on someone else's post: a comment or a reaction, with the post." }, "linkedin_member": { "type": "object", "required": [ "type", "vanity_name", "url", "full_name", "headline", "location", "services" ], "properties": { "type": { "type": "string", "enum": [ "person", "company" ], "description": "A company page can comment and react as itself." }, "vanity_name": { "type": [ "string", "null" ], "description": "The public name in the URL: after `/in/` for a person, after `/company/` for a company. `null` where LinkedIn gives only an id." }, "url": { "type": "string", "format": "uri", "description": "Their page. Where LinkedIn lists a person by member id, as it does a post's reactors, this is a member-id link (`/in/ACoAA…`)." }, "full_name": { "type": [ "string", "null" ], "description": "The person's name, or the company's." }, "headline": { "type": [ "string", "null" ], "description": "The line under the name. For a company, LinkedIn prints its follower count here." }, "location": { "type": [ "string", "null" ], "description": "As printed. `null` in most lists." }, "services": { "type": "array", "items": { "type": "string", "description": "One service." }, "description": "What they offer, for someone found by linkedin/services. Empty in other lists." } }, "additionalProperties": false, "description": "A person or a company in a list: a post's reactors, a comment's author, a people search's results." }, "linkedin_ad": { "type": "object", "required": [ "id", "url", "advertiser", "format", "headline", "text", "image_url", "video_url", "carousel_image_urls", "call_to_action", "destination_url", "first_shown", "last_shown", "impressions", "impressions_by_country", "targeting" ], "properties": { "id": { "type": "string", "description": "The Ad Library's id for the ad." }, "url": { "type": "string", "format": "uri", "description": "The ad in LinkedIn's Ad Library." }, "advertiser": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "The advertiser's name. `null` where the source does not give it." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Their company page, or a person's profile for an ad a person runs." } }, "additionalProperties": false, "description": "Who paid for the ad." }, "format": { "type": [ "string", "null" ], "description": "As the library names it, e.g. \"Single Image Ad\"." }, "headline": { "type": [ "string", "null" ], "description": "The ad's headline." }, "text": { "type": [ "string", "null" ], "description": "The ad's text." }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The ad's image." }, "video_url": { "type": [ "string", "null" ], "format": "uri", "description": "The ad's video." }, "carousel_image_urls": { "type": "array", "items": { "type": "string", "format": "uri", "description": "One image." }, "description": "A carousel's images, in order." }, "call_to_action": { "type": [ "string", "null" ], "description": "The button, e.g. \"Learn more\"." }, "destination_url": { "type": [ "string", "null" ], "format": "uri", "description": "Where the ad leads." }, "first_shown": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was first shown, as the library dates it." }, "last_shown": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last shown, as the library dates it." }, "impressions": { "type": [ "string", "null" ], "description": "The range the library shows, e.g. \"1k-5k\" or \"<1k\"." }, "impressions_by_country": { "type": "array", "items": { "type": "object", "required": [ "country", "share" ], "properties": { "country": { "type": "string", "description": "As the library names it." }, "share": { "type": [ "string", "null" ], "description": "The share it shows, e.g. \"61%\" or \"<1%\"." } }, "additionalProperties": false }, "description": "Where the ad was seen, as linkedin/ad gives it. Empty in a search." }, "targeting": { "type": "object", "required": [ "language", "location" ], "properties": { "language": { "type": [ "string", "null" ], "description": "As the library prints it." }, "location": { "type": [ "string", "null" ], "description": "As the library prints it." } }, "additionalProperties": false, "description": "Whom the ad was aimed at, as the library shows it." } }, "additionalProperties": false, "description": "An ad from LinkedIn's Ad Library." }, "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", "null" ], "description": "As the listing prints it." }, "company": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "As the listing prints it." }, "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 ], "description": "Where the work is done, as LinkedIn labels it. `null` where the listing does not say." }, "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", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "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 LinkedIn job posting." }, "linkedin_lead": { "type": "object", "required": [ "vanity_name", "url", "first_name", "last_name", "full_name", "location", "profile_picture_url", "premium", "open_profile", "current_positions" ], "properties": { "vanity_name": { "type": [ "string", "null" ], "description": "The public name after `/in/`. `null` where Sales Navigator gives only a member id." }, "url": { "type": "string", "format": "uri", "description": "Their profile. Sales Navigator often gives a member-id link (`/in/ACwAA…`) instead of a public name." }, "first_name": { "type": [ "string", "null" ], "description": "The given name." }, "last_name": { "type": [ "string", "null" ], "description": "The family name." }, "full_name": { "type": [ "string", "null" ], "description": "First and last name together." }, "location": { "type": [ "string", "null" ], "description": "As printed." }, "profile_picture_url": { "type": [ "string", "null" ], "format": "uri", "description": "The profile photo." }, "premium": { "type": [ "boolean", "null" ], "description": "Whether they pay for LinkedIn Premium." }, "open_profile": { "type": [ "boolean", "null" ], "description": "Whether anyone can message them, connected or not." }, "current_positions": { "type": "array", "items": { "type": "object", "required": [ "title", "company", "company_id", "start_date", "description" ], "properties": { "title": { "type": [ "string", "null" ], "description": "The job title, as printed." }, "company": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "As the listing prints it." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The company page, where it has one." } }, "additionalProperties": false, "description": "The employer." }, "company_id": { "type": [ "string", "null" ], "description": "LinkedIn's numeric id for the employer." }, "start_date": { "type": [ "string", "null" ], "description": "`YYYY-MM`, or `YYYY` where only a year is given." }, "description": { "type": [ "string", "null" ], "description": "What they wrote about the role." } }, "additionalProperties": false }, "description": "What they do now, as Sales Navigator lists it." } }, "additionalProperties": false, "description": "A person from Sales Navigator's lead search: every match, with their current roles." }, "linkedin_company_result": { "type": "object", "required": [ "company_id", "vanity_name", "url", "name", "industry", "location", "follower_count", "summary", "logo_url" ], "properties": { "company_id": { "type": "string", "description": "LinkedIn's numeric id for the company: linkedin/employees, linkedin/employee-stats, linkedin/jobs and linkedin/ads take it as `company_id`, and linkedin/people as a filter." }, "vanity_name": { "type": [ "string", "null" ], "description": "The part after `/company/` in the page URL." }, "url": { "type": "string", "format": "uri", "description": "The company page." }, "name": { "type": "string", "description": "The company's name." }, "industry": { "type": [ "string", "null" ], "description": "As the search prints it." }, "location": { "type": [ "string", "null" ], "description": "As the search prints it." }, "follower_count": { "type": [ "integer", "null" ], "description": "`null` where LinkedIn prints a rounded number, such as \"12K followers\"." }, "summary": { "type": [ "string", "null" ], "description": "The line the search shows under the name." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The company's logo." } }, "additionalProperties": false, "description": "A company in LinkedIn's company search." }, "linkedin_employee_stats": { "type": "object", "required": [ "company_id", "vanity_name", "url", "stats" ], "properties": { "company_id": { "type": [ "string", "null" ], "description": "LinkedIn's numeric id for the company." }, "vanity_name": { "type": [ "string", "null" ], "description": "The part after `/company/` in the page URL." }, "url": { "type": "string", "format": "uri", "description": "The company page." }, "stats": { "type": "array", "items": { "type": "object", "required": [ "dimension", "values" ], "properties": { "dimension": { "type": "string", "description": "What LinkedIn counts them by, as its People tab names it: \"Where they live\", \"What they do\", \"Where they studied\", …" }, "values": { "type": "array", "items": { "type": "object", "required": [ "name", "count" ], "properties": { "name": { "type": "string", "description": "What is counted: a place, a job function, a school, …" }, "count": { "type": "integer", "description": "How many members." } }, "additionalProperties": false }, "description": "The largest first." } }, "additionalProperties": false }, "description": "One block per question the People tab answers." } }, "additionalProperties": false, "description": "Who works at a company, counted: where they live, what they do, where they studied, what they are skilled at." }, "linkedin_group": { "type": "object", "required": [ "group_id", "url", "name", "member_count", "description", "rules", "created_at", "logo_url", "is_public" ], "properties": { "group_id": { "type": "string", "description": "LinkedIn's numeric id for the group." }, "url": { "type": "string", "format": "uri", "description": "The group." }, "name": { "type": "string", "description": "The group's name." }, "member_count": { "type": [ "integer", "null" ], "description": "How many members. `null` where LinkedIn prints a rounded number, such as \"12K members\"." }, "description": { "type": [ "string", "null" ], "description": "The About text. In a search, the short summary." }, "rules": { "type": [ "string", "null" ], "description": "`null` in a search." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` in a search." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The group's logo." }, "is_public": { "type": [ "boolean", "null" ], "description": "Whether anyone can see its posts. `null` in a search." } }, "additionalProperties": false, "description": "A LinkedIn group." }, "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" ], "description": "The bio." }, "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" ], "description": "The link's label, where it has one." }, "url": { "type": "string", "format": "uri", "description": "Where the link leads." } }, "additionalProperties": false }, "description": "Every link in the bio." }, "profile_picture_url": { "type": [ "string", "null" ], "format": "uri", "description": "The profile picture. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media." }, "followers_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "follows_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "media_count": { "type": [ "integer", "null" ], "description": "Posts on the grid." }, "is_verified": { "type": "boolean", "description": "Whether the account has the verified badge." }, "is_private": { "type": "boolean", "description": "A private account shows its counts and nothing else." }, "is_business_account": { "type": [ "boolean", "null" ], "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", "null" ], "description": "Story highlights on the profile." } }, "additionalProperties": false, "description": "An Instagram account." }, "instagram_search_result": { "type": "object", "required": [ "username", "name", "url" ], "properties": { "username": { "type": "string", "description": "Without the @." }, "name": { "type": [ "string", "null" ], "description": "The display name, as the search index has it." }, "url": { "type": "string", "format": "uri", "description": "The account's page." } }, "additionalProperties": false, "description": "An Instagram account that a search found. Call `instagram/profile` with its username for the whole 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" ], "description": "The caption." }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "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. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media." }, "thumbnail_url": { "type": [ "string", "null" ], "format": "uri", "description": "The cover of a video. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media." }, "children": { "type": "array", "items": { "type": "object", "required": [ "media_type", "media_url" ], "properties": { "media_type": { "type": "string", "enum": [ "IMAGE", "VIDEO" ], "description": "An image or a video." }, "media_url": { "type": "string", "format": "uri", "description": "The image, or the video file. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media." } }, "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", "null" ], "description": "`null` when the source does not give it." }, "view_count": { "type": [ "integer", "null" ], "description": "Views, for videos and Reels." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "One hashtag." }, "description": "The caption's hashtags, without the #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "One username." }, "description": "The usernames the caption mentions, without the @." }, "location": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Instagram's id for the location." }, "name": { "type": "string", "description": "The place's name, as the tag shows it." } }, "additionalProperties": false, "description": "The location tag." }, "is_paid_partnership": { "type": [ "boolean", "null" ], "description": "Whether it carries the \"Paid partnership\" label. `null` where that is not known." } }, "additionalProperties": false, "description": "An 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", "description": "Instagram's id for the comment." }, "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", "description": "Who wrote it, without the @." }, "text": { "type": [ "string", "null" ], "description": "`null` for a comment with no words, such as a GIF." }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` when the source does not say." }, "like_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "reply_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." } }, "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" ], "description": "The display name." }, "bio_description": { "type": [ "string", "null" ], "description": "The bio." }, "bio_url": { "type": [ "string", "null" ], "format": "uri", "description": "The link in the bio." }, "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "The profile picture. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "profile_url": { "type": "string", "format": "uri", "description": "The profile." }, "is_verified": { "type": "boolean", "description": "Whether the account has the verified badge." }, "follower_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "following_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "likes_count": { "type": [ "integer", "null" ], "description": "Likes across all their videos. `null` when the source does not give it." }, "video_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." } }, "additionalProperties": false, "description": "A 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", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "duration": { "type": [ "integer", "null" ], "description": "Seconds. `null` when the source does not give it." }, "cover_image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The video's cover image. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "play_url": { "type": [ "string", "null" ], "format": "uri", "description": "The video file. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "view_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "like_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "comment_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "share_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "favorites_count": { "type": [ "integer", "null" ], "description": "Saves. `null` where the page does not show them." }, "hashtag_names": { "type": "array", "items": { "type": "string", "description": "One hashtag." }, "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", "description": "TikTok's id for the sound." }, "title": { "type": "string", "description": "The sound's name, as TikTok shows it." }, "author": { "type": [ "string", "null" ], "description": "Who the sound is credited to." }, "original": { "type": "boolean", "description": "An original sound rather than a track." } }, "additionalProperties": false, "description": "The sound." }, "duet_enabled": { "type": [ "boolean", "null" ], "description": "`null` where that is not known." }, "stitch_enabled": { "type": [ "boolean", "null" ], "description": "`null` where that is not known." } }, "additionalProperties": false, "description": "A 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", "description": "TikTok's id for the comment." }, "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", "description": "Who wrote it, without the @." }, "text": { "type": [ "string", "null" ], "description": "`null` for a comment with no words, such as a sticker." }, "create_time": { "type": [ "string", "null" ], "format": "date-time", "description": "`null` when the source does not say." }, "like_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." }, "reply_count": { "type": [ "integer", "null" ], "description": "`null` when the source does not give it." } }, "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" ], "description": "How many videos use it." }, "view_count": { "type": [ "integer", "null" ], "description": "Views across its videos." } }, "additionalProperties": false, "description": "A TikTok hashtag, from a search." }, "tiktok_ad": { "type": "object", "required": [ "id", "url", "advertiser", "title", "industry", "first_shown", "last_shown", "video_url", "cover_image_url", "image_urls", "estimated_audience", "impressions" ], "properties": { "id": { "type": "string", "description": "The Ad Library's id for the ad." }, "url": { "type": "string", "format": "uri", "description": "The ad in TikTok's Ad Library." }, "advertiser": { "type": [ "string", "null" ], "description": "The name the ad runs under." }, "title": { "type": [ "string", "null" ], "description": "The ad's title, as the library shows it." }, "industry": { "type": [ "string", "null" ], "description": "As the library files it, e.g. \"Apparel & Accessories\"." }, "first_shown": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was first shown, as the library dates it." }, "last_shown": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last shown, as the library dates it." }, "video_url": { "type": [ "string", "null" ], "format": "uri", "description": "The ad's video. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "cover_image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The video's cover image. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri", "description": "One image." }, "description": "The ad's images, in order. On TikTok's CDN. TikTok signs the link, and it can stop working within hours, so fetch the file soon. We do not rehost media." }, "estimated_audience": { "type": [ "string", "null" ], "description": "The range the library shows, e.g. \"1K-10K\"." }, "impressions": { "type": [ "integer", "null" ], "description": "How many times it was shown, as the library counts it. `null` where the library leaves it blank." } }, "additionalProperties": false, "description": "An ad from TikTok's Ad Library." }, "x_user": { "type": "object", "required": [ "id", "username", "name", "description", "location", "url", "profile_url", "profile_image_url", "profile_banner_url", "created_at", "verified", "protected", "public_metrics", "pinned_tweet_id" ], "properties": { "id": { "type": "string", "description": "X's numeric id for the account." }, "username": { "type": "string", "description": "Without the @." }, "name": { "type": [ "string", "null" ], "description": "The display name." }, "description": { "type": [ "string", "null" ], "description": "The bio." }, "location": { "type": [ "string", "null" ], "description": "As they wrote it." }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The link in their profile, unshortened, as X's API names it." }, "profile_url": { "type": "string", "format": "uri", "description": "The account on X." }, "profile_image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The profile picture, at full size." }, "profile_banner_url": { "type": [ "string", "null" ], "format": "uri", "description": "The header image above the profile." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the account was made." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether it has a checkmark, of any kind." }, "protected": { "type": [ "boolean", "null" ], "description": "Whether its posts are private." }, "public_metrics": { "type": "object", "required": [ "followers_count", "following_count", "tweet_count", "listed_count", "like_count", "media_count" ], "properties": { "followers_count": { "type": [ "integer", "null" ], "description": "How many accounts follow them." }, "following_count": { "type": [ "integer", "null" ], "description": "How many accounts they follow." }, "tweet_count": { "type": [ "integer", "null" ], "description": "Posts, replies and reposts together, as X counts them." }, "listed_count": { "type": [ "integer", "null" ], "description": "How many lists include them." }, "like_count": { "type": [ "integer", "null" ], "description": "Posts they have liked." }, "media_count": { "type": [ "integer", "null" ], "description": "Posts with photos or videos." } }, "additionalProperties": false, "description": "The counts on the profile. `null` where the source does not give one." }, "pinned_tweet_id": { "type": [ "string", "null" ], "description": "The id of the post pinned to the profile. `null` where there is none, or the source does not say." } }, "additionalProperties": false, "description": "An X account." }, "x_post": { "type": "object", "required": [ "id", "url", "text", "created_at", "lang", "author", "conversation_id", "referenced_tweets", "public_metrics", "media", "hashtags", "mentions" ], "properties": { "id": { "type": "string", "description": "X's id for the post." }, "url": { "type": "string", "format": "uri", "description": "The post on X." }, "text": { "type": [ "string", "null" ], "description": "The whole text. Links stay as X shortens them." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was posted. `null` when the source does not say." }, "lang": { "type": [ "string", "null" ], "description": "The language X detected, e.g. `en`." }, "author": { "type": "object", "required": [ "id", "username", "name", "profile_url", "profile_image_url", "verified" ], "properties": { "id": { "type": [ "string", "null" ], "description": "X's numeric id for the account." }, "username": { "type": "string", "description": "Without the @." }, "name": { "type": [ "string", "null" ], "description": "The display name." }, "profile_url": { "type": "string", "format": "uri", "description": "The account on X." }, "profile_image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The profile picture, at full size." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account has a checkmark." } }, "additionalProperties": false, "description": "Who posted it." }, "conversation_id": { "type": [ "string", "null" ], "description": "The first post of the thread it belongs to." }, "referenced_tweets": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ], "description": "How this post refers to it: a reply, a quote or a repost." }, "id": { "type": "string", "description": "X's id for that post." } }, "additionalProperties": false }, "description": "The post it replies to, quotes or reposts, as X's API names them." }, "public_metrics": { "type": "object", "required": [ "retweet_count", "reply_count", "like_count", "quote_count", "bookmark_count", "impression_count" ], "properties": { "retweet_count": { "type": [ "integer", "null" ], "description": "Reposts." }, "reply_count": { "type": [ "integer", "null" ], "description": "Replies." }, "like_count": { "type": [ "integer", "null" ], "description": "Likes." }, "quote_count": { "type": [ "integer", "null" ], "description": "Quotes." }, "bookmark_count": { "type": [ "integer", "null" ], "description": "Bookmarks." }, "impression_count": { "type": [ "integer", "null" ], "description": "Views." } }, "additionalProperties": false, "description": "`null` where the source does not give one." }, "media": { "type": "array", "items": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "photo", "video", "animated_gif", null ], "description": "`null` where the source does not say." }, "url": { "type": "string", "format": "uri", "description": "The image, or a video's preview image." } }, "additionalProperties": false }, "description": "Photos and videos, in order." }, "hashtags": { "type": "array", "items": { "type": "string", "description": "One hashtag." }, "description": "Without the #." }, "mentions": { "type": "array", "items": { "type": "string", "description": "One username." }, "description": "Usernames, without the @." } }, "additionalProperties": false, "description": "A post on X: a post, a reply or a quote." }, "x_community": { "type": "object", "required": [ "id", "url", "name", "description", "member_count", "created_at", "join_policy", "rules", "creator_username" ], "properties": { "id": { "type": "string", "description": "X's id for the community." }, "url": { "type": "string", "format": "uri", "description": "The community on X." }, "name": { "type": "string", "description": "The community's name." }, "description": { "type": [ "string", "null" ], "description": "What it is about, in its own words." }, "member_count": { "type": [ "integer", "null" ], "description": "How many members it has." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the community was made." }, "join_policy": { "type": [ "string", "null" ], "description": "As X names it: \"Open\" or \"Closed\"." }, "rules": { "type": "array", "items": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "The rule's title." }, "description": { "type": [ "string", "null" ], "description": "More about the rule. `null` where it has none." } }, "additionalProperties": false }, "description": "Its rules, in order." }, "creator_username": { "type": [ "string", "null" ], "description": "Who made it." } }, "additionalProperties": false, "description": "An X community." }, "error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "method_not_allowed", "permission_error", "not_found", "rate_limit", "upstream_error", "not_available", "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", "account_suspended", "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", "key_limit", "unverified_account", "unknown_endpoint", "missing_parameter", "missing_one_of", "invalid_parameter", "invalid_json", "invalid_cursor", "profile_not_found", "place_not_found", "subject_suppressed", "signup_not_found", "post_not_found", "posting_not_found", "group_not_found", "ad_not_found", "community_not_found", "endpoint_busy", "concurrency_limit", "method_not_allowed", "not_found_limit", "demo_limit", "not_available_yet", "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" }, "retry_after": { "type": "integer", "description": "On a 429: seconds to wait, as the `Retry-After` header says." } } } } } } } }