{ "openapi": "3.0.0", "info": { "title": "Social Fetch Public API", "version": "1.0.0", "description": "REST API for Social Fetch. Versioned routes under `/v1` require authentication via the `x-api-key` header (API key value)." }, "servers": [ { "url": "https://api.socialfetch.dev", "description": "API origin" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key (`sfk_...`)" } }, "schemas": {}, "parameters": {} }, "paths": { "/health": { "get": { "tags": ["System"], "summary": "Health check", "description": "Returns a simple health status indicating the API process is running.", "responses": { "200": { "description": "Service is running", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok"], "description": "Health status for the service." } }, "required": ["status"], "description": "Simple health check response." } } } }, "429": { "description": "Health endpoint rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/whoami": { "get": { "tags": ["Auth"], "summary": "Whoami", "description": "Returns the authenticated user associated with the API key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal Social Fetch user identifier." }, "name": { "type": "string", "nullable": true, "description": "Display name for the authenticated user, when available." }, "email": { "type": "string", "nullable": true, "description": "Email address for the authenticated user, when available." } }, "required": ["id", "name", "email"], "description": "Authenticated user associated with the provided API key." } }, "required": ["user"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "user": { "id": "user_01example", "name": "Ada Lovelace", "email": "ada@example.com" } }, "meta": { "requestId": "req_01example", "creditsCharged": 0, "version": "v1" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "429": { "description": "Rate limit exceeded for this free endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/balance": { "get": { "tags": ["Auth"], "summary": "Get account balance", "description": "Returns the authenticated user's current credit balance.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "balance": { "type": "integer", "minimum": 0, "description": "Current credit balance for the authenticated API user." } }, "required": ["balance"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "balance": 1234 }, "meta": { "requestId": "req_01example", "creditsCharged": 0, "version": "v1" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "429": { "description": "Rate limit exceeded for this free endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/profiles": { "get": { "tags": ["Facebook"], "summary": "Get Facebook profile", "description": "Looks up a Facebook public profile or page by full URL. Outcomes such as found, private, or not found are indicated in `data.lookupStatus`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Facebook public profile or page URL to look up." }, "required": true, "description": "Facebook public profile or page URL to look up.", "name": "url", "in": "query" }, { "schema": { "type": "boolean", "description": "Optional: include structured business hours in the response when available." }, "required": false, "description": "Optional: include structured business hours in the response when available.", "name": "includeBusinessHours", "in": "query" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found`, `private`, or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "private", "not_found"], "description": "Whether the profile was found, private, or not found." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["facebook"], "description": "Social platform for this profile." }, "profileType": { "type": "string", "enum": ["person", "business"], "description": "Whether the lookup resolved to a personal profile or business page." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name shown on the Facebook profile or page." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public Facebook profile or page URL." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available avatar image URL." }, "coverImageUrl": { "type": "string", "nullable": true, "description": "Best available cover image URL." }, "platformUserId": { "type": "string", "description": "Facebook profile or page id when available." }, "gender": { "type": "string", "nullable": true, "enum": ["female", "male", "unknown", null], "description": "Gender label when available for personal profiles." } }, "required": [ "platform", "profileType", "displayName", "profileUrl", "avatarUrl", "coverImageUrl" ], "description": "Profile details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "likes": { "type": "integer", "nullable": true, "minimum": 0, "description": "Page likes count when available." }, "followers": { "type": "integer", "nullable": true, "minimum": 0, "description": "Page follower count when available." }, "ratingCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Number of public ratings or reviews when available." } }, "required": ["likes", "followers", "ratingCount"], "description": "Profile metrics when available." }, "contact": { "type": "object", "nullable": true, "properties": { "address": { "type": "string", "nullable": true, "description": "Public business address when available." }, "email": { "type": "string", "nullable": true, "description": "Public contact email when available." }, "phone": { "type": "string", "nullable": true, "description": "Public phone number when available." }, "website": { "type": "string", "nullable": true, "description": "Primary public website URL when available." } }, "required": ["address", "email", "phone", "website"], "description": "Public contact information when available." }, "business": { "type": "object", "nullable": true, "properties": { "intro": { "type": "string", "nullable": true, "description": "Short public introduction shown on the page when available." }, "category": { "type": "string", "nullable": true, "description": "Primary category label when available." }, "services": { "type": "string", "nullable": true, "description": "Service summary when available." }, "priceRange": { "type": "string", "nullable": true, "description": "Displayed price range when available." }, "ratingText": { "type": "string", "nullable": true, "description": "Public rating summary text when available." }, "isActive": { "type": "boolean", "description": "Whether the page is marked as an active business page." }, "createdDateText": { "type": "string", "nullable": true, "description": "Human-readable page creation date when available." }, "adLibraryStatus": { "type": "string", "nullable": true, "description": "Advertising activity summary when available." }, "adLibraryPageId": { "type": "string", "nullable": true, "description": "Facebook page id shown in the ad library when available." }, "hours": { "type": "object", "properties": { "monday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "tuesday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "wednesday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "thursday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "friday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "saturday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." }, "sunday": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Opening time for the first interval when available." }, "close": { "type": "string", "nullable": true, "description": "Closing time for the last interval when available." }, "intervals": { "type": "array", "items": { "type": "object", "properties": { "open": { "type": "string", "nullable": true, "description": "Start time for one business-hours interval when available." }, "close": { "type": "string", "nullable": true, "description": "End time for one business-hours interval when available." } }, "required": ["open", "close"], "description": "A single opening-hours interval." }, "description": "Structured opening intervals for the day." }, "text": { "type": "string", "description": "Human-readable business-hours text for the day." } }, "required": [ "open", "close", "intervals", "text" ], "description": "Business hours for one weekday." } }, "description": "Structured business hours when requested and available." } }, "required": [ "intro", "category", "services", "priceRange", "ratingText" ], "description": "Business-page-specific details when available." } }, "required": [ "lookupStatus", "profile", "metrics", "contact", "business" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "facebook", "profileType": "person", "displayName": "Carly Cross", "profileUrl": "https://www.facebook.com/carly.cross.5", "avatarUrl": "https://example.com/avatar.jpg", "coverImageUrl": "https://example.com/cover.jpg", "platformUserId": "pfbid02sEc1nJvcFqcQrMPgnv4zaL8idwhenjVNNBRQe7HV2yDMXrJDW7b9YfBpMUKcVwffl", "gender": "female" }, "metrics": null, "contact": null, "business": null }, "meta": { "requestId": "req_01example_found", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "facebook", "profileType": "person", "displayName": "Carly Cross", "profileUrl": "https://www.facebook.com/carly.cross.5", "avatarUrl": "https://example.com/avatar.jpg", "coverImageUrl": "https://example.com/cover.jpg", "platformUserId": "pfbid02sEc1nJvcFqcQrMPgnv4zaL8idwhenjVNNBRQe7HV2yDMXrJDW7b9YfBpMUKcVwffl", "gender": "female" }, "metrics": null, "contact": null, "business": null }, "meta": { "requestId": "req_01example_found", "creditsCharged": 1, "version": "v1" } } }, "found_business": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "facebook", "profileType": "business", "displayName": "Mantraindian", "profileUrl": "https://www.facebook.com/mantraindianfolsom", "avatarUrl": "https://example.com/avatar.jpg", "coverImageUrl": "https://example.com/cover.jpg", "platformUserId": "100088017857524", "gender": "unknown" }, "metrics": { "likes": 4228, "followers": 4200, "ratingCount": null }, "contact": { "address": "1870 Prairie City Rd, Suite 500, Folsom, CA, United States, California", "email": "contact@mantraindian.com", "phone": "+1 916-999-1749", "website": "https://www.mantraindian.com/" }, "business": { "intro": "Indian Vegan & Vegetarian Restaurant", "category": "Restaurant", "services": "Delivery · Takeaway · Dine in…", "priceRange": "$$", "ratingText": "Not yet rated (1 review)", "isActive": false, "createdDateText": "November 25, 2022", "adLibraryStatus": "This Page is currently running ads.", "adLibraryPageId": "104359362513119", "hours": { "monday": { "open": "11:00", "close": "21:30", "intervals": [ { "open": "11:00", "close": "14:30" }, { "open": "16:30", "close": "21:30" } ], "text": "11:00 - 14:30, 16:30 - 21:30" } } } }, "meta": { "requestId": "req_01example_business", "creditsCharged": 1, "version": "v1" } } }, "private": { "value": { "data": { "lookupStatus": "private", "profile": null, "metrics": null, "contact": null, "business": null }, "meta": { "requestId": "req_01example_private", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "metrics": null, "contact": null, "business": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/profiles/posts": { "get": { "tags": ["Facebook"], "summary": "List Facebook profile posts", "description": "Lists public posts for a Facebook profile or page identified by `url` or `pageId`, with cursor-based pagination. Private profiles, missing pages, and profiles with no public posts can all surface as HTTP `200` with an empty `data.posts` page—this route does not expose `lookupStatus`. Call `GET /v1/facebook/profiles` first when you need explicit `found` / `private` / `not_found` before interpreting an empty list.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.posts` page with `hasMore: false` can represent no public posts, restricted visibility, or an unresolvable URL or id—there is no `lookupStatus` field on this route.", "disambiguation": "Call `GET /v1/facebook/profiles` first when you need `found` / `private` / `not_found` before interpreting an empty posts page." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Full public Facebook profile or page URL." }, "required": false, "description": "Full public Facebook profile or page URL.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Facebook page or profile id when you have it instead of a full URL." }, "required": false, "description": "Facebook page or profile id when you have it instead of a full URL.", "name": "pageId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`)." }, "required": false, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`).", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Facebook posts for the requested profile or page. Empty `data.posts` is ambiguous without a profile preflight—see the operation description.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Facebook post id." }, "text": { "type": "string", "nullable": true, "description": "Post caption or text when present." }, "url": { "type": "string", "minLength": 1, "description": "Public Facebook URL for this post." }, "publishTime": { "type": "integer", "description": "When the post was published (Unix epoch seconds) when available." }, "authorDisplayName": { "type": "string", "nullable": true, "description": "Display name for the post author when available." }, "authorShortName": { "type": "string", "nullable": true, "description": "Short display label for the author when Facebook provides one." }, "authorId": { "type": "string", "description": "Facebook id for the post author when available." }, "reactionCount": { "type": "integer", "minimum": 0, "description": "Reaction count when available." }, "commentCount": { "type": "integer", "minimum": 0, "description": "Comment count when available." }, "videoViewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video view count when available." }, "imageUrl": { "type": "string", "description": "Primary image URL when the post includes a single primary image." }, "imageUrls": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Gallery image URLs when the post includes multiple images." }, "videoSdUrl": { "type": "string", "description": "Standard-definition video URL when this post includes playable video." }, "videoHdUrl": { "type": "string", "description": "High-definition video URL when this post includes playable video." }, "videoThumbnailUrl": { "type": "string", "description": "Video thumbnail image URL when available." }, "topComments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Comment id." }, "text": { "type": "string", "nullable": true, "description": "Comment text when available." }, "publishTime": { "type": "integer", "description": "When the comment was published (Unix epoch seconds) when available." }, "authorDisplayName": { "type": "string", "nullable": true, "description": "Display name for the comment author when available." }, "authorId": { "type": "string", "description": "Facebook id for the comment author when available." }, "authorUrl": { "type": "string", "nullable": true, "description": "Public Facebook URL for the comment author when available." } }, "required": ["id", "text"], "description": "A top-level comment surfaced on a Facebook post." }, "description": "A small set of top comments when Facebook exposes them for the post." } }, "required": ["id", "text", "url"], "description": "A single Facebook post on a profile feed page." }, "description": "Facebook posts for the requested input. An empty array can mean no public posts were returned, the profile does not expose posts publicly, or the URL or id could not be resolved—there is no separate lookup status on this route." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when more posts are available." }, "hasMore": { "type": "boolean", "description": "Whether another page of posts is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination state for the current response." } }, "required": ["posts", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "posts": [ { "id": "10244109500012284", "text": "Example post text.", "url": "https://www.facebook.com/example/posts/pfbid0example", "publishTime": 1775718956, "authorDisplayName": "Example Author", "authorShortName": "Example", "authorId": "100063669491743", "reactionCount": 12, "commentCount": 3, "videoViewCount": null, "imageUrl": "https://example.com/image.jpg", "topComments": [ { "id": "Y29tbWVudDoxXzI=", "text": "Nice post!", "publishTime": 1775719000, "authorDisplayName": "Commenter", "authorId": "123456789", "authorUrl": null } ] } ], "page": { "nextCursor": "Cg8Ob3JnYW5pY19jdXJzb3IJAAABexample", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "first_page": { "value": { "data": { "posts": [ { "id": "10244109500012284", "text": "Example post text.", "url": "https://www.facebook.com/example/posts/pfbid0example", "publishTime": 1775718956, "authorDisplayName": "Example Author", "authorShortName": "Example", "authorId": "100063669491743", "reactionCount": 12, "commentCount": 3, "videoViewCount": null, "imageUrl": "https://example.com/image.jpg", "topComments": [ { "id": "Y29tbWVudDoxXzI=", "text": "Nice post!", "publishTime": 1775719000, "authorDisplayName": "Commenter", "authorId": "123456789", "authorUrl": null } ] } ], "page": { "nextCursor": "Cg8Ob3JnYW5pY19jdXJzb3IJAAABexample", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "posts": [ { "id": "10244073632835627", "text": "Second page example.", "url": "https://www.facebook.com/example/posts/pfbid0page2", "authorDisplayName": "Example Author", "reactionCount": 6, "commentCount": 1 } ], "page": { "nextCursor": "next-cursor-token", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "posts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid `url`, `pageId`, `cursor`, or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/profiles/reels": { "get": { "tags": ["Facebook"], "summary": "List Facebook profile reels", "description": "Lists public Facebook reels for a profile or page URL. Check `data.lookupStatus` for `found` vs `not_found`. Use `data.page.nextCursor` to request the next page when `data.page.hasMore` is true.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "outcomes": "Check `data.lookupStatus`: `found` means the profile or page resolved, while `not_found` means the URL could not be resolved for this reels lookup.", "pagination": "Use `data.page.nextCursor` only when `data.page.hasMore` is true." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public Facebook profile or page URL whose reels should be listed." }, "required": true, "description": "Public Facebook profile or page URL whose reels should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`)." }, "required": false, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`).", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Facebook reels for the requested profile or page. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the requested profile or page resolved for this request." }, "reels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable reel identifier from Facebook." }, "postId": { "type": "string", "nullable": true, "description": "Underlying Facebook post id when available." }, "videoId": { "type": "string", "nullable": true, "description": "Underlying Facebook video id when available." }, "url": { "type": "string", "minLength": 1, "description": "Public Facebook URL for this reel." }, "description": { "type": "string", "nullable": true, "description": "Caption or description text when available." }, "createdAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp for when the reel was created." }, "viewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count when available." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail image URL when available." }, "videoUrl": { "type": "string", "nullable": true, "description": "Direct video URL when available." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Play duration in milliseconds when available." }, "music": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "nullable": true, "description": "Music track title when available." } }, "required": ["title"], "description": "Music metadata when available." }, "author": { "type": "object", "nullable": true, "properties": { "platformUserId": { "type": "string", "nullable": true, "description": "Facebook id for the reel author when available." }, "name": { "type": "string", "nullable": true, "description": "Display name for the reel author when available." }, "isVerified": { "type": "boolean", "nullable": true, "description": "Whether Facebook marks the author as verified." }, "url": { "type": "string", "nullable": true, "description": "Public Facebook URL for the author when available." }, "imageUrl": { "type": "string", "nullable": true, "description": "Profile image URL for the author when available." } }, "required": [ "platformUserId", "name", "isVerified", "url", "imageUrl" ], "description": "Author metadata when available." } }, "required": [ "id", "postId", "videoId", "url", "description", "createdAt", "viewCount", "thumbnailUrl", "videoUrl", "durationMs", "music", "author" ], "description": "A single Facebook reel on a profile reels page." }, "description": "Reels returned for the requested profile or page. This array may be empty on the last page." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of reels can be requested." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "reels", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "reels": [ { "id": "reel_1", "postId": "456", "videoId": "123", "url": "https://www.facebook.com/reel/123", "description": "Example caption.", "createdAt": "2026-03-08T15:55:57.000Z", "viewCount": 8000, "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "durationMs": 31000, "music": { "title": null }, "author": { "platformUserId": "100063669491743", "name": "Example Author", "isVerified": false, "url": "https://www.facebook.com/example", "imageUrl": "https://example.com/author.jpg" } } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "reels": [ { "id": "reel_1", "postId": "456", "videoId": "123", "url": "https://www.facebook.com/reel/123", "description": "Example caption.", "createdAt": "2026-03-08T15:55:57.000Z", "viewCount": 8000, "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "durationMs": 31000, "music": { "title": null }, "author": { "platformUserId": "100063669491743", "name": "Example Author", "isVerified": false, "url": "https://www.facebook.com/example", "imageUrl": "https://example.com/author.jpg" } } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "last_page": { "value": { "data": { "lookupStatus": "found", "reels": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_last_page", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "reels": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_not_found", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid `url` or `cursor`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/profiles/photos": { "get": { "tags": ["Facebook"], "summary": "List Facebook profile photos", "description": "Lists public Facebook photos for a profile or page URL. Check `data.lookupStatus` for `found` vs `not_found`. Use `data.page.nextCursor` to request the next page when `data.page.hasMore` is true.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "outcomes": "Check `data.lookupStatus`: `found` means the profile or page resolved, while `not_found` means the URL could not be resolved for this photos lookup.", "pagination": "Use `data.page.nextCursor` only when `data.page.hasMore` is true." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public Facebook profile or page URL whose photos should be listed." }, "required": true, "description": "Public Facebook profile or page URL whose photos should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`)." }, "required": false, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`).", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Facebook photos for the requested profile or page. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the requested profile or page resolved for this request." }, "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable photo item identifier from Facebook." }, "photoId": { "type": "string", "minLength": 1, "description": "Facebook photo id when available." }, "url": { "type": "string", "minLength": 1, "description": "Public Facebook URL for this photo." }, "accessibilityCaption": { "type": "string", "nullable": true, "description": "Accessibility or alt-style caption text when Facebook provides one." }, "imageUrl": { "type": "string", "nullable": true, "description": "Primary image URL when available." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail image URL when available." }, "dimensions": { "type": "object", "nullable": true, "properties": { "width": { "type": "integer", "minimum": 0, "description": "Image width in pixels when available." }, "height": { "type": "integer", "minimum": 0, "description": "Image height in pixels when available." } }, "required": ["width", "height"], "description": "Image dimensions when available." } }, "required": [ "id", "photoId", "url", "accessibilityCaption", "imageUrl", "thumbnailUrl", "dimensions" ], "description": "A single Facebook photo on a profile photos page." }, "description": "Photos returned for the requested profile or page. This array may be empty on the last page." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of photos can be requested." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "photos", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "photos": [ { "id": "YXBwX2l0ZW06MTAwMDQ0NjM0NDUwMjA4OjIzMDUyNzI3MzI6NTo6MTQ5NDAyOTQ2ODc2MTUyMQ==", "photoId": "1494029468761521", "url": "https://www.facebook.com/photo.php?fbid=1494029468761521&set=pb.100044634450208.-2207520000&type=3", "accessibilityCaption": "May be an image of basketball and text.", "imageUrl": "https://example.com/image.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "dimensions": { "width": 1440, "height": 1800 } } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "photos": [ { "id": "YXBwX2l0ZW06MTAwMDQ0NjM0NDUwMjA4OjIzMDUyNzI3MzI6NTo6MTQ5NDAyOTQ2ODc2MTUyMQ==", "photoId": "1494029468761521", "url": "https://www.facebook.com/photo.php?fbid=1494029468761521&set=pb.100044634450208.-2207520000&type=3", "accessibilityCaption": "May be an image of basketball and text.", "imageUrl": "https://example.com/image.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "dimensions": { "width": 1440, "height": 1800 } } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "last_page": { "value": { "data": { "lookupStatus": "found", "photos": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_last_page", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "photos": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_not_found", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid `url` or `cursor`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/groups/posts": { "get": { "tags": ["Facebook"], "summary": "List Facebook group posts", "description": "Lists posts for a public Facebook group. Pass the full group URL and optional `sortBy` and `cursor` for pagination. Check `data.lookupStatus` for `found` vs `not_found`.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public Facebook group URL whose posts should be listed." }, "required": true, "description": "Public Facebook group URL whose posts should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "enum": [ "top", "recentActivity", "chronological", "chronologicalListings" ], "description": "Optional sort order for the returned posts." }, "required": false, "description": "Optional sort order for the returned posts.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`)." }, "required": false, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`).", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Group posts for the requested feed. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the group resolved for this request." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable identifier for the post." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this Facebook group post." }, "text": { "type": "string", "nullable": true, "description": "Text body of the post when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp for when the post was published, when available." }, "reactionCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Reaction count for the post when available." }, "commentCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count for the post when available." }, "author": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Platform identifier for the post author when available." }, "name": { "type": "string", "nullable": true, "description": "Display name for the post author when available." }, "url": { "type": "string", "nullable": true, "description": "Public profile URL for the post author when available." } }, "required": ["id", "name", "url"], "description": "Author summary for this post." }, "video": { "type": "object", "properties": { "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail image URL for embedded video when available." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video duration in milliseconds when available." }, "sdUrl": { "type": "string", "nullable": true, "description": "Standard-definition video URL when available." }, "hdUrl": { "type": "string", "nullable": true, "description": "High-definition video URL when available." } }, "required": [ "thumbnailUrl", "durationMs", "sdUrl", "hdUrl" ], "description": "Embedded video metadata when this post includes video." } }, "required": [ "id", "url", "text", "publishedAt", "reactionCount", "commentCount", "author", "video" ], "description": "A single post from a Facebook group feed." }, "description": "Posts returned for the requested group. This array may be empty when the group resolves but no posts are returned." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of posts can be requested." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "posts", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "posts": [ { "id": "1286289372828481", "url": "https://www.facebook.com/groups/742354120555345/permalink/1286289372828481/", "text": "Example post text.", "publishedAt": "2025-05-30T12:29:49.000Z", "reactionCount": 198, "commentCount": 100, "author": { "id": "61552766652796", "name": "Example Author", "url": "https://www.facebook.com/example.author" }, "video": { "thumbnailUrl": "https://example.com/thumb.jpg", "durationMs": null, "sdUrl": "https://example.com/video-sd.mp4", "hdUrl": "https://example.com/video-hd.mp4" } } ], "page": { "nextCursor": "opaque_next_page_cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "posts": [ { "id": "1286289372828481", "url": "https://www.facebook.com/groups/742354120555345/permalink/1286289372828481/", "text": "Example post text.", "publishedAt": "2025-05-30T12:29:49.000Z", "reactionCount": 198, "commentCount": 100, "author": { "id": "61552766652796", "name": "Example Author", "url": "https://www.facebook.com/example.author" }, "video": { "thumbnailUrl": "https://example.com/thumb.jpg", "durationMs": null, "sdUrl": "https://example.com/video-sd.mp4", "hdUrl": "https://example.com/video-hd.mp4" } } ], "page": { "nextCursor": "opaque_next_page_cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "lookupStatus": "found", "posts": [ { "id": "1280901910033894", "url": "https://www.facebook.com/groups/742354120555345/permalink/1280901910033894/", "text": "Another post.", "publishedAt": "2025-05-23T22:34:36.000Z", "reactionCount": 1671, "commentCount": 214, "author": { "id": "61552766652796", "name": "Example Author", "url": "https://www.facebook.com/example.author" }, "video": { "thumbnailUrl": "https://example.com/thumb.jpg", "durationMs": null, "sdUrl": "https://example.com/video-sd.mp4", "hdUrl": "https://example.com/video-hd.mp4" } } ], "page": { "nextCursor": "opaque_second_page_cursor", "hasMore": true } }, "meta": { "requestId": "req_01example_p2", "creditsCharged": 1, "version": "v1" } } }, "no_posts": { "value": { "data": { "lookupStatus": "found", "posts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "posts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid group URL, sort, cursor, or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/posts": { "get": { "tags": ["Facebook"], "summary": "Get Facebook post or reel", "description": "Returns public metadata for a single Facebook post or reel URL. Availability is indicated in `data.lookupStatus` as `found` or `not_found`. Optional `includeComments` and `includeTranscript` request extra fields when available.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public permalink to the Facebook post or reel." }, "required": true, "description": "Public permalink to the Facebook post or reel.", "name": "url", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, includes a sample of top-level comments when available." }, "required": false, "description": "When true, includes a sample of top-level comments when available.", "name": "includeComments", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, includes a plain-text transcript when available for the video." }, "required": false, "description": "When true, includes a plain-text transcript when available for the video.", "name": "includeTranscript", "in": "query" } ], "responses": { "200": { "description": "Post or reel metadata (found or not found in body).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the URL could be resolved to public content." }, "post": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["facebook"], "description": "Social platform for this content." }, "postId": { "type": "string", "minLength": 1, "description": "Platform post id when available." }, "url": { "type": "string", "minLength": 1, "description": "Canonical or resolved public URL for this post or reel." }, "description": { "type": "string", "nullable": true, "description": "Caption or body text when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp in ISO 8601 when available." }, "feedbackId": { "type": "string", "nullable": true, "description": "Opaque feedback identifier when exposed by the platform; may be used for related lookups." } }, "required": [ "platform", "postId", "url", "description", "publishedAt", "feedbackId" ], "description": "Post details when found." }, "author": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name of the author." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Public profile URL for the author when available." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar image URL when available." }, "platformUserId": { "type": "string", "description": "Platform-specific author id when available." }, "verified": { "type": "boolean", "description": "Whether the author is marked as verified." } }, "required": [ "name", "profileUrl", "avatarUrl", "verified" ], "description": "Author when found." }, "metrics": { "type": "object", "nullable": true, "properties": { "likes": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count when available." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count when available." }, "shares": { "type": "integer", "nullable": true, "minimum": 0, "description": "Share count when available." }, "views": { "type": "integer", "nullable": true, "minimum": 0, "description": "View or play count when available." } }, "required": ["likes", "comments", "shares", "views"], "description": "Engagement metrics for the post or reel." }, "media": { "type": "object", "nullable": true, "properties": { "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail image URL when available." }, "imageUrl": { "type": "string", "nullable": true, "description": "Primary image URL when the post is image-based." }, "videoUrl": { "type": "string", "nullable": true, "description": "Standard-definition video URL when available." }, "videoHdUrl": { "type": "string", "nullable": true, "description": "High-definition video URL when available." }, "durationSec": { "type": "number", "nullable": true, "minimum": 0, "description": "Video duration in seconds when available." }, "width": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video width in pixels when available." }, "height": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video height in pixels when available." }, "captionsUrl": { "type": "string", "nullable": true, "description": "Caption or subtitle asset URL when available." } }, "required": [ "thumbnailUrl", "imageUrl", "videoUrl", "videoHdUrl", "durationSec", "width", "height", "captionsUrl" ], "description": "Primary media for the post or reel." }, "music": { "type": "object", "nullable": true, "properties": { "trackTitle": { "type": "string", "nullable": true, "description": "Track title when the post uses attached audio." }, "albumArtUrl": { "type": "string", "nullable": true, "description": "Album art image URL when available." }, "musicId": { "type": "string", "description": "Audio track id when available." }, "type": { "type": "string", "description": "Audio source type label when available." } }, "required": ["trackTitle", "albumArtUrl"], "description": "Attached audio metadata when available." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1, "description": "Stable id for the comment when available." }, "text": { "type": "string", "nullable": true, "description": "Comment body text." }, "createdAt": { "type": "string", "nullable": true, "description": "Creation timestamp in ISO 8601 when available." }, "replyCount": { "type": "integer", "minimum": 0, "description": "Number of direct replies when available." }, "reactionCount": { "type": "integer", "minimum": 0, "description": "Total reactions when available." }, "authorName": { "type": "string", "minLength": 1, "description": "Display name of the commenter." } }, "required": [ "commentId", "text", "createdAt", "replyCount", "reactionCount", "authorName" ], "description": "A single top-level comment sample." }, "description": "Sample of top-level comments when requested and available." }, "transcript": { "type": "string", "nullable": true, "description": "Plain-text transcript when requested and available." } }, "required": [ "lookupStatus", "post", "author", "metrics", "media", "music", "comments", "transcript" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "post": { "platform": "facebook", "postId": "10162952105911701", "url": "https://www.facebook.com/reel/823172974137208", "description": "Example caption.", "publishedAt": "2026-04-07T19:02:33.000Z", "feedbackId": "ZmVlZGJhY2s6MTAxNjI5NTIxMDU5MTE3MDE=" }, "author": { "name": "Example Author", "profileUrl": "https://www.facebook.com/example.author", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "pfbid02example", "verified": false }, "metrics": { "likes": 110, "comments": 10, "shares": 0, "views": null }, "media": { "thumbnailUrl": "https://example.com/thumb.jpg", "imageUrl": null, "videoUrl": "https://example.com/video-sd.mp4", "videoHdUrl": "https://example.com/video-hd.mp4", "durationSec": 37.64, "width": 1080, "height": 1920, "captionsUrl": null }, "music": { "trackTitle": "Example Artist · Example track", "albumArtUrl": "https://example.com/album.jpg", "musicId": "1736166400619393", "type": "LIBRARY_MUSIC" }, "comments": [], "transcript": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "post": { "platform": "facebook", "postId": "10162952105911701", "url": "https://www.facebook.com/reel/823172974137208", "description": "Example caption.", "publishedAt": "2026-04-07T19:02:33.000Z", "feedbackId": "ZmVlZGJhY2s6MTAxNjI5NTIxMDU5MTE3MDE=" }, "author": { "name": "Example Author", "profileUrl": "https://www.facebook.com/example.author", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "pfbid02example", "verified": false }, "metrics": { "likes": 110, "comments": 10, "shares": 0, "views": null }, "media": { "thumbnailUrl": "https://example.com/thumb.jpg", "imageUrl": null, "videoUrl": "https://example.com/video-sd.mp4", "videoHdUrl": "https://example.com/video-hd.mp4", "durationSec": 37.64, "width": 1080, "height": 1920, "captionsUrl": null }, "music": { "trackTitle": "Example Artist · Example track", "albumArtUrl": "https://example.com/album.jpg", "musicId": "1736166400619393", "type": "LIBRARY_MUSIC" }, "comments": [], "transcript": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "with_comments": { "value": { "data": { "lookupStatus": "found", "post": { "platform": "facebook", "postId": "10162952105911701", "url": "https://www.facebook.com/reel/823172974137208", "description": "Example caption.", "publishedAt": "2026-04-07T19:02:33.000Z", "feedbackId": "ZmVlZGJhY2s6MTAxNjI5NTIxMDU5MTE3MDE=" }, "author": { "name": "Example Author", "profileUrl": "https://www.facebook.com/example.author", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "pfbid02example", "verified": false }, "metrics": { "likes": 110, "comments": 10, "shares": 0, "views": null }, "media": { "thumbnailUrl": "https://example.com/thumb.jpg", "imageUrl": null, "videoUrl": "https://example.com/video-sd.mp4", "videoHdUrl": "https://example.com/video-hd.mp4", "durationSec": 37.64, "width": 1080, "height": 1920, "captionsUrl": null }, "music": { "trackTitle": "Example Artist · Example track", "albumArtUrl": "https://example.com/album.jpg", "musicId": "1736166400619393", "type": "LIBRARY_MUSIC" }, "comments": [ { "commentId": "Y29tbWVudDox", "text": "Great post.", "createdAt": "2026-04-07T19:08:56.000Z", "replyCount": 0, "reactionCount": 2, "authorName": "Example User" } ], "transcript": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "post": null, "author": null, "metrics": null, "media": null, "music": null, "comments": [], "transcript": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/posts/comments": { "get": { "tags": ["Facebook"], "summary": "List Facebook post or reel comments", "description": "Lists top-level comments for a public Facebook post or reel URL with optional cursor-based pagination.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the Facebook post or reel whose comments should be listed." }, "required": false, "description": "Link to the Facebook post or reel whose comments should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor from a previous response to fetch the next page." }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional Facebook feedback identifier for the target post; when available it can improve lookup performance." }, "required": false, "description": "Optional Facebook feedback identifier for the target post; when available it can improve lookup performance.", "name": "feedbackId", "in": "query" } ], "responses": { "200": { "description": "Comment listing result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the post or reel was resolved for this request." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable identifier for the comment." }, "text": { "type": "string", "description": "Comment text." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp when the comment was created." }, "replyCount": { "type": "integer", "minimum": 0, "description": "Direct reply count for the comment thread." }, "reactionCount": { "type": "integer", "minimum": 0, "description": "Total reaction count on the comment." }, "author": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name of the commenter." }, "platformUserId": { "type": "string", "description": "Platform-specific commenter id when available." }, "shortName": { "type": "string", "nullable": true, "description": "Short display name for the commenter when available." } }, "required": ["name", "shortName"], "description": "Comment author." } }, "required": [ "id", "text", "createdAt", "replyCount", "reactionCount", "author" ], "description": "A single top-level comment on a Facebook post or reel." }, "description": "Top-level comments for the resolved post or reel." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when more pages exist." }, "hasMore": { "type": "boolean", "description": "Whether another page of comments is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for this response." } }, "required": ["lookupStatus", "comments", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "comments": [ { "id": "Y29tbWVudDox", "text": "Great post.", "createdAt": "2026-04-20T05:10:39.000Z", "replyCount": 0, "reactionCount": 10, "author": { "name": "Example User", "platformUserId": "100012345678901", "shortName": "Example" } } ], "page": { "nextCursor": "opaque-next-page-cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "comments": [ { "id": "Y29tbWVudDox", "text": "Great post.", "createdAt": "2026-04-20T05:10:39.000Z", "replyCount": 0, "reactionCount": 10, "author": { "name": "Example User", "platformUserId": "100012345678901", "shortName": "Example" } } ], "page": { "nextCursor": "opaque-next-page-cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "no_comments": { "value": { "data": { "lookupStatus": "found", "comments": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nc", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "comments": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/facebook/posts/transcript": { "get": { "tags": ["Facebook"], "summary": "Get Facebook post transcript", "description": "Returns a plain-text transcript for a public Facebook post or reel when available. Pass `url` as a full permalink. Short videos are more likely to return speech; longer videos may not include a transcript. Inspect `data.lookupStatus` for found, not found, or lookup_failed.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the Facebook post or reel whose transcript should be returned." }, "required": true, "description": "Link to the Facebook post or reel whose transcript should be returned.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Transcript lookup result. Inspect `data.lookupStatus` for found, not found, or lookup_failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found", "lookup_failed"], "description": "Outcome of the transcript lookup: transcript resolved, not found, or lookup could not be completed." }, "post": { "type": "object", "nullable": true, "properties": { "url": { "type": "string", "minLength": 1, "description": "Public URL of the Facebook post or reel that was requested (same as the lookup input)." } }, "required": ["url"], "description": "Post or reel identity when the lookup resolved; otherwise null." }, "transcript": { "type": "string", "nullable": true, "description": "Plain transcript text when available. May be null when speech is not detected, the video exceeds supported length, or transcription is otherwise unavailable." } }, "required": ["lookupStatus", "post", "transcript"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "post": { "url": "https://www.facebook.com/reel/1535656380759655" }, "transcript": "Example line one.\nExample line two." }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "post": { "url": "https://www.facebook.com/reel/1535656380759655" }, "transcript": "Example line one.\nExample line two." }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "post": null, "transcript": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } }, "no_transcript": { "value": { "data": { "lookupStatus": "found", "post": { "url": "https://www.facebook.com/reel/1535656380759655" }, "transcript": null }, "meta": { "requestId": "req_01example_null", "creditsCharged": 1, "version": "v1" } } }, "lookup_failed": { "value": { "data": { "lookupStatus": "lookup_failed", "post": null, "transcript": null }, "meta": { "requestId": "req_01example_lf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query, bad request, or the video exceeds supported transcription length.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": ["bad_request"] }, { "type": "string", "enum": ["video_too_long_for_transcription"] } ], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } }, "examples": { "bad_request": { "value": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } }, "video_too_long_for_transcription": { "value": { "error": { "code": "video_too_long_for_transcription", "message": "Example message.", "requestId": "req_01example" } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/profiles/{handle}": { "get": { "tags": ["TikTok"], "summary": "Get TikTok profile", "description": "Looks up a TikTok profile by handle.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "TikTok handle to look up, with or without a leading @." }, "required": true, "description": "TikTok handle to look up, with or without a leading @.", "name": "handle", "in": "path" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found`, `private`, or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "private", "not_found"], "description": "Whether the profile was found, private, or not found." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["tiktok"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "TikTok username without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name shown on the TikTok profile." }, "bio": { "type": "string", "nullable": true, "description": "Profile biography text." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available avatar image URL for the profile." }, "verified": { "type": "boolean", "description": "Whether TikTok marks the profile as verified." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public TikTok profile URL." }, "privateAccount": { "type": "boolean", "description": "Whether the TikTok account is private." }, "platformUserId": { "type": "string", "description": "TikTok numeric user id as a string (stable within TikTok)." }, "secUid": { "type": "string", "description": "TikTok opaque stable user identifier (for advanced integrations)." }, "accountCreatedAt": { "type": "integer", "minimum": 0, "description": "Account creation time as Unix epoch seconds from TikTok, when provided." }, "avatarUrls": { "type": "object", "properties": { "large": { "type": "string", "description": "Large avatar URL (typically 1080px class)." }, "medium": { "type": "string", "description": "Medium avatar URL (typically 720px class)." }, "thumb": { "type": "string", "description": "Thumbnail avatar URL (typically 100px class)." } }, "description": "Avatar URLs at multiple resolutions when available." }, "bioLink": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Destination URL for the profile link." }, "riskLevel": { "type": "integer", "description": "TikTok-assigned link risk indicator (vendor-defined)." } }, "required": ["url", "riskLevel"], "description": "Profile link-in-bio when TikTok provides it." }, "language": { "type": "string", "description": "Profile language code reported by TikTok (e.g. en)." }, "isCommerceUser": { "type": "boolean", "description": "Whether TikTok marks the account as a commerce/creator shop user." }, "isSeller": { "type": "boolean", "description": "Whether TikTok marks the account as a TikTok Shop seller." }, "openFavorite": { "type": "boolean", "description": "Whether the user’s liked-videos list is public." }, "isAdVirtual": { "type": "boolean", "description": "Whether TikTok flags the profile as an AD virtual account." }, "isEmbedBanned": { "type": "boolean", "description": "Whether embeds are disallowed for this profile." }, "canExpandPlaylist": { "type": "boolean", "description": "Whether playlist expansion is allowed for this profile." }, "profileEmbedPermission": { "type": "integer", "description": "TikTok profile embed permission code (vendor-defined)." }, "followingVisibility": { "type": "integer", "description": "Who can see accounts this user follows (TikTok vendor-defined code)." }, "roomId": { "type": "string", "description": "Live room id when TikTok provides a non-empty value." }, "contentSettings": { "type": "object", "properties": { "comment": { "type": "integer", "description": "TikTok comment-setting code (vendor-defined)." }, "duet": { "type": "integer", "description": "TikTok duet-setting code (vendor-defined)." }, "stitch": { "type": "integer", "description": "TikTok stitch-setting code (vendor-defined)." }, "download": { "type": "integer", "description": "TikTok download-setting code (vendor-defined)." } }, "required": [ "comment", "duet", "stitch", "download" ], "description": "Comment, duet, stitch, and download settings from TikTok." }, "profileTabs": { "type": "object", "properties": { "showMusicTab": { "type": "boolean", "description": "Whether the Music tab is shown on the profile." }, "showQuestionTab": { "type": "boolean", "description": "Whether the Q&A tab is shown on the profile." }, "showPlayListTab": { "type": "boolean", "description": "Whether the playlist tab is shown on the profile." } }, "required": [ "showMusicTab", "showQuestionTab", "showPlayListTab" ], "description": "Which profile tabs TikTok exposes." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "verified", "profileUrl" ], "description": "Profile details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Total follower count reported by TikTok." }, "following": { "type": "integer", "minimum": 0, "description": "Total following count reported by TikTok." }, "likes": { "type": "integer", "minimum": 0, "description": "Total profile likes reported by TikTok." }, "posts": { "type": "integer", "minimum": 0, "description": "Total public posts or videos reported by TikTok." }, "friends": { "type": "integer", "minimum": 0, "description": "Mutual friend count when TikTok reports it." }, "diggs": { "type": "integer", "minimum": 0, "description": "Profile digg count when TikTok reports it (often zero)." } }, "required": [ "followers", "following", "likes", "posts" ], "description": "Profile metrics when available." } }, "required": ["lookupStatus", "profile", "metrics"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "tiktok", "handle": "charlidamelio", "displayName": "charli", "bio": "hey", "avatarUrl": "https://example.com/avatar-large.jpg", "verified": true, "profileUrl": "https://www.tiktok.com/@charlidamelio", "privateAccount": false, "platformUserId": "5831967", "secUid": "MS4wLjABAAAA-VASjiXTh7wDDyXvjk10VFhMWUAoxr8bgfO1kAL1-9s", "accountCreatedAt": 1447505838, "avatarUrls": { "large": "https://example.com/avatar-large.jpg", "medium": "https://example.com/avatar-medium.jpg", "thumb": "https://example.com/avatar-thumb.jpg" }, "bioLink": { "url": "https://youtube.com/@charlidamelio", "riskLevel": 0 }, "language": "en", "isCommerceUser": false, "isSeller": false, "openFavorite": false, "isAdVirtual": false, "isEmbedBanned": false, "canExpandPlaylist": true, "profileEmbedPermission": 1, "followingVisibility": 2, "contentSettings": { "comment": 0, "duet": 0, "stitch": 0, "download": 0 }, "profileTabs": { "showMusicTab": false, "showQuestionTab": true, "showPlayListTab": false } }, "metrics": { "followers": 150000000, "following": 123, "likes": 12345678901, "posts": 456, "friends": 1194, "diggs": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "tiktok", "handle": "charlidamelio", "displayName": "charli", "bio": "hey", "avatarUrl": "https://example.com/avatar-large.jpg", "verified": true, "profileUrl": "https://www.tiktok.com/@charlidamelio", "privateAccount": false, "platformUserId": "5831967", "secUid": "MS4wLjABAAAA-VASjiXTh7wDDyXvjk10VFhMWUAoxr8bgfO1kAL1-9s", "accountCreatedAt": 1447505838, "avatarUrls": { "large": "https://example.com/avatar-large.jpg", "medium": "https://example.com/avatar-medium.jpg", "thumb": "https://example.com/avatar-thumb.jpg" }, "bioLink": { "url": "https://youtube.com/@charlidamelio", "riskLevel": 0 }, "language": "en", "isCommerceUser": false, "isSeller": false, "openFavorite": false, "isAdVirtual": false, "isEmbedBanned": false, "canExpandPlaylist": true, "profileEmbedPermission": 1, "followingVisibility": 2, "contentSettings": { "comment": 0, "duet": 0, "stitch": 0, "download": 0 }, "profileTabs": { "showMusicTab": false, "showQuestionTab": true, "showPlayListTab": false } }, "metrics": { "followers": 150000000, "following": 123, "likes": 12345678901, "posts": 456, "friends": 1194, "diggs": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "private": { "value": { "data": { "lookupStatus": "private", "profile": { "platform": "tiktok", "handle": "redfanta_", "displayName": "Example", "bio": null, "avatarUrl": "https://example.com/avatar.jpg", "verified": false, "profileUrl": "https://www.tiktok.com/@redfanta_", "privateAccount": true }, "metrics": { "followers": 24, "following": 1046, "likes": 751, "posts": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "metrics": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/profiles/{handle}/live": { "get": { "tags": ["TikTok"], "summary": "Get TikTok live stream", "description": "Looks up a TikTok handle and returns live stream details when broadcasting, with profile fields for lookup context.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "TikTok handle to look up, with or without a leading @." }, "required": true, "description": "TikTok handle to look up, with or without a leading @.", "name": "handle", "in": "path" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found` or `not_found`; when found, `data.liveStatus` is `live` or `offline`, with profile context in `data.profile` and live stream payload in `data.live` when broadcasting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether a TikTok profile identity could be resolved for the handle." }, "liveStatus": { "type": "string", "nullable": true, "enum": ["live", "offline", null], "description": "When `lookupStatus` is `found`, whether the profile is `live` or `offline`. Null when the profile could not be resolved." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["tiktok"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "TikTok username without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name shown on the TikTok profile." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available avatar image URL for the profile." }, "verified": { "type": "boolean", "description": "Whether TikTok marks the profile as verified." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public TikTok profile URL." }, "platformUserId": { "type": "string", "description": "TikTok numeric user id as a string (stable within TikTok)." }, "secUid": { "type": "string", "description": "TikTok opaque stable user identifier (for advanced integrations)." }, "followerCount": { "type": "integer", "minimum": 0, "description": "Follower count reported by TikTok when available." }, "followingCount": { "type": "integer", "minimum": 0, "description": "Following count reported by TikTok when available." }, "bio": { "type": "string", "nullable": true, "description": "Profile biography text when TikTok provides it." } }, "required": [ "platform", "handle", "displayName", "avatarUrl", "verified", "profileUrl" ], "description": "Profile identity when the lookup resolved." }, "live": { "type": "object", "nullable": true, "properties": { "roomId": { "type": "string", "minLength": 1, "description": "TikTok live room identifier for the current broadcast." }, "title": { "type": "string", "nullable": true, "description": "Live stream title when TikTok provides one." }, "coverUrl": { "type": "string", "nullable": true, "description": "Cover image URL for the live stream when available." }, "startedAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp when the live stream started, when TikTok provides a valid start time." }, "viewerCount": { "type": "integer", "minimum": 0, "description": "Approximate concurrent viewers reported by TikTok." }, "enterCount": { "type": "integer", "minimum": 0, "description": "Cumulative enters reported by TikTok for this live room." }, "streamId": { "type": "string", "description": "TikTok stream identifier when TikTok provides one." }, "streams": { "type": "array", "items": { "type": "object", "properties": { "codecFamily": { "type": "string", "enum": ["h264", "h265"], "description": "Video codec family for this variant." }, "source": { "type": "string", "enum": ["primary", "hevc"], "description": "Which upstream stream bundle this variant came from (standard vs alternate encoding)." }, "qualityKey": { "type": "string", "minLength": 1, "description": "Stable quality key for this variant (for example origin, hd, sd)." }, "qualityLabel": { "type": "string", "description": "Human-readable quality label when TikTok provides one." }, "flvUrl": { "type": "string", "description": "FLV playback URL when TikTok provides one." }, "hlsUrl": { "type": "string", "description": "HLS playback URL when TikTok provides one." }, "cmafUrl": { "type": "string", "description": "CMAF playback URL when TikTok provides one." }, "resolution": { "type": "string", "description": "Video resolution string when TikTok reports it." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Target bitrate in bits per second when TikTok reports it." } }, "required": [ "codecFamily", "source", "qualityKey" ], "description": "A single live stream playback variant." }, "description": "Flattened playback variants for the live stream." } }, "required": [ "roomId", "title", "coverUrl", "startedAt", "viewerCount", "enterCount", "streams" ], "description": "Live broadcast details when `liveStatus` is `live`. Null when not live or when the profile could not be resolved." } }, "required": [ "lookupStatus", "liveStatus", "profile", "live" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "liveStatus": "live", "profile": { "platform": "tiktok", "handle": "aommsinn_28", "displayName": "ธนาคารสีชมพู💕", "avatarUrl": "https://example.com/avatar.jpg", "verified": false, "profileUrl": "https://www.tiktok.com/@aommsinn_28", "platformUserId": "6824385553216996353", "secUid": "MS4wLjABAAAAexample", "followerCount": 1100, "followingCount": 612, "bio": "IG:aomsinnn_28\nรับรีวิวสินค้า🧺" }, "live": { "roomId": "7630101503277746960", "title": "เหงาาคับบพี่", "coverUrl": "https://example.com/cover.jpg", "startedAt": "2026-04-18T14:30:53.000Z", "viewerCount": 4, "enterCount": 820, "streamId": "1848602593495089198", "streams": [ { "codecFamily": "h264", "source": "primary", "qualityKey": "origin", "qualityLabel": "Original", "flvUrl": "https://example.com/stream-origin.flv" } ] } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "live": { "value": { "data": { "lookupStatus": "found", "liveStatus": "live", "profile": { "platform": "tiktok", "handle": "aommsinn_28", "displayName": "ธนาคารสีชมพู💕", "avatarUrl": "https://example.com/avatar.jpg", "verified": false, "profileUrl": "https://www.tiktok.com/@aommsinn_28", "platformUserId": "6824385553216996353", "secUid": "MS4wLjABAAAAexample", "followerCount": 1100, "followingCount": 612, "bio": "IG:aomsinnn_28\nรับรีวิวสินค้า🧺" }, "live": { "roomId": "7630101503277746960", "title": "เหงาาคับบพี่", "coverUrl": "https://example.com/cover.jpg", "startedAt": "2026-04-18T14:30:53.000Z", "viewerCount": 4, "enterCount": 820, "streamId": "1848602593495089198", "streams": [ { "codecFamily": "h264", "source": "primary", "qualityKey": "origin", "qualityLabel": "Original", "flvUrl": "https://example.com/stream-origin.flv" } ] } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "offline": { "value": { "data": { "lookupStatus": "found", "liveStatus": "offline", "profile": { "platform": "tiktok", "handle": "jade_pk6", "displayName": "Jade-pk", "avatarUrl": "https://example.com/avatar.jpg", "verified": false, "profileUrl": "https://www.tiktok.com/@jade_pk6", "platformUserId": "75123320319", "secUid": "MS4wLjABAAAAexample", "followerCount": 1657, "followingCount": 217, "bio": "หยกรีวิวทู้กกกอย่างงง🥰" }, "live": null }, "meta": { "requestId": "req_01example_offline", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "liveStatus": null, "profile": null, "live": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/profiles/{handle}/videos": { "get": { "tags": ["TikTok"], "summary": "List TikTok profile videos", "description": "Lists videos for a TikTok profile with cursor-based pagination. Optional query `sortBy` is `latest` or `popular`; when omitted, a default ordering applies—pass `sortBy` explicitly if you need predictable ordering. This route does not expose `lookupStatus`; an empty `data.videos` array can occur for several reasons—call `GET /v1/tiktok/profiles/{handle}` first when you need explicit `found` / `private` / `not_found` before interpreting an empty list.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.videos` array can mean no videos in the selected sort window, a private profile, or other cases—there is no `lookupStatus` field on this route.", "disambiguation": "Call `GET /v1/tiktok/profiles/{handle}` when you need explicit `lookupStatus` including `private` or `not_found` before interpreting an empty video list." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "TikTok handle whose videos should be listed." }, "required": true, "description": "TikTok handle whose videos should be listed.", "name": "handle", "in": "path" }, { "schema": { "type": "string", "enum": ["latest", "popular"], "description": "Optional sort order for the returned TikTok videos." }, "required": false, "description": "Optional sort order for the returned TikTok videos.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Pagination cursor returned by a previous response." }, "required": false, "description": "Pagination cursor returned by a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional TikTok user id to speed up the request." }, "required": false, "description": "Optional TikTok user id to speed up the request.", "name": "userId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional region (country code) for the request." }, "required": false, "description": "Optional region (country code) for the request.", "name": "region", "in": "query" }, { "schema": { "type": "boolean", "description": "Optional flag for a smaller response with fewer fields." }, "required": false, "description": "Optional flag for a smaller response with fewer fields.", "name": "trim", "in": "query" } ], "responses": { "200": { "description": "TikTok videos for the requested profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "TikTok video identifier." }, "caption": { "type": "string", "nullable": true, "description": "Caption text shown for the TikTok video." }, "createdAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp when the video was created, when available." }, "url": { "type": "string", "nullable": true, "description": "Canonical public TikTok URL for the video." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Best available thumbnail or cover image URL for the video." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video duration in milliseconds, when available." }, "pinned": { "type": "boolean", "description": "Whether the video is pinned on the profile." }, "isAd": { "type": "boolean", "description": "Whether TikTok marks the video as an ad." }, "stats": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "View count reported by TikTok for the video." }, "likes": { "type": "integer", "minimum": 0, "description": "Like count reported by TikTok for the video." }, "comments": { "type": "integer", "minimum": 0, "description": "Comment count reported by TikTok for the video." }, "shares": { "type": "integer", "minimum": 0, "description": "Share count reported by TikTok for the video." }, "saves": { "type": "integer", "minimum": 0, "description": "Save or collection count reported by TikTok for the video." } }, "required": [ "views", "likes", "comments", "shares", "saves" ], "description": "Engagement metrics for the video." }, "media": { "type": "object", "properties": { "downloadUrl": { "type": "string", "nullable": true, "description": "Best available downloadable video URL, usually with watermark." }, "downloadWithoutWatermarkUrl": { "type": "string", "nullable": true, "description": "Best available downloadable video URL without watermark." } }, "required": [ "downloadUrl", "downloadWithoutWatermarkUrl" ], "description": "Download-related media URLs for the video." }, "details": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "description": "Additional TikTok-native fields for this video (for example author, music, challenges, and full `video` and `statistics` objects). Keys that only duplicate the top-level fields are omitted." } }, "required": [ "id", "caption", "createdAt", "url", "thumbnailUrl", "durationMs", "pinned", "isAd", "stats", "media" ], "description": "TikTok video in the profile feed." }, "description": "TikTok videos for the requested profile page. An empty array can mean no videos in the selected sort window, a private profile, or other cases—this route has no `lookupStatus`; use the profile endpoint when you need explicit outcomes." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when more videos are available." }, "hasMore": { "type": "boolean", "description": "Whether another page of videos is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination state for the current response." } }, "required": ["videos", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "videos": [ { "id": "7470969622276164906", "caption": "Uncle Jerry and his family may be the nicest people in the world", "createdAt": "2025-09-03T18:37:38.000Z", "url": "https://www.tiktok.com/@stoolpresidente/video/7470969622276164906", "thumbnailUrl": "https://example.com/video-cover.jpg", "durationMs": 89131, "pinned": false, "isAd": false, "stats": { "views": 141567, "likes": 18651, "comments": 152, "shares": 237, "saves": 274 }, "media": { "downloadUrl": "https://example.com/video-watermarked.mp4", "downloadWithoutWatermarkUrl": "https://example.com/video-no-watermark.mp4" }, "details": { "author": { "unique_id": "stoolpresidente", "nickname": "Dave Portnoy" }, "music": { "title": "original sound" } } } ], "page": { "nextCursor": "1738435195000", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "first_page": { "value": { "data": { "videos": [ { "id": "7470969622276164906", "caption": "Uncle Jerry and his family may be the nicest people in the world", "createdAt": "2025-09-03T18:37:38.000Z", "url": "https://www.tiktok.com/@stoolpresidente/video/7470969622276164906", "thumbnailUrl": "https://example.com/video-cover.jpg", "durationMs": 89131, "pinned": false, "isAd": false, "stats": { "views": 141567, "likes": 18651, "comments": 152, "shares": 237, "saves": 274 }, "media": { "downloadUrl": "https://example.com/video-watermarked.mp4", "downloadWithoutWatermarkUrl": "https://example.com/video-no-watermark.mp4" }, "details": { "author": { "unique_id": "stoolpresidente", "nickname": "Dave Portnoy" }, "music": { "title": "original sound" } } } ], "page": { "nextCursor": "1738435195000", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "videos": [ { "id": "7470123456789012345", "caption": "Second page example video", "createdAt": "2025-09-01T12:00:00.000Z", "url": "https://www.tiktok.com/@stoolpresidente/video/7470123456789012345", "thumbnailUrl": "https://example.com/video-cover-page-2.jpg", "durationMs": 30250, "pinned": false, "isAd": false, "stats": { "views": 9021, "likes": 731, "comments": 48, "shares": 12, "saves": 19 }, "media": { "downloadUrl": "https://example.com/video-page-2-watermarked.mp4", "downloadWithoutWatermarkUrl": "https://example.com/video-page-2-no-watermark.mp4" } } ], "page": { "nextCursor": "1737000000000", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "videos": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/profiles/{handle}/showcase-products": { "get": { "tags": ["TikTok"], "summary": "List TikTok profile showcase products", "description": "Lists TikTok Shop products featured on a creator profile showcase with cursor-based pagination. This route does not expose `lookupStatus`; an empty `data.products` array can occur when there are no showcased products, the profile is private, or other cases—call `GET /v1/tiktok/profiles/{handle}` first when you need explicit account status.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.products` array can mean no showcased products, a private profile, or other cases—there is no `lookupStatus` field on this route.", "disambiguation": "Call `GET /v1/tiktok/profiles/{handle}` when you need explicit profile lookup status before interpreting an empty showcase list." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "TikTok handle whose profile showcase products should be listed." }, "required": true, "description": "TikTok handle whose profile showcase products should be listed.", "name": "handle", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Pagination cursor returned by a previous response." }, "required": false, "description": "Pagination cursor returned by a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional region (country code) for the request." }, "required": false, "description": "Optional region (country code) for the request.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Showcase products for the requested TikTok profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Product identifier." }, "title": { "type": "string", "nullable": true, "description": "Product title shown on TikTok Shop." }, "url": { "type": "string", "nullable": true, "description": "Canonical TikTok Shop URL for the product." }, "image": { "type": "object", "nullable": true, "properties": { "url": { "type": "string", "nullable": true, "description": "Primary image URL for the product." }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Image URLs for the product in preference order." }, "width": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image width in pixels when available." }, "height": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image height in pixels when available." } }, "required": ["url", "urls", "width", "height"], "description": "Primary image metadata." }, "price": { "type": "object", "nullable": true, "properties": { "currencyCode": { "type": "string", "nullable": true, "description": "Currency code for displayed prices." }, "currencySymbol": { "type": "string", "nullable": true, "description": "Currency symbol for displayed prices." }, "salePrice": { "type": "string", "nullable": true, "description": "Current sale price as a decimal string." }, "originalPrice": { "type": "string", "nullable": true, "description": "Original price before discounts as a decimal string." }, "discountPercent": { "type": "string", "nullable": true, "description": "Discount amount as shown by TikTok (often a percentage string)." } }, "required": [ "currencyCode", "currencySymbol", "salePrice", "originalPrice", "discountPercent" ], "description": "Price details when TikTok provides them." }, "rating": { "type": "object", "nullable": true, "properties": { "score": { "type": "number", "nullable": true, "description": "Average rating score when TikTok reports one." }, "reviewCount": { "type": "integer", "minimum": 0, "description": "Review count reported by TikTok." } }, "required": ["score", "reviewCount"], "description": "Rating summary when TikTok provides it." }, "sales": { "type": "object", "properties": { "soldCount": { "type": "integer", "minimum": 0, "description": "Sold units reported by TikTok." } }, "required": ["soldCount"], "description": "Sales counts reported by TikTok." }, "seller": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "Seller identifier." } }, "required": ["id"], "description": "Seller metadata when TikTok provides it." }, "details": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "description": "Additional TikTok-native fields for this product that were not mapped into canonical fields." } }, "required": [ "id", "title", "url", "image", "price", "rating", "sales", "seller" ], "description": "A TikTok Shop product shown on a profile showcase." }, "description": "Products shown on the TikTok profile showcase for this page. An empty array can mean no showcased products, a private account, or other cases—call the TikTok profile endpoint first when you need explicit account status." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when more products are available." }, "hasMore": { "type": "boolean", "description": "Whether another page of products is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination state for the current response." } }, "required": ["products", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "products": [ { "id": "1729508370969629931", "title": "Example skincare product title", "url": "https://www.tiktok.com/shop/pdp/1729508370969629931", "image": { "url": "https://example.com/product-cover.webp", "urls": [ "https://example.com/product-cover.webp", "https://example.com/product-cover-alt.webp" ], "width": 500, "height": 500 }, "price": { "currencyCode": "USD", "currencySymbol": "$", "salePrice": "21", "originalPrice": "36", "discountPercent": "42%" }, "rating": { "score": 4.5, "reviewCount": 5922 }, "sales": { "soldCount": 338798 }, "seller": { "id": "7495514739648989419" }, "details": { "extra_field": "Example TikTok-native payload retained here." } } ], "page": { "nextCursor": "eyJwcm9kdWN0SWRzIjpbIjE3In0", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "first_page": { "value": { "data": { "products": [ { "id": "1729508370969629931", "title": "Example skincare product title", "url": "https://www.tiktok.com/shop/pdp/1729508370969629931", "image": { "url": "https://example.com/product-cover.webp", "urls": [ "https://example.com/product-cover.webp", "https://example.com/product-cover-alt.webp" ], "width": 500, "height": 500 }, "price": { "currencyCode": "USD", "currencySymbol": "$", "salePrice": "21", "originalPrice": "36", "discountPercent": "42%" }, "rating": { "score": 4.5, "reviewCount": 5922 }, "sales": { "soldCount": 338798 }, "seller": { "id": "7495514739648989419" }, "details": { "extra_field": "Example TikTok-native payload retained here." } } ], "page": { "nextCursor": "eyJwcm9kdWN0SWRzIjpbIjE3In0", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "products": [ { "id": "1731414247972311160", "title": "Example page-two product", "url": "https://www.tiktok.com/shop/pdp/1731414247972311160", "image": { "url": "https://example.com/page2-cover.webp", "urls": ["https://example.com/page2-cover.webp"], "width": 500, "height": 500 }, "price": { "currencyCode": "USD", "currencySymbol": "$", "salePrice": "9.9", "originalPrice": "19", "discountPercent": "48%" }, "rating": { "score": 4.5, "reviewCount": 3507 }, "sales": { "soldCount": 49056 }, "seller": { "id": "7496252928214665336" } } ], "page": { "nextCursor": "eyJwcm9kdWN0SWRzIjpbIjI5In0", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "products": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/shop/products/search": { "get": { "tags": ["TikTok"], "summary": "Search TikTok Shop products", "description": "Returns product cards for a TikTok Shop catalog search. Pass a `query` string and optional `page` (1-based) and `region` code. Pagination is page-based; `data.page.hasMore` indicates whether another page can be requested.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Search query text for TikTok Shop products." }, "required": true, "description": "Search query text for TikTok Shop products.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "description": "1-based results page number. Omit to request the first page. Pagination is page-based." }, "required": false, "description": "1-based results page number. Omit to request the first page. Pagination is page-based.", "name": "page", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "DE", "FR", "IT", "ID", "MY", "MX", "PH", "SG", "ES", "TH", "VN", "BR", "JP", "IE" ], "description": "Optional country or region code for the product search catalog." }, "required": false, "description": "Optional country or region code for the product search catalog.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Product search results for the requested page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query that was evaluated for this response." }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "TikTok Shop product identifier." }, "title": { "type": "string", "minLength": 1, "description": "Product title text." }, "description": { "type": "string", "nullable": true, "description": "Product description, when available." }, "url": { "type": "string", "nullable": true, "minLength": 1, "description": "Canonical public URL for the product page, when available." }, "imageUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Primary product image URL, when available." }, "image": { "type": "object", "nullable": true, "properties": { "width": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image width in pixels, when available." }, "height": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image height in pixels, when available." }, "url": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ], "description": "Primary product image URL." } }, "required": ["width", "height", "url"], "description": "Structured image size metadata when the image URL is available." }, "shipFrom": { "type": "string", "nullable": true, "description": "Reported ship-from location text, when available." }, "trustLabel": { "type": "string", "nullable": true, "description": "TikTok Shop trust badge label, when available." }, "labels": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Label text shown for the product." }, "type": { "type": "integer", "nullable": true, "description": "TikTok Shop label type code, when available." } }, "required": ["text", "type"], "description": "A promotional, shipping, or trust label for a product card." }, "description": "Promotional, shipping, and trust labels for the product card." }, "price": { "type": "object", "properties": { "currencyCode": { "type": "string", "nullable": true, "description": "Currency name or code for displayed prices, when available." }, "currencySymbol": { "type": "string", "nullable": true, "description": "Currency symbol for the listed price, when available." }, "current": { "type": "string", "nullable": true, "description": "Current sale price for the product, when available." }, "original": { "type": "string", "nullable": true, "description": "Original or list price before discount, when available." }, "discountText": { "type": "string", "nullable": true, "description": "Human-readable discount label, when available." }, "savingText": { "type": "string", "nullable": true, "description": "Human-readable savings line, when available." } }, "required": [ "currencyCode", "currencySymbol", "current", "original", "discountText", "savingText" ], "description": "Displayed price data." }, "metrics": { "type": "object", "properties": { "sold": { "type": "integer", "nullable": true, "minimum": 0, "description": "Approximate units sold, when available." }, "reviews": { "type": "integer", "nullable": true, "minimum": 0, "description": "Number of product reviews, when available." }, "rating": { "type": "number", "nullable": true, "minimum": 0, "description": "Average product rating, when available." } }, "required": ["sold", "reviews", "rating"], "description": "Rating and sales metrics for the product." }, "shop": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "TikTok Shop seller identifier, when available." }, "name": { "type": "string", "nullable": true, "description": "Shop display name, when available." }, "logoUrl": { "type": "string", "nullable": true, "description": "Shop logo image URL, when available." } }, "required": ["id", "name", "logoUrl"], "description": "Selling shop for the product." } }, "required": [ "id", "title", "description", "url", "imageUrl", "shipFrom", "trustLabel", "labels", "price", "metrics", "shop" ], "description": "A normalized TikTok Shop search result product." }, "description": "Products returned for the requested page." }, "totalProducts": { "type": "integer", "minimum": 0, "description": "Total matching products reported for the search, when available." }, "page": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "description": "1-based page number for this response." }, "nextPage": { "type": "integer", "nullable": true, "minimum": 1, "description": "Next page number to request when more results are available; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether more product pages are likely available for this search." } }, "required": ["currentPage", "nextPage", "hasMore"], "description": "Pagination state for the current response." } }, "required": [ "query", "products", "totalProducts", "page" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "query": "shoes", "totalProducts": 100, "products": [ { "id": "1730213444857467838", "title": "Crocs Adult Classic Clogs", "description": null, "url": "https://www.tiktok.com/shop/pdp/example/1730213444857467838", "imageUrl": "https://p16.example.com/image.webp", "image": { "width": 400, "height": 400, "url": "https://p16.example.com/image.webp" }, "shipFrom": "Fontana, CA", "trustLabel": "gold", "labels": [ { "text": "Free shipping", "type": 8 } ], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "49.99", "original": "59.99", "discountText": "15%", "savingText": "Saving $10.00" }, "metrics": { "sold": 24737, "reviews": 2493, "rating": 4.8 }, "shop": { "id": "7495832567110863806", "name": "Crocs", "logoUrl": "https://p16.example.com/logo.png" } } ], "page": { "currentPage": 1, "nextPage": 2, "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "sample": { "value": { "data": { "query": "shoes", "totalProducts": 100, "products": [ { "id": "1730213444857467838", "title": "Crocs Adult Classic Clogs", "description": null, "url": "https://www.tiktok.com/shop/pdp/example/1730213444857467838", "imageUrl": "https://p16.example.com/image.webp", "image": { "width": 400, "height": 400, "url": "https://p16.example.com/image.webp" }, "shipFrom": "Fontana, CA", "trustLabel": "gold", "labels": [ { "text": "Free shipping", "type": 8 } ], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "49.99", "original": "59.99", "discountText": "15%", "savingText": "Saving $10.00" }, "metrics": { "sold": 24737, "reviews": 2493, "rating": 4.8 }, "shop": { "id": "7495832567110863806", "name": "Crocs", "logoUrl": "https://p16.example.com/logo.png" } } ], "page": { "currentPage": 1, "nextPage": 2, "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "query": "zzzzimprobablequery", "totalProducts": 0, "products": [], "page": { "currentPage": 1, "nextPage": null, "hasMore": false } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "sparse": { "value": { "data": { "query": "tshirt", "totalProducts": 2, "products": [ { "id": "1729505304355116874", "title": "Sample product with missing rating data", "description": null, "url": "https://www.tiktok.com/shop/pdp/1729505304355116874", "imageUrl": "https://p16.example.com/p.webp", "image": { "width": 400, "height": 400, "url": "https://p16.example.com/p.webp" }, "shipFrom": null, "trustLabel": null, "labels": [], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "16.00", "original": "39.98", "discountText": "60%", "savingText": "Saving $23.98" }, "metrics": { "sold": 16, "reviews": null, "rating": null }, "shop": { "id": "7494469722151290698", "name": "example-shop", "logoUrl": null } } ], "page": { "currentPage": 1, "nextPage": null, "hasMore": false } }, "meta": { "requestId": "req_01example_sparse", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/shop/products": { "get": { "tags": ["TikTok"], "summary": "List TikTok shop products", "description": "Lists products for a TikTok Shop store URL with cursor-based pagination and an optional region. When `data.page.hasMore` is true, pass `data.page.nextCursor` as the `cursor` query parameter on the next request.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public TikTok Shop store URL whose products should be listed." }, "required": true, "description": "Public TikTok Shop store URL whose products should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Pagination cursor from a previous response. Omit to request the first page." }, "required": false, "description": "Pagination cursor from a previous response. Omit to request the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "DE", "FR", "IT", "ID", "MY", "MX", "PH", "SG", "ES", "TH", "VN", "BR", "JP", "IE" ], "description": "Optional region code for the shop catalog. When omitted, the default catalog region is US." }, "required": false, "description": "Optional region code for the shop catalog. When omitted, the default catalog region is US.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Store listing result. `data.lookupStatus` is `not_found` when the storefront cannot be resolved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the storefront resolved for this request." }, "shop": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "minLength": 1, "description": "Shop seller identifier, when available." }, "name": { "type": "string", "nullable": true, "minLength": 1, "description": "Shop display name, when available." }, "logoUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Shop logo image URL, when available." }, "storeUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Canonical public URL for the shop storefront, when available." }, "region": { "type": "string", "nullable": true, "minLength": 1, "description": "Region code reported for the storefront, when available." }, "rating": { "type": "number", "nullable": true, "minimum": 0, "description": "Average shop rating, when available." }, "soldCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Approximate units sold for the shop, when available." }, "reviewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Number of shop reviews, when available." }, "onSellProductCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of products currently on sale, when available." }, "followerCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Follower count for the shop, when available." }, "videoCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video count associated with the shop, when available." } }, "required": [ "id", "name", "logoUrl", "storeUrl", "region", "rating", "soldCount", "reviewCount", "onSellProductCount", "followerCount", "videoCount" ], "description": "Store summary when `lookupStatus` is `found`; null when the store could not be resolved." }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "TikTok Shop product identifier." }, "title": { "type": "string", "minLength": 1, "description": "Product title text." }, "description": { "type": "string", "nullable": true, "description": "Product description, when available." }, "url": { "type": "string", "nullable": true, "minLength": 1, "description": "Canonical public URL for the product page, when available." }, "imageUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Primary product image URL, when available." }, "image": { "type": "object", "nullable": true, "properties": { "width": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image width in pixels, when available." }, "height": { "type": "integer", "nullable": true, "minimum": 0, "description": "Image height in pixels, when available." }, "url": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ], "description": "Primary product image URL." } }, "required": ["width", "height", "url"], "description": "Structured image size metadata when the image URL is available." }, "shipFrom": { "type": "string", "nullable": true, "description": "Reported ship-from location text, when available." }, "trustLabel": { "type": "string", "nullable": true, "description": "TikTok Shop trust badge label, when available." }, "labels": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Label text shown for the product." }, "type": { "type": "integer", "nullable": true, "description": "TikTok Shop label type code, when available." } }, "required": ["text", "type"], "description": "A promotional, shipping, or trust label for a product card." }, "description": "Promotional, shipping, and trust labels for the product card." }, "price": { "type": "object", "properties": { "currencyCode": { "type": "string", "nullable": true, "description": "Currency name or code for displayed prices, when available." }, "currencySymbol": { "type": "string", "nullable": true, "description": "Currency symbol for the listed price, when available." }, "current": { "type": "string", "nullable": true, "description": "Current sale price for the product, when available." }, "original": { "type": "string", "nullable": true, "description": "Original or list price before discount, when available." }, "discountText": { "type": "string", "nullable": true, "description": "Human-readable discount label, when available." }, "savingText": { "type": "string", "nullable": true, "description": "Human-readable savings line, when available." } }, "required": [ "currencyCode", "currencySymbol", "current", "original", "discountText", "savingText" ], "description": "Displayed price data." }, "metrics": { "type": "object", "properties": { "sold": { "type": "integer", "nullable": true, "minimum": 0, "description": "Approximate units sold, when available." }, "reviews": { "type": "integer", "nullable": true, "minimum": 0, "description": "Number of product reviews, when available." }, "rating": { "type": "number", "nullable": true, "minimum": 0, "description": "Average product rating, when available." } }, "required": ["sold", "reviews", "rating"], "description": "Rating and sales metrics for the product." }, "shop": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "TikTok Shop seller identifier, when available." }, "name": { "type": "string", "nullable": true, "description": "Shop display name, when available." }, "logoUrl": { "type": "string", "nullable": true, "description": "Shop logo image URL, when available." } }, "required": ["id", "name", "logoUrl"], "description": "Selling shop for the product." } }, "required": [ "id", "title", "description", "url", "imageUrl", "shipFrom", "trustLabel", "labels", "price", "metrics", "shop" ], "description": "A normalized TikTok Shop search result product." }, "description": "Product cards returned for the requested page." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "minLength": 1, "description": "Opaque cursor to pass as `cursor` on the next request when `hasMore` is true; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of products can be requested for this store." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination state for the current response." } }, "required": ["lookupStatus", "shop", "products", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "shop": { "id": "7495794203056835079", "name": "Goli Nutrition", "logoUrl": "https://p16.example.com/shop-logo.webp", "storeUrl": "https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079", "region": "US", "rating": 4.6, "soldCount": 3767605, "reviewCount": 284185, "onSellProductCount": 36, "followerCount": 237879, "videoCount": 2413 }, "products": [ { "id": "1729527313880355335", "title": "Goli Ashwagandha & Vitamin D Gummy - Mixed Berry, KSM-66, Vegan, Plant Based, Non-GMO, Gluten-Free & Gelatin Free.", "description": null, "url": "https://www.tiktok.com/shop/pdp/1729527313880355335", "imageUrl": "https://p16.example.com/product.webp", "image": { "width": 500, "height": 500, "url": "https://p16.example.com/product.webp" }, "shipFrom": null, "trustLabel": null, "labels": [], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "14.96", "original": "24.99", "discountText": "40%", "savingText": "10.03" }, "metrics": { "sold": 1283012, "reviews": 93661, "rating": 4.5 }, "shop": { "id": "7495794203056835079", "name": "Goli Nutrition", "logoUrl": null } } ], "page": { "nextCursor": "WzkzNjU0LCIxNzI5NTg5MjU1NzcwMzc4NzU5Il0=", "hasMore": true } }, "meta": { "requestId": "req_01example_shop_products", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "shop": { "id": "7495794203056835079", "name": "Goli Nutrition", "logoUrl": "https://p16.example.com/shop-logo.webp", "storeUrl": "https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079", "region": "US", "rating": 4.6, "soldCount": 3767605, "reviewCount": 284185, "onSellProductCount": 36, "followerCount": 237879, "videoCount": 2413 }, "products": [ { "id": "1729527313880355335", "title": "Goli Ashwagandha & Vitamin D Gummy - Mixed Berry, KSM-66, Vegan, Plant Based, Non-GMO, Gluten-Free & Gelatin Free.", "description": null, "url": "https://www.tiktok.com/shop/pdp/1729527313880355335", "imageUrl": "https://p16.example.com/product.webp", "image": { "width": 500, "height": 500, "url": "https://p16.example.com/product.webp" }, "shipFrom": null, "trustLabel": null, "labels": [], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "14.96", "original": "24.99", "discountText": "40%", "savingText": "10.03" }, "metrics": { "sold": 1283012, "reviews": 93661, "rating": 4.5 }, "shop": { "id": "7495794203056835079", "name": "Goli Nutrition", "logoUrl": null } } ], "page": { "nextCursor": "WzkzNjU0LCIxNzI5NTg5MjU1NzcwMzc4NzU5Il0=", "hasMore": true } }, "meta": { "requestId": "req_01example_shop_products", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "shop": null, "products": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_shop_not_found", "creditsCharged": 1, "version": "v1" } } }, "sparse": { "value": { "data": { "lookupStatus": "found", "shop": { "id": "7495794203056835079", "name": null, "logoUrl": null, "storeUrl": "https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079", "region": "US", "rating": null, "soldCount": null, "reviewCount": null, "onSellProductCount": null, "followerCount": null, "videoCount": null }, "products": [ { "id": "1732299628898390535", "title": "Goli Restore Kit - 1 Silk Pillow Case & 1 Silk Eye Mask", "description": null, "url": "https://www.tiktok.com/shop/pdp/1732299628898390535", "imageUrl": "https://p16.example.com/p.webp", "image": { "width": 500, "height": 500, "url": "https://p16.example.com/p.webp" }, "shipFrom": null, "trustLabel": null, "labels": [], "price": { "currencyCode": "USD", "currencySymbol": "$", "current": "99.98", "original": null, "discountText": null, "savingText": null }, "metrics": { "sold": 3076, "reviews": null, "rating": null }, "shop": { "id": "7495794203056835079", "name": null, "logoUrl": null } } ], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_shop_sparse", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/products": { "get": { "tags": ["TikTok"], "summary": "Get TikTok Shop product", "description": "Returns detailed catalog data for a TikTok Shop product page URL, including offer and media fields when the page resolves. Response shape may change as the catalog updates.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public TikTok Shop product detail page URL for the product to retrieve." }, "required": true, "description": "Public TikTok Shop product detail page URL for the product to retrieve.", "name": "url", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "DE", "FR", "IT", "ID", "MY", "MX", "PH", "SG", "ES", "TH", "VN", "BR", "JP", "IE" ], "description": "Optional country or region code for the product catalog. When omitted, the default catalog region applies." }, "required": false, "description": "Optional country or region code for the product catalog. When omitted, the default catalog region applies.", "name": "region", "in": "query" } ], "responses": { "200": { "description": "Product detail for the given product page URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "description": "Product detail data from the catalog, when the product page could be resolved." } }, "required": ["product"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "product": { "product_id": "1729587769570529799", "status": 1, "seller": { "name": "Goli Nutrition" } } }, "meta": { "requestId": "req_01hzyd8c6tfvb9v1k7w9fxv7aa", "creditsCharged": 1, "version": "v1" } }, "examples": { "product_detail": { "value": { "data": { "product": { "product_id": "1729587769570529799", "status": 1, "seller": { "name": "Goli Nutrition" } } }, "meta": { "requestId": "req_01hzyd8c6tfvb9v1k7w9fxv7aa", "creditsCharged": 1, "version": "v1" } } }, "minimal_keys": { "value": { "data": { "product": { "product_id": "1729587769570529799" } }, "meta": { "requestId": "req_01example_tiktok_product_sparse", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/products/reviews": { "get": { "tags": ["TikTok"], "summary": "List TikTok Shop product reviews", "description": "Returns customer reviews for a TikTok Shop product. Pass a public product page `url`, a `productId`, or both. Results are page-based; use `data.page.nextPage` as the `page` query parameter on the next request when `data.page.hasMore` is true. `data.lookupStatus` is `not_found` when the product cannot be resolved.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public TikTok Shop product detail page URL for the product whose reviews should be listed." }, "required": false, "description": "Public TikTok Shop product detail page URL for the product whose reviews should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "TikTok Shop product identifier. Provide this instead of `url` when you already know the product id." }, "required": false, "description": "TikTok Shop product identifier. Provide this instead of `url` when you already know the product id.", "name": "productId", "in": "query" }, { "schema": { "type": "string", "enum": [ "US", "GB", "DE", "FR", "IT", "ID", "MY", "MX", "PH", "SG", "ES", "TH", "VN", "BR", "JP", "IE" ], "description": "Optional country or region code for the product review catalog. When omitted, the default catalog region applies." }, "required": false, "description": "Optional country or region code for the product review catalog. When omitted, the default catalog region applies.", "name": "region", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "description": "1-based review page number. Omit to request the first page." }, "required": false, "description": "1-based review page number. Omit to request the first page.", "name": "page", "in": "query" } ], "responses": { "200": { "description": "Product reviews for the requested page. `lookupStatus` is `not_found` when the product cannot be resolved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the product could be resolved for this request." }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable id for the review when available." }, "productId": { "type": "string", "minLength": 1, "description": "TikTok Shop product id for this review." }, "skuId": { "type": "string", "nullable": true, "minLength": 1, "description": "Sku id for the purchased variant, when available." }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Star rating for the review (1-5)." }, "text": { "type": "string", "nullable": true, "description": "Review body text, when available." }, "createdAt": { "type": "string", "nullable": true, "minLength": 1, "description": "ISO-8601 timestamp for when the review was posted, when available." }, "verifiedPurchase": { "type": "boolean", "nullable": true, "description": "Whether the review is from a verified purchase, when available." }, "incentivized": { "type": "boolean", "nullable": true, "description": "Whether the review is marked as incentivized, when available." }, "reviewer": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "minLength": 1, "description": "Reviewer id when available." }, "name": { "type": "string", "nullable": true, "minLength": 1, "description": "Display name when available." }, "avatarUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Profile image URL when available." } }, "required": ["id", "name", "avatarUrl"], "description": "Reviewer display information." }, "media": { "type": "object", "properties": { "displayImageUrl": { "type": "string", "nullable": true, "minLength": 1, "description": "Primary image attached to the review, when available." }, "imageUrls": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Additional image URLs for the review when available." } }, "required": ["displayImageUrl", "imageUrls"], "description": "Media attached to a review." }, "variant": { "type": "string", "nullable": true, "minLength": 1, "description": "Human-readable label for the purchased variant, when available." }, "country": { "type": "string", "nullable": true, "minLength": 1, "description": "Country code associated with the review, when available." } }, "required": [ "id", "productId", "skuId", "rating", "text", "createdAt", "verifiedPurchase", "incentivized", "reviewer", "media", "variant", "country" ], "description": "A single customer review for a TikTok Shop product." }, "description": "Customer reviews for the product on this page." }, "summary": { "type": "object", "properties": { "totalReviews": { "type": "integer", "nullable": true, "minimum": 0, "description": "Total number of reviews reported for the product, when available." }, "averageRating": { "type": "number", "nullable": true, "minimum": 0, "description": "Average star rating, when available." }, "ratingDistribution": { "type": "object", "properties": { "oneStar": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of 1-star ratings, when available." }, "twoStar": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of 2-star ratings, when available." }, "threeStar": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of 3-star ratings, when available." }, "fourStar": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of 4-star ratings, when available." }, "fiveStar": { "type": "integer", "nullable": true, "minimum": 0, "description": "Count of 5-star ratings, when available." } }, "required": [ "oneStar", "twoStar", "threeStar", "fourStar", "fiveStar" ], "description": "Breakdown of reviews by star rating, when available." } }, "required": [ "totalReviews", "averageRating", "ratingDistribution" ], "description": "Summary statistics for the product review set." }, "page": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "description": "1-based page number for this response." }, "nextPage": { "type": "integer", "nullable": true, "minimum": 1, "description": "Next page number to request when more pages are available; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of reviews is available." } }, "required": ["currentPage", "nextPage", "hasMore"], "description": "Pagination information for the current response." } }, "required": [ "lookupStatus", "reviews", "summary", "page" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "reviews": [ { "id": "7610144993492207374", "productId": "1731578642912612516", "skuId": null, "rating": 5, "text": "Works great for my cat.", "createdAt": "2025-12-25T10:00:00.000Z", "verifiedPurchase": true, "incentivized": false, "reviewer": { "id": "6952699155328861189", "name": "Emily", "avatarUrl": "https://p16.example.com/avatar.jpg" }, "media": { "displayImageUrl": null, "imageUrls": [] }, "variant": "Item: Default", "country": "US" } ], "summary": { "totalReviews": 808, "averageRating": 4.5, "ratingDistribution": { "oneStar": 10, "twoStar": 5, "threeStar": 8, "fourStar": 20, "fiveStar": 100 } }, "page": { "currentPage": 1, "nextPage": 2, "hasMore": true } }, "meta": { "requestId": "req_01example_tiktok_product_reviews", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "reviews": [ { "id": "7610144993492207374", "productId": "1731578642912612516", "skuId": null, "rating": 5, "text": "Works great for my cat.", "createdAt": "2025-12-25T10:00:00.000Z", "verifiedPurchase": true, "incentivized": false, "reviewer": { "id": "6952699155328861189", "name": "Emily", "avatarUrl": "https://p16.example.com/avatar.jpg" }, "media": { "displayImageUrl": null, "imageUrls": [] }, "variant": "Item: Default", "country": "US" } ], "summary": { "totalReviews": 808, "averageRating": 4.5, "ratingDistribution": { "oneStar": 10, "twoStar": 5, "threeStar": 8, "fourStar": 20, "fiveStar": 100 } }, "page": { "currentPage": 1, "nextPage": 2, "hasMore": true } }, "meta": { "requestId": "req_01example_tiktok_product_reviews", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "lookupStatus": "found", "reviews": [], "summary": { "totalReviews": 0, "averageRating": null, "ratingDistribution": { "oneStar": null, "twoStar": null, "threeStar": null, "fourStar": null, "fiveStar": null } }, "page": { "currentPage": 1, "nextPage": null, "hasMore": false } }, "meta": { "requestId": "req_01example_tiktok_product_reviews_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "reviews": [], "summary": { "totalReviews": null, "averageRating": null, "ratingDistribution": { "oneStar": null, "twoStar": null, "threeStar": null, "fourStar": null, "fiveStar": null } }, "page": { "currentPage": 1, "nextPage": null, "hasMore": false } }, "meta": { "requestId": "req_01example_tiktok_product_reviews_not_found", "creditsCharged": 1, "version": "v1" } } }, "sparse": { "value": { "data": { "lookupStatus": "found", "reviews": [ { "id": "7620000000000000001", "productId": "1731578642912612516", "skuId": null, "rating": 4, "text": "Good.", "createdAt": "2025-12-20T10:00:00.000Z", "verifiedPurchase": true, "incentivized": null, "reviewer": { "id": null, "name": "A**1", "avatarUrl": null }, "media": { "displayImageUrl": null, "imageUrls": [] }, "variant": "Item: Default", "country": "US" } ], "summary": { "totalReviews": 100, "averageRating": 4.4, "ratingDistribution": { "oneStar": 2, "twoStar": 1, "threeStar": 5, "fourStar": 10, "fiveStar": 20 } }, "page": { "currentPage": 2, "nextPage": 3, "hasMore": true } }, "meta": { "requestId": "req_01example_tiktok_product_reviews_sparse", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/videos": { "get": { "tags": ["TikTok"], "summary": "Get TikTok video", "description": "Returns public metadata for a single TikTok video or photo post.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [ { "queryParam": "downloadMedia", "credits": 10, "when": "boolean_true", "label": "Hosted media download" } ], "maxCredits": 11, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base; +10 when `downloadMedia=true` (up to 11 credits on success). See `meta.creditsCharged`. Normalization failures are charged 1 credit.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the video or photo post." }, "required": true, "description": "Link to the video or photo post.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional two-letter region (country code) used to route the request when needed." }, "required": false, "description": "Optional two-letter region (country code) used to route the request when needed.", "name": "region", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, returns a smaller response with fewer fields." }, "required": false, "description": "When true, returns a smaller response with fewer fields.", "name": "trim", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, includes hosted CDN URLs in `downloads` when available. Adds 10 credits (11 total with the base lookup) on successful lookups, even if `downloads` is empty." }, "required": false, "description": "When true, includes hosted CDN URLs in `downloads` when available. Adds 10 credits (11 total with the base lookup) on successful lookups, even if `downloads` is empty.", "name": "downloadMedia", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, includes the video transcript (WEBVTT) in `transcript` when one is available." }, "required": false, "description": "When true, includes the video transcript (WEBVTT) in `transcript` when one is available.", "name": "getTranscript", "in": "query" } ], "responses": { "200": { "description": "Video metadata (found or not found in body).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the video was resolved." }, "video": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "TikTok video id." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public TikTok URL for this video." }, "caption": { "type": "string", "nullable": true, "description": "Caption text." }, "createdAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp when the video was posted." }, "region": { "type": "string", "nullable": true, "description": "Video region (two-letter country code)." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video duration in milliseconds." }, "mediaType": { "type": "string", "enum": ["video", "slideshow"], "description": "Whether the post is a video or a photo slideshow." }, "isAd": { "type": "boolean", "description": "Whether TikTok marks the post as an ad." } }, "required": [ "id", "url", "caption", "createdAt", "durationMs", "mediaType", "isAd" ], "description": "Video details when found." }, "author": { "type": "object", "nullable": true, "properties": { "platformUserId": { "type": "string", "description": "Numeric user id." }, "secUid": { "type": "string", "description": "Stable opaque user id." }, "handle": { "type": "string", "minLength": 1, "description": "Public username without a leading @." }, "nickname": { "type": "string", "nullable": true, "description": "Display name." }, "verified": { "type": "boolean", "description": "Whether the account is verified." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile picture URL." }, "signature": { "type": "string", "nullable": true, "description": "Profile bio text." }, "region": { "type": "string", "nullable": true, "description": "Two-letter country code when available." }, "privateAccount": { "type": "boolean", "description": "Whether the account is private." } }, "required": ["handle", "verified"], "description": "Author when found." }, "music": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": true, "description": "Music or sound id." }, "title": { "type": "string", "nullable": true, "description": "Music title." }, "author": { "type": "string", "nullable": true, "description": "Music author." }, "playUrl": { "type": "string", "nullable": true, "description": "Music playable URL." }, "coverUrl": { "type": "string", "nullable": true, "description": "Music cover image URL." }, "durationSec": { "type": "number", "nullable": true, "minimum": 0, "description": "Music duration in seconds." }, "isOriginal": { "type": "boolean", "description": "Whether the sound is marked as original." } }, "description": "Music or sound when found." }, "metrics": { "type": "object", "nullable": true, "properties": { "views": { "type": "integer", "nullable": true, "minimum": 0, "description": "Play count." }, "likes": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count." }, "shares": { "type": "integer", "nullable": true, "minimum": 0, "description": "Share count." }, "saves": { "type": "integer", "nullable": true, "minimum": 0, "description": "Save or collection count." } }, "description": "Engagement metrics for the video." }, "media": { "type": "object", "nullable": true, "properties": { "downloadUrl": { "type": "string", "nullable": true, "description": "Best available video URL (typically watermarked)." }, "downloadWithoutWatermarkUrl": { "type": "string", "nullable": true, "description": "Best available video URL without watermark." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail or cover image URL." }, "dimensions": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Pixel dimensions." }, "slideshowImages": { "type": "array", "items": { "type": "string" }, "description": "Ordered image URLs when the post is a photo slideshow." } }, "required": [ "downloadUrl", "downloadWithoutWatermarkUrl", "thumbnailUrl" ], "description": "Primary playable media payload for the video." }, "transcript": { "type": "object", "nullable": true, "properties": { "format": { "type": "string", "enum": ["webvtt"], "description": "Transcript format." }, "content": { "type": "string", "description": "Raw transcript text." } }, "required": ["format", "content"], "description": "Populated only when `getTranscript=true` was passed and a transcript was available." }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "description": "Video id from the post." }, "originalUrl": { "type": "string", "description": "Source media URL." }, "cdnUrl": { "type": "string", "description": "Permanent hosted URL." }, "type": { "type": "string", "enum": ["video", "image"], "description": "Asset type." } }, "required": ["originalUrl", "cdnUrl", "type"], "description": "A hosted media asset." }, "description": "Populated only when `downloadMedia=true` was passed and media was available." }, "details": { "type": "object", "properties": {}, "additionalProperties": { "nullable": true }, "description": "Additional TikTok-native fields from the post (author, music, video, etc.), minus keys already promoted above." } }, "required": [ "lookupStatus", "video", "author", "music", "metrics", "media", "transcript", "downloads" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "video": { "id": "7587811642650545421", "url": "https://www.tiktok.com/@nike/video/7587811642650545421", "caption": "Example caption.", "createdAt": "2025-12-25T12:00:00.000Z", "region": "US", "durationMs": 46315, "mediaType": "video", "isAd": false }, "author": { "handle": "nike", "nickname": "Nike", "verified": true, "avatarUrl": "https://example.com/avatar.jpg", "privateAccount": false }, "music": { "title": "original sound", "author": "Nike" }, "metrics": { "views": 1566081, "likes": 21907, "comments": 273, "shares": 947, "saves": 1171 }, "media": { "downloadUrl": "https://example.com/watermarked.mp4", "downloadWithoutWatermarkUrl": "https://example.com/clean.mp4", "thumbnailUrl": "https://example.com/thumb.jpg" }, "transcript": null, "downloads": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7587811642650545421", "url": "https://www.tiktok.com/@nike/video/7587811642650545421", "caption": "Example caption.", "createdAt": "2025-12-25T12:00:00.000Z", "region": "US", "durationMs": 46315, "mediaType": "video", "isAd": false }, "author": { "handle": "nike", "nickname": "Nike", "verified": true, "avatarUrl": "https://example.com/avatar.jpg", "privateAccount": false }, "music": { "title": "original sound", "author": "Nike" }, "metrics": { "views": 1566081, "likes": 21907, "comments": 273, "shares": 947, "saves": 1171 }, "media": { "downloadUrl": "https://example.com/watermarked.mp4", "downloadWithoutWatermarkUrl": "https://example.com/clean.mp4", "thumbnailUrl": "https://example.com/thumb.jpg" }, "transcript": null, "downloads": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "video": null, "author": null, "music": null, "metrics": null, "media": null, "transcript": null, "downloads": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "download_media": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7587811642650545421", "url": "https://www.tiktok.com/@nike/video/7587811642650545421", "caption": "Example caption.", "createdAt": "2025-12-25T12:00:00.000Z", "region": "US", "durationMs": 46315, "mediaType": "video", "isAd": false }, "author": { "handle": "nike", "verified": true }, "music": null, "metrics": { "views": 100, "likes": 10, "comments": 1, "shares": 0, "saves": 0 }, "media": { "downloadUrl": "https://example.com/w.mp4", "downloadWithoutWatermarkUrl": "https://example.com/nw.mp4", "thumbnailUrl": "https://example.com/t.jpg" }, "transcript": null, "downloads": [ { "postId": "7587811642650545421", "originalUrl": "https://cdn.example.com/orig.mp4", "cdnUrl": "https://cdn.example.com/hosted.mp4", "type": "video" } ] }, "meta": { "requestId": "req_01example_dl", "creditsCharged": 11, "version": "v1" } } }, "slideshow": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7628328815495744790", "url": "https://www.tiktok.com/@user/photo/7628328815495744790", "caption": null, "createdAt": "2026-04-16T12:00:00.000Z", "region": "GB", "durationMs": null, "mediaType": "slideshow", "isAd": false }, "author": { "handle": "kelseycarlin1", "verified": false }, "music": null, "metrics": null, "media": { "downloadUrl": null, "downloadWithoutWatermarkUrl": null, "thumbnailUrl": "https://example.com/cover.jpg", "slideshowImages": [ "https://example.com/slide1.jpg", "https://example.com/slide2.jpg" ] }, "transcript": null, "downloads": [] }, "meta": { "requestId": "req_01example_ss", "creditsCharged": 1, "version": "v1" } } }, "transcript": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7587811642650545421", "url": "https://www.tiktok.com/@nike/video/7587811642650545421", "caption": "Example.", "createdAt": "2025-12-25T12:00:00.000Z", "region": "US", "durationMs": 46315, "mediaType": "video", "isAd": false }, "author": { "handle": "nike", "verified": true }, "music": null, "metrics": null, "media": { "downloadUrl": null, "downloadWithoutWatermarkUrl": null, "thumbnailUrl": null }, "transcript": { "format": "webvtt", "content": "WEBVTT\n\n00:00:00.140 --> 00:00:04.020\nAll right. Pizza review time" }, "downloads": [] }, "meta": { "requestId": "req_01example_tr", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/videos/comments": { "get": { "tags": ["TikTok"], "summary": "List TikTok video comments", "description": "Lists top-level comments for a TikTok video URL with optional cursor-based pagination.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the TikTok video whose comments should be listed." }, "required": true, "description": "Link to the TikTok video whose comments should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor from a previous response to fetch the next page." }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page.", "name": "cursor", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, returns a smaller response with fewer fields." }, "required": false, "description": "When true, returns a smaller response with fewer fields.", "name": "trim", "in": "query" } ], "responses": { "200": { "description": "Comment listing result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the video was resolved for this request." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable identifier for the comment when provided by TikTok; otherwise a deterministic placeholder derived from available fields." }, "text": { "type": "string", "description": "Comment text." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp when the comment was created." }, "likes": { "type": "integer", "minimum": 0, "description": "Like count on the comment." }, "replyCount": { "type": "integer", "minimum": 0, "description": "Direct reply count for the comment thread." }, "language": { "type": "string", "description": "Reported language code for the comment text." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Public TikTok username without a leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Display name shown on the commenter profile." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile image URL for the commenter when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the commenter when available." }, "secUid": { "type": "string", "description": "Opaque stable user identifier when available." } }, "required": [ "handle", "displayName", "avatarUrl" ], "description": "Comment author." } }, "required": [ "id", "text", "createdAt", "likes", "replyCount", "language", "author" ], "description": "A single top-level comment on a TikTok video." }, "description": "Top-level comments for the resolved video." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when more pages exist." }, "hasMore": { "type": "boolean", "description": "Whether another page of comments is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for this response." }, "totalComments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Total comment count reported for the video when available; null when the video could not be resolved." } }, "required": [ "lookupStatus", "comments", "page", "totalComments" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "comments": [ { "id": "7629233786471121682", "text": "Great video.", "createdAt": "2025-12-25T12:00:00.000Z", "likes": 12, "replyCount": 0, "language": "en", "author": { "handle": "user9157612562418", "displayName": "Example", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "7607454359202579477", "secUid": "MS4wLjABAAAAPt-CNXGEewLBKgqC8rW0caml6yor4v0CUzI2FAOlQ43O3vv_dBHl7Pl6uFKiWwmS" } } ], "page": { "nextCursor": null, "hasMore": false }, "totalComments": 42 }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "comments": [ { "id": "7629233786471121682", "text": "Great video.", "createdAt": "2025-12-25T12:00:00.000Z", "likes": 12, "replyCount": 0, "language": "en", "author": { "handle": "user9157612562418", "displayName": "Example", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "7607454359202579477", "secUid": "MS4wLjABAAAAPt-CNXGEewLBKgqC8rW0caml6yor4v0CUzI2FAOlQ43O3vv_dBHl7Pl6uFKiWwmS" } } ], "page": { "nextCursor": null, "hasMore": false }, "totalComments": 42 }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "no_comments": { "value": { "data": { "lookupStatus": "found", "comments": [], "page": { "nextCursor": null, "hasMore": false }, "totalComments": 0 }, "meta": { "requestId": "req_01example_nc", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "comments": [], "page": { "nextCursor": null, "hasMore": false }, "totalComments": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } }, "trimmed": { "value": { "data": { "lookupStatus": "found", "comments": [ { "id": "7629222350868729109:1776319423:7607454359202579477:0", "text": "Nice.", "createdAt": "2026-04-16T06:03:43.000Z", "likes": 1, "replyCount": 0, "language": "th", "author": { "handle": "user9157612562418", "displayName": "Example", "avatarUrl": "https://example.com/avatar.jpg", "platformUserId": "7607454359202579477", "secUid": "MS4wLjABAAAAPt-CNXGEewLBKgqC8rW0caml6yor4v0CUzI2FAOlQ43O3vv_dBHl7Pl6uFKiWwmS" } } ], "page": { "nextCursor": null, "hasMore": false }, "totalComments": 8 }, "meta": { "requestId": "req_01example_tr", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/tiktok/videos/transcript": { "get": { "tags": ["TikTok"], "summary": "Get TikTok video transcript", "description": "Returns transcript text for a TikTok video when one is available.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [ { "queryParam": "useAiFallback", "credits": 10, "when": "boolean_true", "label": "AI transcript fallback" } ], "maxCredits": 11, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base; +10 when `useAiFallback=true` (up to 11 credits on success). See `meta.creditsCharged`. Normalization failures are charged 1 credit.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^https:\\/\\/", "description": "Link to the TikTok video whose transcript should be returned." }, "required": true, "description": "Link to the TikTok video whose transcript should be returned.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Optional two-letter language code to request a transcript in a specific language when available." }, "required": false, "description": "Optional two-letter language code to request a transcript in a specific language when available.", "name": "language", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, uses SocialFetch's AI fallback when a transcript is not otherwise available. Adds 10 credits on completed lookups (11 total with the base lookup)." }, "required": false, "description": "When true, uses SocialFetch's AI fallback when a transcript is not otherwise available. Adds 10 credits on completed lookups (11 total with the base lookup).", "name": "useAiFallback", "in": "query" } ], "responses": { "200": { "description": "Transcript lookup result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the transcript lookup resolved to a TikTok video." }, "video": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "TikTok video id." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public TikTok URL for the video." } }, "required": ["id", "url"], "description": "Video identity when the lookup resolved." }, "transcript": { "type": "object", "nullable": true, "properties": { "format": { "type": "string", "enum": ["webvtt"], "description": "Transcript format." }, "content": { "type": "string", "description": "Raw transcript text." } }, "required": ["format", "content"], "description": "Transcript content when one is available for the resolved video." } }, "required": ["lookupStatus", "video", "transcript"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "video": { "id": "7605134253197708566", "url": "https://www.tiktok.com/@wildcarlosvlogs/video/7605134253197708566" }, "transcript": { "format": "webvtt", "content": "WEBVTT\n\n00:00:00.340 --> 00:00:02.440\nGive me some money. Why?" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7605134253197708566", "url": "https://www.tiktok.com/@wildcarlosvlogs/video/7605134253197708566" }, "transcript": { "format": "webvtt", "content": "WEBVTT\n\n00:00:00.340 --> 00:00:02.440\nGive me some money. Why?" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "video": null, "transcript": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } }, "no_transcript": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7579680153173822742", "url": "https://www.tiktok.com/@dadusqooo.p/video/7579680153173822742" }, "transcript": null }, "meta": { "requestId": "req_01example_null", "creditsCharged": 1, "version": "v1" } } }, "ai_fallback": { "value": { "data": { "lookupStatus": "found", "video": { "id": "7628301471137664278", "url": "https://www.tiktok.com/@maddysonm00/video/7628301471137664278" }, "transcript": { "format": "webvtt", "content": "WEBVTT\n\n00:00:00.040 --> 00:00:01.080\nhey I'm Maddie" } }, "meta": { "requestId": "req_01example_ai", "creditsCharged": 11, "version": "v1" } } } } } } }, "400": { "description": "Invalid request or the URL is not a video (for example a photo post).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": ["bad_request"] }, { "type": "string", "enum": ["transcript_target_not_video"] } ], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } }, "examples": { "bad_request": { "value": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } }, "transcript_target_not_video": { "value": { "error": { "code": "transcript_target_not_video", "message": "Example message.", "requestId": "req_01example" } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/instagram/profiles/{handle}": { "get": { "tags": ["Instagram"], "summary": "Get Instagram profile", "description": "Looks up an Instagram profile by handle. Outcomes such as found, private, or not found are indicated in `data.lookupStatus`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Instagram handle to look up, with or without a leading @." }, "required": true, "description": "Instagram handle to look up, with or without a leading @.", "name": "handle", "in": "path" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found`, `private`, or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "private", "not_found"], "description": "Whether the profile was found, private, or not found." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["instagram"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "Instagram username without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name on the Instagram profile." }, "bio": { "type": "string", "nullable": true, "description": "Profile biography text." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar image URL." }, "avatarUrlHd": { "type": "string", "nullable": true, "description": "Higher-resolution avatar URL when available." }, "verified": { "type": "boolean", "description": "Whether Instagram marks the profile as verified." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public Instagram profile URL." }, "privateAccount": { "type": "boolean", "description": "Whether the account is private." }, "platformUserId": { "type": "string", "description": "Instagram numeric user id as a string." }, "businessAccount": { "type": "boolean", "description": "Whether the account is a business account." }, "professionalAccount": { "type": "boolean", "description": "Whether the account is a professional/creator account." }, "categoryName": { "type": "string", "nullable": true, "description": "Category label when Instagram provides one." }, "externalUrl": { "type": "string", "nullable": true, "description": "Primary external link from the profile." }, "highlightReelCount": { "type": "integer", "minimum": 0, "description": "Number of story highlights on the profile." }, "bioLinks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "nullable": true, "description": "Link title shown on the profile." }, "url": { "type": "string", "minLength": 1, "description": "Destination URL." } }, "required": ["title", "url"], "description": "A link from the Instagram profile bio." }, "description": "Structured bio links when available." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "verified", "profileUrl", "privateAccount" ], "description": "Profile details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Follower count reported by Instagram." }, "following": { "type": "integer", "minimum": 0, "description": "Following count reported by Instagram." }, "posts": { "type": "integer", "minimum": 0, "description": "Total public posts count on the profile grid." } }, "required": ["followers", "following", "posts"], "description": "Profile metrics when available." }, "recentPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Instagram media id for this post (vendor-defined)." }, "shortcode": { "type": "string", "description": "Public shortcode for the post URL." }, "mediaType": { "type": "string", "enum": [ "video", "image", "sidecar", "unknown" ], "description": "Normalized media type." }, "caption": { "type": "string", "nullable": true, "description": "Post caption when available." }, "takenAt": { "type": "integer", "description": "When the media was taken or posted (Unix epoch seconds)." }, "commentCount": { "type": "integer", "minimum": 0, "description": "Comment count when available." }, "likeCount": { "type": "integer", "minimum": 0, "description": "Like count when available." }, "videoViewCount": { "type": "integer", "minimum": 0, "description": "Video view count for video posts when available." }, "displayUrl": { "type": "string", "description": "Primary display image URL." }, "thumbnailUrl": { "type": "string", "description": "Thumbnail image URL." }, "videoUrl": { "type": "string", "description": "Direct video URL when available." }, "dimensions": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "description": "Media width in pixels." }, "height": { "type": "integer", "minimum": 0, "description": "Media height in pixels." } }, "required": ["width", "height"], "description": "Width and height when available." } }, "required": [ "id", "shortcode", "mediaType", "caption", "takenAt" ], "description": "A recent post or reel from the profile grid." }, "description": "Recent grid posts from the profile when available." }, "relatedProfiles": { "type": "array", "items": { "type": "object", "properties": { "platformUserId": { "type": "string", "description": "Instagram user id for the account." }, "handle": { "type": "string", "description": "Instagram username." }, "displayName": { "type": "string", "nullable": true, "description": "Display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile picture URL." }, "verified": { "type": "boolean", "description": "Whether the account is verified." }, "privateAccount": { "type": "boolean", "description": "Whether the account is private." } }, "required": [ "platformUserId", "handle", "displayName", "avatarUrl", "verified", "privateAccount" ], "description": "A suggested related Instagram account." }, "description": "Suggested related accounts when available." } }, "required": [ "lookupStatus", "profile", "metrics", "recentPosts", "relatedProfiles" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "instagram", "handle": "adrianhorning", "displayName": "Adrian Horning", "bio": "Scraping the web", "avatarUrl": "https://example.com/avatar.jpg", "avatarUrlHd": "https://example.com/avatar-hd.jpg", "verified": true, "profileUrl": "https://www.instagram.com/adrianhorning/", "privateAccount": false, "platformUserId": "2700692569", "businessAccount": true, "professionalAccount": true, "categoryName": "Entrepreneur", "externalUrl": "https://scrapecreators.com/", "highlightReelCount": 0, "bioLinks": [ { "title": "Social Media APIs", "url": "https://scrapecreators.com" } ] }, "metrics": { "followers": 25116, "following": 101, "posts": 71 }, "recentPosts": [ { "id": "3540614075954356349", "shortcode": "DEiyb48AeB9", "mediaType": "video", "caption": null, "takenAt": 1736294201, "commentCount": 12, "likeCount": 126, "videoViewCount": 1318, "displayUrl": "https://example.com/post.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "dimensions": { "width": 1080, "height": 1920 } } ], "relatedProfiles": [ { "platformUserId": "66873381803", "handle": "itsallykrinsky", "displayName": "ally", "avatarUrl": "https://example.com/related.jpg", "verified": false, "privateAccount": false } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "instagram", "handle": "adrianhorning", "displayName": "Adrian Horning", "bio": "Scraping the web", "avatarUrl": "https://example.com/avatar.jpg", "avatarUrlHd": "https://example.com/avatar-hd.jpg", "verified": true, "profileUrl": "https://www.instagram.com/adrianhorning/", "privateAccount": false, "platformUserId": "2700692569", "businessAccount": true, "professionalAccount": true, "categoryName": "Entrepreneur", "externalUrl": "https://scrapecreators.com/", "highlightReelCount": 0, "bioLinks": [ { "title": "Social Media APIs", "url": "https://scrapecreators.com" } ] }, "metrics": { "followers": 25116, "following": 101, "posts": 71 }, "recentPosts": [ { "id": "3540614075954356349", "shortcode": "DEiyb48AeB9", "mediaType": "video", "caption": null, "takenAt": 1736294201, "commentCount": 12, "likeCount": 126, "videoViewCount": 1318, "displayUrl": "https://example.com/post.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "dimensions": { "width": 1080, "height": 1920 } } ], "relatedProfiles": [ { "platformUserId": "66873381803", "handle": "itsallykrinsky", "displayName": "ally", "avatarUrl": "https://example.com/related.jpg", "verified": false, "privateAccount": false } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "private": { "value": { "data": { "lookupStatus": "private", "profile": { "platform": "instagram", "handle": "lukem121", "displayName": "Luke Askew", "bio": "", "avatarUrl": "https://example.com/priv.jpg", "verified": false, "profileUrl": "https://www.instagram.com/lukem121/", "privateAccount": true, "platformUserId": "18768689" }, "metrics": { "followers": 107, "following": 187, "posts": 13 }, "recentPosts": [], "relatedProfiles": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "metrics": null, "recentPosts": [], "relatedProfiles": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/instagram/profiles/{handle}/posts": { "get": { "tags": ["Instagram"], "summary": "List Instagram profile posts", "description": "Lists public posts for an Instagram profile with cursor-based pagination. Private accounts, missing handles, and accounts with no posts can all surface as HTTP `200` with an empty `data.posts` page—this route does not expose `lookupStatus`. Call `GET /v1/instagram/profiles/{handle}` first when you need explicit `found` / `private` / `not_found` before interpreting an empty list.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.posts` page with `hasMore: false` can represent a private account, a missing handle, no public posts, or similar—there is no `lookupStatus` field on this route.", "disambiguation": "Call `GET /v1/instagram/profiles/{handle}` first when you need `found` / `private` / `not_found` before interpreting an empty posts page." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Instagram handle whose posts should be listed." }, "required": true, "description": "Instagram handle whose posts should be listed.", "name": "handle", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`)." }, "required": false, "description": "Opaque pagination cursor from a previous response (`data.page.nextCursor`).", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Instagram posts for the requested profile page. Empty `data.posts` is ambiguous without a profile preflight—see the operation description.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Instagram media id for this item (vendor-defined composite id)." }, "shortcode": { "type": "string", "minLength": 1, "description": "Public shortcode used in the Instagram post URL." }, "mediaType": { "type": "string", "enum": [ "image", "video", "sidecar", "unknown" ], "description": "Normalized media type." }, "caption": { "type": "string", "nullable": true, "description": "Caption text when Instagram provides one." }, "takenAt": { "type": "integer", "description": "When the media was taken or posted (Unix epoch seconds)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public Instagram URL for this media." }, "displayUrl": { "type": "string", "description": "Primary display image URL when available." }, "thumbnailUrl": { "type": "string", "description": "Thumbnail or cover image URL when available." }, "videoUrl": { "type": "string", "description": "Direct video URL when this item is a video and a URL is available." }, "likeCount": { "type": "integer", "minimum": 0, "description": "Like count when Instagram exposes it." }, "commentCount": { "type": "integer", "minimum": 0, "description": "Comment count when Instagram exposes it." }, "playCount": { "type": "integer", "minimum": 0, "description": "Play or view count for video content when Instagram exposes it (Instagram-only views when distinguishable)." }, "dimensions": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "description": "Media width in pixels." }, "height": { "type": "integer", "minimum": 0, "description": "Media height in pixels." } }, "required": ["width", "height"], "description": "Width and height when available." }, "taggedUsers": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Tagged Instagram username without a leading @." }, "platformUserId": { "type": "string", "description": "Instagram numeric user id for the tagged account when present." } }, "required": ["handle"], "description": "A user tagged in an Instagram media item." }, "description": "Users tagged in the media when Instagram exposes them." } }, "required": [ "id", "shortcode", "mediaType", "caption", "takenAt", "url" ], "description": "A single Instagram post in a profile feed page." }, "description": "Instagram posts for the requested profile page. An empty array can represent a private account, a missing handle, or simply no posts—use the profile endpoint first when you need explicit `lookupStatus`." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when more posts are available." }, "hasMore": { "type": "boolean", "description": "Whether another page of posts is available from Instagram." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination state for the current response." } }, "required": ["posts", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "posts": [ { "id": "3600545900919030401_260462810", "shortcode": "DH3tWudxIKB", "mediaType": "video", "caption": "Example caption text.", "takenAt": 1743438570, "url": "https://www.instagram.com/barstoolsports/p/DH3tWudxIKB/", "displayUrl": "https://example.com/display.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "likeCount": 387, "commentCount": 12, "playCount": 35499, "dimensions": { "width": 720, "height": 1280 }, "taggedUsers": [ { "handle": "danabeers", "platformUserId": "212690485" } ] } ], "page": { "nextCursor": "3599731065704772932_260462810", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "first_page": { "value": { "data": { "posts": [ { "id": "3600545900919030401_260462810", "shortcode": "DH3tWudxIKB", "mediaType": "video", "caption": "Example caption text.", "takenAt": 1743438570, "url": "https://www.instagram.com/barstoolsports/p/DH3tWudxIKB/", "displayUrl": "https://example.com/display.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": "https://example.com/video.mp4", "likeCount": 387, "commentCount": 12, "playCount": 35499, "dimensions": { "width": 720, "height": 1280 }, "taggedUsers": [ { "handle": "danabeers", "platformUserId": "212690485" } ] } ], "page": { "nextCursor": "3599731065704772932_260462810", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "posts": [ { "id": "3599731065704772932_260462810", "shortcode": "ABCdefGhIjK", "mediaType": "image", "caption": null, "takenAt": 1743000000, "url": "https://www.instagram.com/barstoolsports/p/ABCdefGhIjK/", "displayUrl": "https://example.com/page2.jpg", "likeCount": 120, "commentCount": 3 } ], "page": { "nextCursor": "3599000000000000000_260462810", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "posts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle, cursor, or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/instagram/posts": { "get": { "tags": ["Instagram"], "summary": "Get Instagram post or reel", "description": "Returns public metadata for a single Instagram post or reel. Play counts reflect Instagram-native totals when distinguishable from cross-posted network totals.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [ { "queryParam": "downloadMedia", "credits": 10, "when": "boolean_true", "label": "Hosted media download" } ], "maxCredits": 11, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base; +10 when `downloadMedia=true` (up to 11 credits on success). See `meta.creditsCharged`. Normalization failures are charged 1 credit.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the post or reel." }, "required": true, "description": "Link to the post or reel.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Optional two-letter region (country code) for request routing." }, "required": false, "description": "Optional two-letter region (country code) for request routing.", "name": "region", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, returns a smaller response with fewer fields." }, "required": false, "description": "When true, returns a smaller response with fewer fields.", "name": "trim", "in": "query" }, { "schema": { "type": "boolean", "description": "When true, returns permanent CDN URLs for media in `downloads`. Adds 10 credits (11 total including the base lookup)." }, "required": false, "description": "When true, returns permanent CDN URLs for media in `downloads`. Adds 10 credits (11 total including the base lookup).", "name": "downloadMedia", "in": "query" } ], "responses": { "200": { "description": "Post or reel metadata (found or not found in body).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the post or reel was resolved." }, "post": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "Instagram media id." }, "shortcode": { "type": "string", "minLength": 1, "description": "Public shortcode." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public Instagram URL for this media." }, "caption": { "type": "string", "nullable": true, "description": "Caption text." }, "takenAt": { "type": "integer", "description": "Unix timestamp when the media was taken or posted." }, "accessibilityCaption": { "type": "string", "nullable": true }, "isAd": { "type": "boolean" }, "isAffiliate": { "type": "boolean" }, "isPaidPartnership": { "type": "boolean" } }, "required": [ "id", "shortcode", "url", "caption", "takenAt" ], "description": "Post details when found." }, "owner": { "type": "object", "nullable": true, "properties": { "platformUserId": { "type": "string", "description": "Instagram numeric user id." }, "handle": { "type": "string", "minLength": 1, "description": "Instagram username without a leading @." }, "fullName": { "type": "string", "nullable": true, "description": "Display name when available." }, "verified": { "type": "boolean", "description": "Whether the account is verified." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile picture URL." }, "privateAccount": { "type": "boolean", "description": "Whether the account is private." } }, "required": ["handle", "verified"], "description": "Author when found." }, "metrics": { "type": "object", "nullable": true, "properties": { "likes": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count when Instagram exposes it." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count when Instagram exposes it." }, "playCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Play or view count for video/reel content when available." } }, "description": "Engagement metrics for the media." }, "media": { "type": "object", "nullable": true, "properties": { "mediaType": { "type": "string", "enum": ["image", "video", "sidecar", "unknown"], "description": "Normalized media type." }, "displayUrl": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "videoUrl": { "type": "string", "nullable": true }, "videoDurationSec": { "type": "number", "nullable": true, "minimum": 0 }, "dimensions": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0, "description": "Media width in pixels." }, "height": { "type": "integer", "minimum": 0, "description": "Media height in pixels." } }, "required": ["width", "height"], "description": "Dimensions for a media item." }, "productType": { "type": "string", "nullable": true, "description": "Product type when present (e.g. clips)." }, "carouselChildren": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shortcode": { "type": "string" }, "displayUrl": { "type": "string" }, "videoUrl": { "type": "string", "nullable": true }, "isVideo": { "type": "boolean" } }, "description": "One child item in a carousel (sidecar) post." }, "description": "Sidecar children when this is a carousel." } }, "required": ["mediaType"], "description": "Primary media payload for the post." }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "description": "Post or media id when present." }, "originalUrl": { "type": "string", "description": "Original Instagram CDN URL." }, "cdnUrl": { "type": "string", "description": "Permanent hosted URL when download succeeded." }, "type": { "type": "string", "enum": ["image", "video"], "description": "Asset type." } }, "required": ["originalUrl", "cdnUrl", "type"], "description": "A downloaded media file." }, "description": "Permanent CDN URLs when `downloadMedia` was true and media assets are available." }, "taggedUsers": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Tagged username." }, "platformUserId": { "type": "string" } }, "required": ["handle"], "description": "A user tagged in the media." } }, "coauthors": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1 }, "platformUserId": { "type": "string" }, "verified": { "type": "boolean" }, "avatarUrl": { "type": "string", "nullable": true } }, "required": ["handle"] } } }, "required": [ "lookupStatus", "post", "owner", "metrics", "media", "downloads" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "post": { "id": "3672288292859749817", "shortcode": "DL2lr7ouyW5", "url": "https://www.instagram.com/p/DL2lr7ouyW5/", "caption": "Example caption.", "takenAt": 1751990900, "accessibilityCaption": null, "isAd": false, "isAffiliate": false, "isPaidPartnership": false }, "owner": { "platformUserId": "13460080", "handle": "nike", "fullName": "Nike", "verified": true, "avatarUrl": "https://example.com/avatar.jpg", "privateAccount": false }, "metrics": { "likes": 64418, "comments": 425, "playCount": null }, "media": { "mediaType": "image", "displayUrl": "https://example.com/display.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": null, "videoDurationSec": null, "dimensions": { "width": 1080, "height": 1350 }, "productType": null }, "downloads": [], "taggedUsers": [ { "handle": "sabrina_i" } ], "coauthors": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "post": { "id": "3672288292859749817", "shortcode": "DL2lr7ouyW5", "url": "https://www.instagram.com/p/DL2lr7ouyW5/", "caption": "Example caption.", "takenAt": 1751990900, "accessibilityCaption": null, "isAd": false, "isAffiliate": false, "isPaidPartnership": false }, "owner": { "platformUserId": "13460080", "handle": "nike", "fullName": "Nike", "verified": true, "avatarUrl": "https://example.com/avatar.jpg", "privateAccount": false }, "metrics": { "likes": 64418, "comments": 425, "playCount": null }, "media": { "mediaType": "image", "displayUrl": "https://example.com/display.jpg", "thumbnailUrl": "https://example.com/thumb.jpg", "videoUrl": null, "videoDurationSec": null, "dimensions": { "width": 1080, "height": 1350 }, "productType": null }, "downloads": [], "taggedUsers": [ { "handle": "sabrina_i" } ], "coauthors": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "post": null, "owner": null, "metrics": null, "media": null, "downloads": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "download_media": { "value": { "data": { "lookupStatus": "found", "post": { "id": "3672288292859749817", "shortcode": "DL2lr7ouyW5", "url": "https://www.instagram.com/p/DL2lr7ouyW5/", "caption": "Example caption.", "takenAt": 1751990900, "accessibilityCaption": null, "isAd": false, "isAffiliate": false, "isPaidPartnership": false }, "owner": { "handle": "nike", "verified": true, "privateAccount": false }, "metrics": { "likes": 64418, "comments": 425, "playCount": null }, "media": { "mediaType": "image", "displayUrl": "https://example.com/display.jpg" }, "downloads": [ { "postId": "DL2lr7ouyW5", "originalUrl": "https://cdn.instagram.com/original.jpg", "cdnUrl": "https://example.supabase.co/storage/v1/object/public/media_assets/instagram/DL2lr7ouyW5/3672288292859749817.jpg", "type": "image" } ] }, "meta": { "requestId": "req_01example_dl", "creditsCharged": 11, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/instagram/posts/comments": { "get": { "tags": ["Instagram"], "summary": "List Instagram post or reel comments", "description": "Lists top-level comments for a public Instagram post or reel URL with optional cursor-based pagination.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the Instagram post or reel whose comments should be listed." }, "required": true, "description": "Link to the Instagram post or reel whose comments should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque cursor from a previous response to fetch the next page." }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Comment listing result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the post or reel was resolved for this request." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable identifier for the comment." }, "text": { "type": "string", "description": "Comment text." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp when the comment was created." }, "likeCount": { "type": "integer", "minimum": 0, "description": "Like count on the comment." }, "replyCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Direct reply count for the comment thread when available; null when not reported." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Instagram username without a leading @." }, "platformUserId": { "type": "string", "description": "Numeric user id for the commenter when available." }, "verified": { "type": "boolean", "description": "Whether the commenter account is verified." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile image URL for the commenter when available." } }, "required": ["handle", "verified", "avatarUrl"], "description": "Comment author." } }, "required": [ "id", "text", "createdAt", "likeCount", "replyCount", "author" ], "description": "A single top-level comment on an Instagram post or reel." }, "description": "Top-level comments for the resolved media." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when more pages exist." }, "hasMore": { "type": "boolean", "description": "Whether another page of comments is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for this response." } }, "required": ["lookupStatus", "comments", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "comments": [ { "id": "18062038283402944", "text": "Example comment.", "createdAt": "2026-04-16T12:58:38.000Z", "likeCount": 0, "replyCount": null, "author": { "handle": "viewer1", "platformUserId": "69060028703", "verified": false, "avatarUrl": "https://example.com/avatar.jpg" } } ], "page": { "nextCursor": "next-page-cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "comments": [ { "id": "18062038283402944", "text": "Example comment.", "createdAt": "2026-04-16T12:58:38.000Z", "likeCount": 0, "replyCount": null, "author": { "handle": "viewer1", "platformUserId": "69060028703", "verified": false, "avatarUrl": "https://example.com/avatar.jpg" } } ], "page": { "nextCursor": "next-page-cursor", "hasMore": true } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "no_comments": { "value": { "data": { "lookupStatus": "found", "comments": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nc", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "comments": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/linkedin/profiles": { "get": { "tags": ["LinkedIn"], "summary": "Get LinkedIn profile", "description": "Looks up a LinkedIn public profile by URL. Availability is indicated in `data.lookupStatus` as `found` or `not_found`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "LinkedIn public profile URL for this lookup." }, "required": true, "description": "LinkedIn public profile URL for this lookup.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the profile was found or not found for this URL." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["linkedin"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "LinkedIn public profile handle without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name on the profile when available." }, "bio": { "type": "string", "nullable": true, "description": "Profile summary or about text when available." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar image URL when available." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public LinkedIn profile URL for this handle." }, "location": { "type": "string", "nullable": true, "description": "Location label when available." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "profileUrl", "location" ], "description": "Profile details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Follower count when available." } }, "required": ["followers"], "description": "Profile metrics when available." }, "recentPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable activity id for this post when available." }, "url": { "type": "string", "minLength": 1, "description": "Public URL for this activity or post." }, "title": { "type": "string", "nullable": true, "description": "Primary text or headline for the activity." }, "activityType": { "type": "string", "nullable": true, "description": "Activity label when available (for example Post or Repost)." }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp in ISO-8601 format when provided by the source." } }, "required": [ "id", "url", "title", "activityType", "publishedAt" ], "description": "A recent public activity item from the profile." }, "description": "Recent public activities from the profile when available." } }, "required": [ "lookupStatus", "profile", "metrics", "recentPosts" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "linkedin", "handle": "marclouvion", "displayName": "Marc Lou", "bio": "I built 25 startups in the last 3 years.", "avatarUrl": "https://example.com/avatar.jpg", "profileUrl": "https://www.linkedin.com/in/marclouvion/", "location": "Bali, Indonesia" }, "metrics": { "followers": 50377 }, "recentPosts": [ { "id": "7448025715234623509", "url": "https://www.linkedin.com/posts/marclouvion_example-activity-7448025715234623509-dST_", "title": "I overworked myself.\n\nFor the past 5 years…", "activityType": "Post", "publishedAt": "2026-04-09T15:15:08.115Z" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "linkedin", "handle": "marclouvion", "displayName": "Marc Lou", "bio": "I built 25 startups in the last 3 years.", "avatarUrl": "https://example.com/avatar.jpg", "profileUrl": "https://www.linkedin.com/in/marclouvion/", "location": "Bali, Indonesia" }, "metrics": { "followers": 50377 }, "recentPosts": [ { "id": "7448025715234623509", "url": "https://www.linkedin.com/posts/marclouvion_example-activity-7448025715234623509-dST_", "title": "I overworked myself.\n\nFor the past 5 years…", "activityType": "Post", "publishedAt": "2026-04-09T15:15:08.115Z" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_no_posts": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "linkedin", "handle": "fredrik-olsen-hauge", "displayName": "Fredrik Olsen Hauge", "bio": null, "avatarUrl": "https://example.com/avatar.jpg", "profileUrl": "https://www.linkedin.com/in/fredrik-olsen-hauge/", "location": "Bangkok, Bangkok City, Thailand" }, "metrics": { "followers": 91 }, "recentPosts": [] }, "meta": { "requestId": "req_01example_noposts", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "metrics": null, "recentPosts": [] }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid profile URL or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/linkedin/companies/posts": { "get": { "tags": ["LinkedIn"], "summary": "List LinkedIn company posts", "description": "Lists posts for a LinkedIn company page. Pass the public company page URL and optional `page` (1–7). Check `data.lookupStatus` for `found` vs `not_found`. Pagination is page-based; `data.page.hasMore` indicates whether another page can be requested.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public LinkedIn company page URL for the organization whose posts should be listed." }, "required": true, "description": "Public LinkedIn company page URL for the organization whose posts should be listed.", "name": "url", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 7, "description": "1-based results page number. Pagination is page-based; at most 7 pages can be requested for a given company." }, "required": false, "description": "1-based results page number. Pagination is page-based; at most 7 pages can be requested for a given company.", "name": "page", "in": "query" } ], "responses": { "200": { "description": "Company posts for the requested page. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the company page resolved for this request." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable activity identifier for the post." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this LinkedIn post." }, "text": { "type": "string", "nullable": true, "description": "Full text body of the post when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp for when the post was published, when available." } }, "required": ["id", "url", "text", "publishedAt"], "description": "A single LinkedIn post from a company feed page." }, "description": "Posts returned for the requested company page. This array may be empty when the page resolves but no posts are returned." }, "page": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 7, "description": "1-based page number for this response." }, "nextPage": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7, "description": "Next page number to request when `hasMore` is true; otherwise null." }, "hasMore": { "type": "boolean", "description": "Whether another page of posts can be requested." }, "maxPage": { "type": "number", "enum": [7], "description": "Maximum page number that can be requested for this listing." } }, "required": [ "currentPage", "nextPage", "hasMore", "maxPage" ], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "posts", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "posts": [ { "id": "7447536367661744128", "url": "https://www.linkedin.com/posts/knowit_example-activity-7447536367661744128-vhB8", "text": "Example post body.", "publishedAt": "2026-04-08T06:50:38.561Z" } ], "page": { "currentPage": 1, "nextPage": 2, "hasMore": true, "maxPage": 7 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "posts": [ { "id": "7447536367661744128", "url": "https://www.linkedin.com/posts/knowit_example-activity-7447536367661744128-vhB8", "text": "Example post body.", "publishedAt": "2026-04-08T06:50:38.561Z" } ], "page": { "currentPage": 1, "nextPage": 2, "hasMore": true, "maxPage": 7 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "lookupStatus": "found", "posts": [ { "id": "7421865816444309504", "url": "https://www.linkedin.com/posts/knowit_example-activity-7421865816444309504-4M9a", "text": "Another page of posts.", "publishedAt": "2026-02-20T06:47:55.395Z" } ], "page": { "currentPage": 2, "nextPage": 3, "hasMore": true, "maxPage": 7 } }, "meta": { "requestId": "req_01example_p2", "creditsCharged": 1, "version": "v1" } } }, "no_posts": { "value": { "data": { "lookupStatus": "found", "posts": [], "page": { "currentPage": 3, "nextPage": null, "hasMore": false, "maxPage": 7 } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "posts": [], "page": { "currentPage": 1, "nextPage": null, "hasMore": false, "maxPage": 7 } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid company URL, page, or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/linkedin/companies": { "get": { "tags": ["LinkedIn"], "summary": "Get LinkedIn company page", "description": "Looks up a LinkedIn company page by public URL. Availability is indicated in `data.lookupStatus` as `found` or `not_found`.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "LinkedIn company page URL for this lookup." }, "required": true, "description": "LinkedIn company page URL for this lookup.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the company page was found." }, "company": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["linkedin"], "description": "Social platform for this record." }, "id": { "type": "string", "minLength": 1, "description": "Company identifier as a string." }, "handle": { "type": "string", "minLength": 1, "description": "Company vanity handle when available." }, "name": { "type": "string", "minLength": 1, "description": "Company display name." }, "companyUrl": { "type": "string", "minLength": 1, "description": "Canonical public LinkedIn company page URL." }, "description": { "type": "string", "nullable": true, "description": "Company description text when available." }, "slogan": { "type": "string", "nullable": true, "description": "Company tagline when available." }, "website": { "type": "string", "nullable": true, "description": "Primary external website when available." }, "logoUrl": { "type": "string", "nullable": true, "description": "Company logo image URL when available." }, "coverImageUrl": { "type": "string", "nullable": true, "description": "Cover image URL when available." }, "industry": { "type": "string", "nullable": true, "description": "Industry label when available." }, "companyType": { "type": "string", "nullable": true, "description": "Company type label when available." }, "foundedYear": { "type": "integer", "nullable": true, "description": "Founded year when available." }, "headquarters": { "type": "string", "nullable": true, "description": "Headquarters label when available." }, "employeeRange": { "type": "string", "nullable": true, "description": "Reported employee range label when available." }, "specialties": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Specialty tags when available." }, "location": { "type": "object", "nullable": true, "properties": { "city": { "type": "string", "nullable": true, "description": "City label when available." }, "state": { "type": "string", "nullable": true, "description": "State or region label when available." }, "country": { "type": "string", "nullable": true, "description": "Country code or label when available." } }, "required": ["city", "state", "country"], "description": "Structured location when available." } }, "required": [ "platform", "id", "name", "companyUrl", "description", "website", "logoUrl", "coverImageUrl", "industry", "companyType", "headquarters", "employeeRange", "specialties", "location" ], "description": "Company details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Follower count for the company page." }, "employees": { "type": "integer", "minimum": 0, "description": "Reported employee count for the company." } }, "required": ["followers", "employees"], "description": "Company metrics when available." }, "similarCompanies": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Similar company display name." }, "companyUrl": { "type": "string", "minLength": 1, "description": "Public LinkedIn company page URL." }, "imageUrl": { "type": "string", "nullable": true, "description": "Logo image URL when available." } }, "required": ["name", "companyUrl", "imageUrl"], "description": "A similar LinkedIn company suggestion." }, "description": "Similar company suggestions when available." }, "featuredEmployees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Person name." }, "title": { "type": "string", "nullable": true, "description": "Title or headline shown on the company page." }, "profileUrl": { "type": "string", "minLength": 1, "description": "LinkedIn profile URL." }, "imageUrl": { "type": "string", "nullable": true, "description": "Profile image URL when available." } }, "required": [ "name", "title", "profileUrl", "imageUrl" ], "description": "A featured employee shown on the company page." }, "description": "Featured employees shown on the company page when available." }, "recentPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post identifier when available." }, "postUrl": { "type": "string", "minLength": 1, "description": "Public URL for the post." }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication time in ISO-8601 when available." }, "text": { "type": "string", "nullable": true, "description": "Post text when available." } }, "required": ["postUrl"], "description": "A recent post from the company page." }, "description": "Recent posts from the company page when available." }, "funding": { "type": "object", "nullable": true, "properties": { "numberOfRounds": { "type": "integer", "nullable": true, "minimum": 0, "description": "Reported number of funding rounds when available." }, "lastRound": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "description": "Funding round label when available." }, "date": { "type": "string", "nullable": true, "description": "Round date text or ISO string when available." }, "amount": { "type": "string", "nullable": true, "description": "Round amount label when available." } }, "required": ["type", "date", "amount"], "description": "Most recent funding round when available." }, "investors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Investor name." }, "crunchbaseUrl": { "type": "string", "nullable": true, "description": "Crunchbase organization URL when available." }, "imageUrl": { "type": "string", "nullable": true, "description": "Investor logo URL when available." } }, "required": [ "name", "crunchbaseUrl", "imageUrl" ], "description": "A funding investor associated with the company." }, "description": "Investors associated with funding history when available." } }, "required": [ "numberOfRounds", "lastRound", "investors" ], "description": "Funding summary when available." } }, "required": [ "lookupStatus", "company", "metrics", "similarCompanies", "featuredEmployees", "recentPosts", "funding" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "company": { "platform": "linkedin", "id": "8067", "handle": "knowit", "name": "Knowit", "companyUrl": "https://se.linkedin.com/company/knowit", "description": "Building the future takes digitalization skills.", "slogan": null, "website": "http://www.knowit.eu", "logoUrl": "https://example.com/logo.png", "coverImageUrl": "https://example.com/cover.png", "industry": "IT Services and IT Consulting", "companyType": "Public Company", "foundedYear": null, "headquarters": "Stockholm, Stockholm County", "employeeRange": "1,001-5,000 employees", "specialties": ["System Development", "Strategy"], "location": { "city": "Stockholm", "state": "Stockholm County", "country": "SE" } }, "metrics": { "followers": 91563, "employees": 3911 }, "similarCompanies": [ { "name": "Consid", "companyUrl": "https://se.linkedin.com/company/consid-ab", "imageUrl": "https://example.com/c.png" } ], "featuredEmployees": [ { "name": "Niina Sauvolainen", "title": "Knowit•2K followers", "profileUrl": "https://fi.linkedin.com/in/niinasauvolainen", "imageUrl": "https://example.com/p.png" } ], "recentPosts": [ { "id": "7447536367661744128", "postUrl": "https://www.linkedin.com/posts/knowit_proudly-sharing-that-knowit-is-approved-as-activity-7447536367661744128-vhB8", "publishedAt": "2026-04-08T06:50:38.561Z", "text": "Proudly sharing that Knowit is approved..." } ], "funding": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "company": { "platform": "linkedin", "id": "8067", "handle": "knowit", "name": "Knowit", "companyUrl": "https://se.linkedin.com/company/knowit", "description": "Building the future takes digitalization skills.", "slogan": null, "website": "http://www.knowit.eu", "logoUrl": "https://example.com/logo.png", "coverImageUrl": "https://example.com/cover.png", "industry": "IT Services and IT Consulting", "companyType": "Public Company", "foundedYear": null, "headquarters": "Stockholm, Stockholm County", "employeeRange": "1,001-5,000 employees", "specialties": ["System Development", "Strategy"], "location": { "city": "Stockholm", "state": "Stockholm County", "country": "SE" } }, "metrics": { "followers": 91563, "employees": 3911 }, "similarCompanies": [ { "name": "Consid", "companyUrl": "https://se.linkedin.com/company/consid-ab", "imageUrl": "https://example.com/c.png" } ], "featuredEmployees": [ { "name": "Niina Sauvolainen", "title": "Knowit•2K followers", "profileUrl": "https://fi.linkedin.com/in/niinasauvolainen", "imageUrl": "https://example.com/p.png" } ], "recentPosts": [ { "id": "7447536367661744128", "postUrl": "https://www.linkedin.com/posts/knowit_proudly-sharing-that-knowit-is-approved-as-activity-7447536367661744128-vhB8", "publishedAt": "2026-04-08T06:50:38.561Z", "text": "Proudly sharing that Knowit is approved..." } ], "funding": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "company": null, "metrics": null, "similarCompanies": [], "featuredEmployees": [], "recentPosts": [], "funding": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid company URL or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/linkedin/posts": { "get": { "tags": ["LinkedIn"], "summary": "Get LinkedIn post or article", "description": "Returns public metadata for a single LinkedIn feed post or article. Availability is indicated in `data.lookupStatus` as `found` or `not_found`.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Public permalink to the post or article." }, "required": true, "description": "Public permalink to the post or article.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Post or article metadata (found or not found in body).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the URL could be resolved to public content." }, "post": { "type": "object", "nullable": true, "properties": { "contentType": { "type": "string", "enum": ["post", "article"], "description": "Whether this URL resolved to a feed-style post or an article." }, "url": { "type": "string", "minLength": 1, "description": "Canonical or resolved public URL for this item." }, "title": { "type": "string", "nullable": true, "description": "Title for long-form articles when available." }, "headline": { "type": "string", "nullable": true, "description": "Subtitle or lead line when available." }, "description": { "type": "string", "nullable": true, "description": "Full body text when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "Publication timestamp or date string when available." } }, "required": [ "contentType", "url", "title", "headline", "description", "publishedAt" ], "description": "Primary item when found." }, "author": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name of the author." }, "profileUrl": { "type": "string", "nullable": true, "format": "uri", "description": "Public profile URL for the author when available." }, "avatarUrl": { "type": "string", "nullable": true, "format": "uri", "description": "Avatar image URL when available." }, "followers": { "type": "integer", "nullable": true, "minimum": 0, "description": "Follower count when available." } }, "required": [ "name", "profileUrl", "avatarUrl", "followers" ], "description": "Author when found." }, "metrics": { "type": "object", "nullable": true, "properties": { "reactions": { "type": "integer", "nullable": true, "minimum": 0, "description": "Total reactions when available." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count when available." } }, "required": ["reactions", "comments"], "description": "Engagement metrics for the post or article." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "authorName": { "type": "string", "nullable": true, "description": "Display name of the commenter." }, "text": { "type": "string", "nullable": true, "description": "Comment body text." }, "profileUrl": { "type": "string", "nullable": true, "format": "uri", "description": "Public profile URL for the commenter when available." } }, "required": ["authorName", "text", "profileUrl"], "description": "A single top-level comment." }, "description": "Top-level comments when available." }, "relatedArticles": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Permalink to the related item." }, "title": { "type": "string", "nullable": true, "description": "Title when available." }, "publishedAtLabel": { "type": "string", "nullable": true, "description": "Human-readable publication label when only a label is available." }, "description": { "type": "string", "nullable": true, "description": "Short summary text when available." }, "reactions": { "type": "integer", "nullable": true, "minimum": 0, "description": "Reaction count when available." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count when available." } }, "required": [ "url", "title", "publishedAtLabel", "description", "reactions", "comments" ], "description": "A related article from the same author." }, "description": "Related items from the same author when available." } }, "required": [ "lookupStatus", "post", "author", "metrics", "comments", "relatedArticles" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "post": { "contentType": "post", "url": "https://www.linkedin.com/posts/marclouvion_example-activity-123", "title": null, "headline": null, "description": "Example post body text.", "publishedAt": "2026-03-31T13:22:13.483Z" }, "author": { "name": "Marc Lou", "profileUrl": "https://www.linkedin.com/in/marclouvion", "avatarUrl": "https://media.licdn.com/dms/image/v2/example", "followers": 50377 }, "metrics": { "reactions": 207, "comments": 14 }, "comments": [ { "authorName": "Example User", "text": "Great share.", "profileUrl": "https://www.linkedin.com/in/example" } ], "relatedArticles": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found_post": { "value": { "data": { "lookupStatus": "found", "post": { "contentType": "post", "url": "https://www.linkedin.com/posts/marclouvion_example-activity-123", "title": null, "headline": null, "description": "Example post body text.", "publishedAt": "2026-03-31T13:22:13.483Z" }, "author": { "name": "Marc Lou", "profileUrl": "https://www.linkedin.com/in/marclouvion", "avatarUrl": "https://media.licdn.com/dms/image/v2/example", "followers": 50377 }, "metrics": { "reactions": 207, "comments": 14 }, "comments": [ { "authorName": "Example User", "text": "Great share.", "profileUrl": "https://www.linkedin.com/in/example" } ], "relatedArticles": [] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_article": { "value": { "data": { "lookupStatus": "found", "post": { "contentType": "article", "url": "https://www.linkedin.com/pulse/example-article-slug", "title": "Student Assessment in an A.I. era: My way of thinking", "headline": "I was in an on-line meeting with few colleagues the other day.", "description": "Example article body excerpt.", "publishedAt": "2026-03-29T07:37:07.000+00:00" }, "author": { "name": "Professor Nik Bessis", "profileUrl": "https://www.linkedin.com/in/nikbessis", "avatarUrl": null, "followers": 5300 }, "metrics": { "reactions": 26, "comments": 5 }, "comments": [ { "authorName": "Example Reader", "text": "Insightful thoughts.", "profileUrl": "https://www.linkedin.com/in/example-reader" } ], "relatedArticles": [ { "url": "https://www.linkedin.com/pulse/related-example", "title": "Related article title", "publishedAtLabel": "Dec 1, 2020", "description": "Short teaser text.", "reactions": 23, "comments": 15 } ] }, "meta": { "requestId": "req_01example_article", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "post": null, "author": null, "metrics": null, "comments": [], "relatedArticles": [] }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/youtube/channel": { "get": { "tags": ["YouTube"], "summary": "Get YouTube channel", "description": "Looks up a YouTube channel by `channelId`, `handle`, or full `url`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional YouTube channel id for the request." }, "required": false, "description": "Optional YouTube channel id for the request.", "name": "channelId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optional YouTube channel handle for the request." }, "required": false, "description": "Optional YouTube channel handle for the request.", "name": "handle", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional YouTube channel URL for the request." }, "required": false, "description": "Optional YouTube channel URL for the request.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found` or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the channel was found or not found." }, "channel": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["youtube"], "description": "Social platform for this channel." }, "handle": { "type": "string", "description": "YouTube channel handle without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name for the YouTube channel." }, "bio": { "type": "string", "nullable": true, "description": "Channel description text when available." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar image URL." }, "bannerUrl": { "type": "string", "nullable": true, "description": "Channel banner image URL when available." }, "verified": { "type": "boolean", "description": "Whether the channel is marked as verified." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public YouTube channel URL." }, "platformUserId": { "type": "string", "description": "YouTube channel id (stable identifier for the channel)." }, "country": { "type": "string", "nullable": true, "description": "Country label when available." }, "joinedDateText": { "type": "string", "nullable": true, "description": "Human-readable join date text from YouTube when available (not guaranteed to parse to a calendar date)." }, "externalLinks": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Deduplicated outbound links associated with the channel when available." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "bannerUrl", "verified", "profileUrl" ], "description": "Channel details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "subscribers": { "type": "integer", "nullable": true, "minimum": 0, "description": "Subscriber count for the channel when available." }, "videos": { "type": "integer", "nullable": true, "minimum": 0, "description": "Public video count for the channel when available." }, "views": { "type": "integer", "nullable": true, "minimum": 0, "description": "Total view count reported for the channel when available." } }, "required": ["subscribers", "videos", "views"], "description": "Channel metrics when available." } }, "required": ["lookupStatus", "channel", "metrics"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "channel": { "platform": "youtube", "handle": "MrBeast", "displayName": "MrBeast", "bio": "SUBSCRIBE FOR A COOKIE!", "avatarUrl": "https://example.com/avatar.jpg", "bannerUrl": "https://example.com/banner.jpg", "verified": true, "profileUrl": "https://www.youtube.com/@MrBeast", "platformUserId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "country": "United States", "joinedDateText": "Joined Feb 19, 2012", "externalLinks": [ "https://instagram.com/mrbeast", "https://twitter.com/MrBeast" ] }, "metrics": { "subscribers": 478000000, "videos": 965, "views": 118106094339 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "channel": { "platform": "youtube", "handle": "MrBeast", "displayName": "MrBeast", "bio": "SUBSCRIBE FOR A COOKIE!", "avatarUrl": "https://example.com/avatar.jpg", "bannerUrl": "https://example.com/banner.jpg", "verified": true, "profileUrl": "https://www.youtube.com/@MrBeast", "platformUserId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "country": "United States", "joinedDateText": "Joined Feb 19, 2012", "externalLinks": [ "https://instagram.com/mrbeast", "https://twitter.com/MrBeast" ] }, "metrics": { "subscribers": 478000000, "videos": 965, "views": 118106094339 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "channel": null, "metrics": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/youtube/channels/videos": { "get": { "tags": ["YouTube"], "summary": "List YouTube channel videos", "description": "Lists videos for a YouTube channel. Pass `channelId` or `handle` to identify the channel. Optional query `sortBy` controls ordering, `cursor` continues from `data.page.nextCursor`, and `includeExtras=true` may add richer per-video metadata when available. An empty `data.videos` array can still accompany `data.lookupStatus: \"found\"` when the channel resolves but no videos are returned for the current page.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.videos` array can still mean `data.lookupStatus: \"found\"` when the channel resolves but the returned page has no videos.", "disambiguation": "Use `data.lookupStatus` to distinguish a resolved empty result from `not_found`." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional YouTube channel id for the request." }, "required": false, "description": "Optional YouTube channel id for the request.", "name": "channelId", "in": "query" }, { "schema": { "type": "string", "description": "Optional YouTube channel handle for the request." }, "required": false, "description": "Optional YouTube channel handle for the request.", "name": "handle", "in": "query" }, { "schema": { "type": "string", "enum": ["latest", "popular"], "description": "Optional sort order for the returned YouTube videos." }, "required": false, "description": "Optional sort order for the returned YouTube videos.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor returned by a previous response." }, "required": false, "description": "Opaque pagination cursor returned by a previous response.", "name": "cursor", "in": "query" }, { "schema": { "type": "boolean", "description": "Optional flag to include richer per-video metadata when available." }, "required": false, "description": "Optional flag to include richer per-video metadata when available.", "name": "includeExtras", "in": "query" } ], "responses": { "200": { "description": "YouTube videos for the requested channel. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the channel was resolved for this request." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube video identifier." }, "url": { "type": "string", "nullable": true, "description": "Canonical public YouTube URL for the video." }, "title": { "type": "string", "nullable": true, "description": "Title shown for the YouTube video." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Best available thumbnail image URL for the video." }, "viewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count for the video when available." }, "viewCountText": { "type": "string", "nullable": true, "description": "Human-readable view count label when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp for when the video was published, when available." }, "publishedTimeText": { "type": "string", "nullable": true, "description": "Human-readable relative publish time text when available." }, "durationSeconds": { "type": "integer", "nullable": true, "minimum": 0, "description": "Duration of the video in seconds when available." }, "durationText": { "type": "string", "nullable": true, "description": "Human-readable duration label for the video when available." }, "channelTitle": { "type": "string", "nullable": true, "description": "Channel title shown alongside the video when available." }, "channelThumbnailUrl": { "type": "string", "nullable": true, "description": "Channel thumbnail image URL shown alongside the video when available." }, "description": { "type": "string", "nullable": true, "description": "Video description text when available." }, "commentCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count for the video when available." }, "commentCountText": { "type": "string", "nullable": true, "description": "Human-readable comment count label when available." }, "likeCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count for the video when available." }, "likeCountText": { "type": "string", "nullable": true, "description": "Human-readable like count label when available." }, "publishDate": { "type": "string", "nullable": true, "description": "Publish date text when available." }, "genre": { "type": "string", "nullable": true, "description": "Video category or genre label when available." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Duration of the video in milliseconds when available." }, "durationFormatted": { "type": "string", "nullable": true, "description": "Alternative formatted duration label when available." } }, "required": [ "id", "url", "title", "thumbnailUrl", "viewCount", "viewCountText", "publishedAt", "publishedTimeText", "durationSeconds", "durationText", "channelTitle", "channelThumbnailUrl" ], "description": "A single YouTube video in the channel videos feed." }, "description": "YouTube videos returned for the resolved channel. This array may be empty when the channel resolves but there are no videos in the returned page." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when another page exists." }, "hasMore": { "type": "boolean", "description": "Whether another page of videos is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "videos", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "videos": [ { "id": "ehPHNMQEO5M", "url": "https://www.youtube.com/watch?v=ehPHNMQEO5M", "title": "Can HEAT transform your running FITNESS? (Copenhagen Calling Ep.5)", "thumbnailUrl": "https://i.ytimg.com/vi/ehPHNMQEO5M/hqdefault.jpg", "viewCount": 617, "viewCountText": "617 views", "publishedAt": "2026-04-12T15:07:20.873Z", "publishedTimeText": "6 days ago", "durationSeconds": 795, "durationText": "13:15", "channelTitle": null, "channelThumbnailUrl": null } ], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "videos": [ { "id": "ehPHNMQEO5M", "url": "https://www.youtube.com/watch?v=ehPHNMQEO5M", "title": "Can HEAT transform your running FITNESS? (Copenhagen Calling Ep.5)", "thumbnailUrl": "https://i.ytimg.com/vi/ehPHNMQEO5M/hqdefault.jpg", "viewCount": 617, "viewCountText": "617 views", "publishedAt": "2026-04-12T15:07:20.873Z", "publishedTimeText": "6 days ago", "durationSeconds": 795, "durationText": "13:15", "channelTitle": null, "channelThumbnailUrl": null } ], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "lookupStatus": "found", "videos": [ { "id": "sF5LYGgKbUA", "url": "https://www.youtube.com/watch?v=sF5LYGgKbUA", "title": "Every Minute One Person Is Eliminated", "thumbnailUrl": "https://i.ytimg.com/vi/sF5LYGgKbUA/hqdefault.jpg", "viewCount": 166182287, "viewCountText": "166,182,287 views", "publishedAt": "2025-04-18T15:08:58.344Z", "publishedTimeText": "1 year ago", "durationSeconds": 2086, "durationText": "34:46", "channelTitle": null, "channelThumbnailUrl": null } ], "page": { "nextCursor": "opaque_next_cursor", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "no_videos": { "value": { "data": { "lookupStatus": "found", "videos": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "videos": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/youtube/channels/shorts": { "get": { "tags": ["YouTube"], "summary": "List YouTube channel Shorts", "description": "Lists Shorts for a YouTube channel. Pass `channelId` or `handle` to identify the channel. Optional query `sortBy` controls ordering, and `cursor` continues from `data.page.nextCursor`. An empty `data.shorts` array can still accompany `data.lookupStatus: \"found\"` when the channel resolves but no Shorts are returned for the current page.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.shorts` array can still mean `data.lookupStatus: \"found\"` when the channel resolves but the returned page has no Shorts.", "disambiguation": "Use `data.lookupStatus` to distinguish a resolved empty result from `not_found`." }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Optional YouTube channel id for the request." }, "required": false, "description": "Optional YouTube channel id for the request.", "name": "channelId", "in": "query" }, { "schema": { "type": "string", "description": "Optional YouTube channel handle for the request." }, "required": false, "description": "Optional YouTube channel handle for the request.", "name": "handle", "in": "query" }, { "schema": { "type": "string", "enum": ["latest", "popular"], "description": "Optional sort order for the returned YouTube Shorts." }, "required": false, "description": "Optional sort order for the returned YouTube Shorts.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor returned by a previous response." }, "required": false, "description": "Opaque pagination cursor returned by a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "YouTube Shorts for the requested channel. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the channel was resolved for this request." }, "shorts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube Short identifier." }, "url": { "type": "string", "nullable": true, "description": "Canonical public YouTube URL for the Short." }, "title": { "type": "string", "nullable": true, "description": "Title shown for the Short." }, "description": { "type": "string", "nullable": true, "description": "Short description text when available." }, "viewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count for the Short when available." }, "viewCountText": { "type": "string", "nullable": true, "description": "Human-readable view count label when available." }, "commentCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count for the Short when available." }, "commentCountText": { "type": "string", "nullable": true, "description": "Human-readable comment count label when available." }, "likeCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count for the Short when available." }, "likeCountText": { "type": "string", "nullable": true, "description": "Human-readable like count label when available." }, "publishDate": { "type": "string", "nullable": true, "description": "Publication timestamp label when available." }, "genre": { "type": "string", "nullable": true, "description": "Category or genre label when available." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Duration of the Short in milliseconds when available." }, "durationFormatted": { "type": "string", "nullable": true, "description": "Formatted duration label when available." } }, "required": [ "id", "url", "title", "description", "viewCount", "viewCountText" ], "description": "A single YouTube Short in the channel Shorts feed." }, "description": "YouTube Shorts returned for the resolved channel. This array may be empty when the channel resolves but there are no Shorts in the returned page." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass in the next request when another page exists." }, "hasMore": { "type": "boolean", "description": "Whether another page of Shorts is available." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["lookupStatus", "shorts", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "shorts": [ { "id": "mFWpUx3FiyU", "url": "https://www.youtube.com/watch?v=mFWpUx3FiyU", "title": "Guess The Animal", "description": "American Humane Society monitored the animal action. No animals were harmed® (AH 14171)", "viewCount": 47801268, "viewCountText": "47,801,268", "commentCount": 5900, "commentCountText": "5.9K", "likeCount": 756483, "likeCountText": "756483", "publishDate": "2026-04-17T09:00:01-07:00", "genre": "Entertainment", "durationMs": 45000, "durationFormatted": "00:00:45" } ], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "shorts": [ { "id": "mFWpUx3FiyU", "url": "https://www.youtube.com/watch?v=mFWpUx3FiyU", "title": "Guess The Animal", "description": "American Humane Society monitored the animal action. No animals were harmed® (AH 14171)", "viewCount": 47801268, "viewCountText": "47,801,268", "commentCount": 5900, "commentCountText": "5.9K", "likeCount": 756483, "likeCountText": "756483", "publishDate": "2026-04-17T09:00:01-07:00", "genre": "Entertainment", "durationMs": 45000, "durationFormatted": "00:00:45" } ], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "paginated": { "value": { "data": { "lookupStatus": "found", "shorts": [ { "id": "NfhuGUyWYfQ", "url": "https://www.youtube.com/watch?v=NfhuGUyWYfQ", "title": "Would Your Grandma Go Skydiving?", "description": null, "viewCount": 93855107, "viewCountText": "93,855,107", "commentCount": 9100, "commentCountText": "9.1K", "likeCount": 2544417, "likeCountText": "2544417", "publishDate": "2025-09-26T11:00:07-07:00", "genre": "Entertainment", "durationMs": 42000, "durationFormatted": "00:00:42" } ], "page": { "nextCursor": "opaque_second_page_cursor", "hasMore": true } }, "meta": { "requestId": "req_01example_page_2", "creditsCharged": 1, "version": "v1" } } }, "no_shorts": { "value": { "data": { "lookupStatus": "found", "shorts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "shorts": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/youtube/videos": { "get": { "tags": ["YouTube"], "summary": "Get YouTube video", "description": "Returns public metadata for a single YouTube video. This endpoint also supports YouTube Shorts URLs.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the YouTube video. Shorts URLs are also supported." }, "required": true, "description": "Link to the YouTube video. Shorts URLs are also supported.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 16, "description": "Optional preferred language for returned text when the source supports localization." }, "required": false, "description": "Optional preferred language for returned text when the source supports localization.", "name": "language", "in": "query" } ], "responses": { "200": { "description": "YouTube video metadata. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the video was resolved for this request." }, "video": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube video identifier." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public YouTube URL." }, "title": { "type": "string", "description": "Video title." }, "description": { "type": "string", "nullable": true, "description": "Video description text when available." }, "descriptionLinks": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "URLs extracted from the description when available." }, "thumbnailUrl": { "type": "string", "minLength": 1, "description": "Best available thumbnail image URL." }, "publishedAt": { "type": "string", "nullable": true, "description": "Publish timestamp when available." }, "publishDateText": { "type": "string", "nullable": true, "description": "Human-readable publish date label when available." }, "durationMs": { "type": "integer", "nullable": true, "minimum": 0, "description": "Video duration in milliseconds when available." }, "durationFormatted": { "type": "string", "nullable": true, "description": "Human-readable duration label when available." }, "genre": { "type": "string", "nullable": true, "description": "Category or genre label when available." }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Keyword tags associated with the video when available." }, "isPaidPromotion": { "type": "boolean", "description": "Whether the video is marked as paid promotion." } }, "required": [ "id", "url", "title", "description", "descriptionLinks", "thumbnailUrl", "publishedAt", "publishDateText", "durationMs", "durationFormatted", "genre", "keywords", "isPaidPromotion" ], "description": "Video details when found." }, "channel": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["youtube"], "description": "Social platform for this channel." }, "handle": { "type": "string", "minLength": 1, "description": "YouTube channel handle without a leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Public display name for the YouTube channel." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public YouTube channel URL." }, "platformUserId": { "type": "string", "description": "YouTube channel id when available." } }, "required": [ "platform", "handle", "displayName", "profileUrl" ], "description": "Uploader channel when found." }, "metrics": { "type": "object", "nullable": true, "properties": { "views": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count when available." }, "likes": { "type": "integer", "nullable": true, "minimum": 0, "description": "Like count when available." }, "comments": { "type": "integer", "nullable": true, "minimum": 0, "description": "Comment count when available." } }, "required": ["views", "likes", "comments"], "description": "Engagement metrics when found." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Chapter title." }, "startTimeText": { "type": "string", "nullable": true, "description": "Human-readable chapter start time when available." }, "startTimeSeconds": { "type": "number", "minimum": 0, "description": "Chapter start offset in seconds." } }, "required": [ "title", "startTimeText", "startTimeSeconds" ], "description": "A chapter marker in the video timeline." }, "description": "Chapter markers when available." }, "captions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Caption track label." }, "languageCode": { "type": "string", "description": "BCP-47 style language code when available." }, "kind": { "type": "string", "nullable": true, "description": "Caption kind when available." }, "isTranslatable": { "type": "boolean", "description": "Whether the track can be translated in the player." } }, "required": [ "label", "languageCode", "kind", "isTranslatable" ], "description": "A caption or subtitle track available for the video." }, "description": "Caption and subtitle tracks when available." }, "relatedVideos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Related video id." }, "url": { "type": "string", "nullable": true, "description": "Canonical watch URL when available." }, "title": { "type": "string", "description": "Related video title." }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Thumbnail image URL when available." }, "publishedAt": { "type": "string", "nullable": true, "description": "Resolved publish timestamp when available." }, "publishedTimeText": { "type": "string", "nullable": true, "description": "Human-readable relative publish time when available." }, "viewCount": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count when available." }, "viewCountText": { "type": "string", "nullable": true, "description": "Human-readable view count when available." }, "durationSeconds": { "type": "integer", "nullable": true, "minimum": 0, "description": "Duration in seconds when available." }, "durationText": { "type": "string", "nullable": true, "description": "Human-readable duration label when available." }, "channel": { "type": "object", "nullable": true, "properties": { "displayName": { "type": "string", "nullable": true, "description": "Related video channel title when available." }, "handle": { "type": "string", "nullable": true, "description": "Related video channel handle when available." }, "profileUrl": { "type": "string", "nullable": true, "description": "Related video channel URL when available." }, "platformUserId": { "type": "string", "description": "Related video channel id when available." } }, "required": [ "displayName", "handle", "profileUrl" ], "description": "Uploader channel summary when available." } }, "required": [ "id", "url", "title", "thumbnailUrl", "publishedAt", "publishedTimeText", "viewCount", "viewCountText", "durationSeconds", "durationText", "channel" ], "description": "A related or recommended video entry." }, "description": "Related videos suggested after playback when available." } }, "required": [ "lookupStatus", "video", "channel", "metrics", "chapters", "captions", "relatedVideos" ], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "video": { "id": "Y2Ah_DFr8cw", "url": "https://www.youtube.com/watch?v=Y2Ah_DFr8cw", "title": "Example video", "description": "Description text.", "descriptionLinks": [], "thumbnailUrl": "https://img.youtube.com/vi/Y2Ah_DFr8cw/maxresdefault.jpg", "publishedAt": "2019-02-22T03:19:54-08:00", "publishDateText": "Feb 22, 2019", "durationMs": 348000, "durationFormatted": "00:05:48", "genre": "People & Blogs", "keywords": ["example"], "isPaidPromotion": false }, "channel": { "platform": "youtube", "handle": "afroballer8906", "displayName": "Afroballer", "profileUrl": "https://www.youtube.com/@afroballer8906", "platformUserId": "UCWH3hing1Qb4LnkRfQdxsxQ" }, "metrics": { "views": 372864, "likes": 4043, "comments": 358 }, "chapters": [], "captions": [ { "label": "English (auto-generated)", "languageCode": "en", "kind": "asr", "isTranslatable": true } ], "relatedVideos": [ { "id": "lzDTK5kEdkM", "url": "https://www.youtube.com/watch?v=lzDTK5kEdkM", "title": "Charles Barkley and Shaq FUNNIEST MOMENTS", "thumbnailUrl": "https://i.ytimg.com/vi/lzDTK5kEdkM/hqdefault.jpg", "publishedAt": "2025-02-16T19:25:39.493Z", "publishedTimeText": "11 months ago", "viewCount": 1800000, "viewCountText": "1.8M views", "durationSeconds": 1081, "durationText": "18:01", "channel": { "displayName": "SkyHooked", "handle": "SkyHooked", "profileUrl": "https://www.youtube.com/@SkyHooked", "platformUserId": "UCrX8GD5f_O-Cu5Y2vQuSSvw" } } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "video": { "id": "Y2Ah_DFr8cw", "url": "https://www.youtube.com/watch?v=Y2Ah_DFr8cw", "title": "Example video", "description": "Description text.", "descriptionLinks": [], "thumbnailUrl": "https://img.youtube.com/vi/Y2Ah_DFr8cw/maxresdefault.jpg", "publishedAt": "2019-02-22T03:19:54-08:00", "publishDateText": "Feb 22, 2019", "durationMs": 348000, "durationFormatted": "00:05:48", "genre": "People & Blogs", "keywords": ["example"], "isPaidPromotion": false }, "channel": { "platform": "youtube", "handle": "afroballer8906", "displayName": "Afroballer", "profileUrl": "https://www.youtube.com/@afroballer8906", "platformUserId": "UCWH3hing1Qb4LnkRfQdxsxQ" }, "metrics": { "views": 372864, "likes": 4043, "comments": 358 }, "chapters": [], "captions": [ { "label": "English (auto-generated)", "languageCode": "en", "kind": "asr", "isTranslatable": true } ], "relatedVideos": [ { "id": "lzDTK5kEdkM", "url": "https://www.youtube.com/watch?v=lzDTK5kEdkM", "title": "Charles Barkley and Shaq FUNNIEST MOMENTS", "thumbnailUrl": "https://i.ytimg.com/vi/lzDTK5kEdkM/hqdefault.jpg", "publishedAt": "2025-02-16T19:25:39.493Z", "publishedTimeText": "11 months ago", "viewCount": 1800000, "viewCountText": "1.8M views", "durationSeconds": 1081, "durationText": "18:01", "channel": { "displayName": "SkyHooked", "handle": "SkyHooked", "profileUrl": "https://www.youtube.com/@SkyHooked", "platformUserId": "UCrX8GD5f_O-Cu5Y2vQuSSvw" } } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "short": { "value": { "data": { "lookupStatus": "found", "video": { "id": "QLu_ZsRc_G0", "url": "https://www.youtube.com/watch?v=QLu_ZsRc_G0", "title": "Covering 10 points, a surprisingly tricky puzzle.", "description": "Made as part of a monthly series of puzzles for the 2026 Year of Math.", "descriptionLinks": [], "thumbnailUrl": "https://img.youtube.com/vi/QLu_ZsRc_G0/maxresdefault.jpg", "publishedAt": "2026-04-16T09:08:21-07:00", "publishDateText": "Apr 16, 2026", "durationMs": 39000, "durationFormatted": "00:00:39", "genre": "Education", "keywords": ["Mathematics"], "isPaidPromotion": false }, "channel": { "platform": "youtube", "handle": "3blue1brown", "displayName": "3Blue1Brown", "profileUrl": "https://www.youtube.com/@3blue1brown", "platformUserId": "UCYO_jab_esuFRV4b17AJtAw" }, "metrics": { "views": 575269, "likes": 14359, "comments": 1300 }, "chapters": [], "captions": [ { "label": "English (auto-generated)", "languageCode": "en", "kind": "asr", "isTranslatable": true } ], "relatedVideos": [] }, "meta": { "requestId": "req_01example_short", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "video": null, "channel": null, "metrics": null, "chapters": [], "captions": [], "relatedVideos": [] }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid query or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/youtube/videos/transcript": { "get": { "tags": ["YouTube"], "summary": "Get YouTube video transcript", "description": "Returns structured captions for a YouTube video when available. Pass `url` as a standard watch link (or equivalent). Optional `language` requests a preferred caption language when multiple tracks exist.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Link to the YouTube video whose transcript should be returned." }, "required": true, "description": "Link to the YouTube video whose transcript should be returned.", "name": "url", "in": "query" }, { "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Optional ISO 639-1 language code (two letters) to prefer when multiple transcripts exist." }, "required": false, "description": "Optional ISO 639-1 language code (two letters) to prefer when multiple transcripts exist.", "name": "language", "in": "query" } ], "responses": { "200": { "description": "Transcript lookup result. Inspect `data.lookupStatus` for found, not found, or lookup_failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found", "lookup_failed"], "description": "Outcome of the transcript lookup: resolved video, not found, or lookup could not be completed." }, "video": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube video id." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for the video." } }, "required": ["id", "url"], "description": "Video identity when the lookup resolved." }, "transcript": { "type": "object", "nullable": true, "properties": { "segments": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Transcript segment text." }, "startMs": { "type": "integer", "minimum": 0, "description": "Segment start offset in milliseconds." }, "endMs": { "type": "integer", "minimum": 0, "description": "Segment end offset in milliseconds." } }, "required": ["text", "startMs", "endMs"], "description": "One timed transcript segment." }, "description": "Timed transcript segments." }, "plainText": { "type": "string", "description": "Full transcript text, typically derived from captions." }, "language": { "type": "string", "description": "Human-readable transcript language label when reported by the lookup." } }, "required": ["segments", "plainText", "language"], "description": "Transcript content when available for the resolved video." } }, "required": ["lookupStatus", "video", "transcript"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "video": { "id": "ByGJQzlzxQg", "url": "https://www.youtube.com/watch?v=ByGJQzlzxQg" }, "transcript": { "segments": [ { "text": "Example segment.", "startMs": 0, "endMs": 5940 } ], "plainText": "Example segment.", "language": "English" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "video": { "id": "ByGJQzlzxQg", "url": "https://www.youtube.com/watch?v=ByGJQzlzxQg" }, "transcript": { "segments": [ { "text": "Example segment.", "startMs": 0, "endMs": 5940 } ], "plainText": "Example segment.", "language": "English" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "video": null, "transcript": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } }, "no_transcript": { "value": { "data": { "lookupStatus": "found", "video": { "id": "1JPwiLeo4WY", "url": "https://www.youtube.com/watch?v=1JPwiLeo4WY" }, "transcript": null }, "meta": { "requestId": "req_01example_null", "creditsCharged": 1, "version": "v1" } } }, "lookup_failed": { "value": { "data": { "lookupStatus": "lookup_failed", "video": null, "transcript": null }, "meta": { "requestId": "req_01example_lf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/profiles/{handle}": { "get": { "tags": ["Twitter"], "summary": "Get Twitter profile", "description": "Looks up an X profile by handle.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "X handle to look up, with or without a leading @." }, "required": true, "description": "X handle to look up, with or without a leading @.", "name": "handle", "in": "path" } ], "responses": { "200": { "description": "Lookup result. Check `data.lookupStatus` for `found`, `private`, or `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "private", "not_found"], "description": "Whether the profile was found, private, or not found." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["twitter"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "X screen name (handle) without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Display name shown on the profile." }, "bio": { "type": "string", "nullable": true, "description": "Profile biography text." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar image URL." }, "bannerUrl": { "type": "string", "nullable": true, "description": "Profile banner image URL when available." }, "verified": { "type": "boolean", "description": "Whether X marks the profile with legacy verification (not necessarily paid blue)." }, "blueVerified": { "type": "boolean", "description": "Whether the account has X blue (paid) verification." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public profile URL on x.com." }, "privateAccount": { "type": "boolean", "description": "Whether the account is protected (private)." }, "platformUserId": { "type": "string", "description": "Numeric X user id (`rest_id`) as a string." }, "accountCreatedAt": { "type": "integer", "minimum": 0, "description": "Account creation time as Unix epoch seconds when derivable." }, "location": { "type": "string", "nullable": true, "description": "Location string from the profile when provided." }, "website": { "type": "string", "nullable": true, "description": "Primary outbound link (expanded URL) from the profile." }, "pinnedTweetId": { "type": "string", "description": "Pinned tweet id when X exposes one." }, "verificationInfo": { "type": "object", "properties": { "isIdentityVerified": { "type": "boolean", "description": "Whether X marks the account as identity-verified." }, "verifiedSinceMsec": { "type": "string", "description": "When verification became effective, as milliseconds since epoch (string from X)." }, "reason": { "type": "object", "properties": { "text": { "type": "string", "description": "Human-readable verification reason text from X." }, "entities": { "type": "array", "items": { "nullable": true }, "description": "Inline entity metadata for the reason text (vendor-defined)." } }, "description": "Verification reason payload when X provides it." } }, "required": ["isIdentityVerified"], "description": "Structured verification metadata from X." }, "tipJar": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "description": "Whether the X tip jar is enabled." }, "handles": { "type": "object", "properties": { "bandcamp": { "type": "string", "description": "Bandcamp handle from tip jar." }, "bitcoin": { "type": "string", "description": "Bitcoin address or handle." }, "cashApp": { "type": "string", "description": "Cash App handle." }, "ethereum": { "type": "string", "description": "Ethereum address or handle." }, "goFundMe": { "type": "string", "description": "GoFundMe handle." }, "patreon": { "type": "string", "description": "Patreon handle." }, "payPal": { "type": "string", "description": "PayPal handle." }, "venmo": { "type": "string", "description": "Venmo handle." } }, "description": "Per-service handles when any are present." } }, "required": ["isEnabled"], "description": "Tip jar configuration when present." }, "highlights": { "type": "object", "properties": { "canHighlightTweets": { "type": "boolean", "description": "Whether the account may highlight tweets on the profile." }, "highlightedTweetCount": { "type": "integer", "minimum": 0, "description": "Count of highlighted tweets when reported by X." } }, "required": [ "canHighlightTweets", "highlightedTweetCount" ], "description": "Tweet highlights metadata when present." }, "businessAccount": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Opaque business-account payload from X when non-empty (vendor-defined)." }, "creatorSubscriptionsCount": { "type": "integer", "minimum": 0, "description": "Creator subscriptions count when X reports it." }, "affiliateLabel": { "type": "object", "properties": { "description": { "type": "string", "description": "Affiliate or business label text shown on the profile." }, "badgeUrl": { "type": "string", "description": "Badge image URL when X provides one." }, "url": { "type": "string", "description": "Destination URL for the label link." } }, "required": ["description"], "description": "Affiliate or business label when X provides one." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "verified", "blueVerified", "profileUrl", "privateAccount" ], "description": "Profile details when available." }, "metrics": { "type": "object", "nullable": true, "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Follower count from X." }, "following": { "type": "integer", "minimum": 0, "description": "Following (friends) count from X." }, "tweets": { "type": "integer", "minimum": 0, "description": "Total post (status) count from X." }, "favourites": { "type": "integer", "minimum": 0, "description": "Total favourites (likes) count from X." }, "listedCount": { "type": "integer", "minimum": 0, "description": "Listed count when X provides it." }, "mediaCount": { "type": "integer", "minimum": 0, "description": "Media item count when X provides it." }, "fastFollowersCount": { "type": "integer", "minimum": 0, "description": "Fast-followers count when X provides it." } }, "required": [ "followers", "following", "tweets", "favourites" ], "description": "Profile metrics when available." } }, "required": ["lookupStatus", "profile", "metrics"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "twitter", "handle": "alexbishop2002", "displayName": "alexbishop", "bio": "Love football i follow back up the posh", "avatarUrl": "https://pbs.twimg.com/profile_images/506120681910964224/Qycpq4pO_400x400.jpeg", "bannerUrl": "https://pbs.twimg.com/profile_banners/2262329555/1409503563", "verified": false, "blueVerified": false, "profileUrl": "https://x.com/alexbishop2002", "privateAccount": false, "platformUserId": "2262329555", "accountCreatedAt": 1388859821, "location": null, "website": null, "verificationInfo": { "isIdentityVerified": false }, "tipJar": { "isEnabled": false }, "highlights": { "canHighlightTweets": false, "highlightedTweetCount": 0 }, "creatorSubscriptionsCount": 0 }, "metrics": { "followers": 44, "following": 0, "tweets": 98, "favourites": 47, "listedCount": 0, "mediaCount": 13, "fastFollowersCount": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "twitter", "handle": "alexbishop2002", "displayName": "alexbishop", "bio": "Love football i follow back up the posh", "avatarUrl": "https://pbs.twimg.com/profile_images/506120681910964224/Qycpq4pO_400x400.jpeg", "bannerUrl": "https://pbs.twimg.com/profile_banners/2262329555/1409503563", "verified": false, "blueVerified": false, "profileUrl": "https://x.com/alexbishop2002", "privateAccount": false, "platformUserId": "2262329555", "accountCreatedAt": 1388859821, "location": null, "website": null, "verificationInfo": { "isIdentityVerified": false }, "tipJar": { "isEnabled": false }, "highlights": { "canHighlightTweets": false, "highlightedTweetCount": 0 }, "creatorSubscriptionsCount": 0 }, "metrics": { "followers": 44, "following": 0, "tweets": 98, "favourites": 47, "listedCount": 0, "mediaCount": 13, "fastFollowersCount": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "private": { "value": { "data": { "lookupStatus": "private", "profile": { "platform": "twitter", "handle": "lukem1221", "displayName": "Luke", "bio": null, "avatarUrl": "https://pbs.twimg.com/profile_images/1999456116619771904/rmqNgqiu_400x400.jpg", "bannerUrl": null, "verified": false, "blueVerified": false, "profileUrl": "https://x.com/lukem1221", "privateAccount": true, "platformUserId": "761228485981528065", "accountCreatedAt": 1470325989, "location": null, "website": "https://www.voicegecko.io/", "verificationInfo": { "isIdentityVerified": false }, "tipJar": { "isEnabled": false }, "highlights": { "canHighlightTweets": false, "highlightedTweetCount": 0 }, "creatorSubscriptionsCount": 0 }, "metrics": { "followers": 115, "following": 97, "tweets": 47, "favourites": 48, "listedCount": 3, "mediaCount": 5, "fastFollowersCount": 0 } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "metrics": null }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/profiles/{handle}/tweets": { "get": { "tags": ["Twitter"], "summary": "List Twitter profile tweets", "description": "Returns up to roughly 100 of the account's most popular public tweets as ranked by X. This is not a chronological timeline and is not paginated with a cursor. For handle resolution, inspect `data.lookupStatus` (`found` vs `not_found`). An empty `data.tweets` array can still accompany `lookupStatus: \"found\"` when the account resolves but has no eligible tweets in this set—call `GET /v1/twitter/profiles/{handle}` first if you need `private` vs `not_found` for the account itself.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-agent-hints": { "emptyResults": "An empty `data.tweets` array can occur with `lookupStatus: \"found\"` (no popular public tweets in this window) or `lookupStatus: \"not_found\"` (handle did not resolve).", "disambiguation": "Call `GET /v1/twitter/profiles/{handle}` when you must distinguish `private` from `not_found` before interpreting an empty tweet list." }, "parameters": [ { "schema": { "type": "string", "description": "X handle to look up, with or without a leading @." }, "required": true, "description": "X handle to look up, with or without a leading @.", "name": "handle", "in": "path" }, { "schema": { "type": "boolean", "description": "Optional: omit per-tweet author and profile card for a smaller response." }, "required": false, "description": "Optional: omit per-tweet author and profile card for a smaller response.", "name": "trim", "in": "query" } ], "responses": { "200": { "description": "Tweets for the requested profile. Use `data.lookupStatus`: `not_found` when the handle cannot be resolved; `found` when the handle resolves (check `data.tweets`—it may be empty when there are no popular public tweets in this response). Prefer `GET /v1/twitter/profiles/{handle}` first if you need explicit `private` vs `not_found` for the account before interpreting an empty tweet list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether tweet data was returned for this handle." }, "profile": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["twitter"], "description": "Social platform for this profile." }, "handle": { "type": "string", "minLength": 1, "description": "Screen name without @." }, "displayName": { "type": "string", "nullable": true, "description": "Display name for the profile." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL." }, "verified": { "type": "boolean", "description": "Legacy verified flag from X." }, "blueVerified": { "type": "boolean", "description": "Paid blue verification flag from X." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical profile URL on x.com." }, "platformUserId": { "type": "string", "description": "Numeric user id as a string." } }, "required": [ "platform", "handle", "displayName", "avatarUrl", "verified", "blueVerified", "profileUrl" ], "description": "Profile card from the first tweet when full data is available; null when trimmed or not found." }, "tweets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": ["contentType", "url"], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." }, "quotedTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": [ "contentType", "url" ], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Expanded quoted tweet (one level deep)." }, "retweetedTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": [ "contentType", "url" ], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Expanded reposted tweet (one level deep)." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ] }, "description": "Up to roughly 100 popular public tweets from X for this request (not chronological). May be empty when `lookupStatus` is `found` and no eligible tweets are returned, or when `lookupStatus` is `not_found`." } }, "required": ["lookupStatus", "profile", "tweets"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "profile": { "platform": "twitter", "handle": "elonmusk", "displayName": "Elon Musk", "avatarUrl": "https://pbs.twimg.com/profile_images/1_normal.jpg", "verified": false, "blueVerified": true, "profileUrl": "https://x.com/elonmusk", "platformUserId": "44196397" }, "tweets": [ { "id": "2044683867630833961", "url": "https://x.com/elonmusk/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1732838400, "language": "en", "text": "Example tweet text", "isLongForm": false, "displayTextRange": [0, 18], "author": { "handle": "elonmusk", "displayName": "Elon Musk", "avatarUrl": "https://pbs.twimg.com/profile_images/1_normal.jpg", "verified": false, "blueVerified": true, "platformUserId": "44196397" }, "metrics": { "views": 1000, "favorites": 10, "retweets": 2, "replies": 1, "bookmarks": 0, "quotes": 0 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": false, "isRetweet": false, "possiblySensitive": false, "source": "Twitter for iPhone", "sourceUrl": "http://twitter.com/download/iphone" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "profile": { "platform": "twitter", "handle": "elonmusk", "displayName": "Elon Musk", "avatarUrl": "https://pbs.twimg.com/profile_images/1_normal.jpg", "verified": false, "blueVerified": true, "profileUrl": "https://x.com/elonmusk", "platformUserId": "44196397" }, "tweets": [ { "id": "2044683867630833961", "url": "https://x.com/elonmusk/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1732838400, "language": "en", "text": "Example tweet text", "isLongForm": false, "displayTextRange": [0, 18], "author": { "handle": "elonmusk", "displayName": "Elon Musk", "avatarUrl": "https://pbs.twimg.com/profile_images/1_normal.jpg", "verified": false, "blueVerified": true, "platformUserId": "44196397" }, "metrics": { "views": 1000, "favorites": 10, "retweets": 2, "replies": 1, "bookmarks": 0, "quotes": 0 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": false, "isRetweet": false, "possiblySensitive": false, "source": "Twitter for iPhone", "sourceUrl": "http://twitter.com/download/iphone" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_trimmed": { "value": { "data": { "lookupStatus": "found", "profile": null, "tweets": [ { "id": "2044683867630833961", "url": "https://x.com/elonmusk/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1732838400, "language": "en", "text": "Example tweet text", "isLongForm": false, "displayTextRange": [0, 18], "author": null, "metrics": { "views": 1000, "favorites": 10, "retweets": 2, "replies": 1, "bookmarks": 0, "quotes": 0 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": false, "isRetweet": false, "possiblySensitive": false } ] }, "meta": { "requestId": "req_01example_trim", "creditsCharged": 1, "version": "v1" } } }, "empty": { "value": { "data": { "lookupStatus": "found", "profile": null, "tweets": [] }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "profile": null, "tweets": [] }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid handle or bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/search": { "get": { "tags": ["Twitter"], "summary": "Search Twitter posts", "description": "Searches public posts on X by keyword and optional engagement/date filters. Pagination uses an opaque `cursor` returned by a previous response.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 2, "surcharges": [], "maxCredits": 2, "normalizationFailureCredits": 2 }, "x-socialfetch-credits-pricing": "2 credit base (up to 2 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Search query text to run against public posts on X." }, "required": true, "description": "Search query text to run against public posts on X.", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": ["top", "latest", "people", "photos", "videos"], "description": "Optional search section filter. Omit to use the default `top` section." }, "required": false, "description": "Optional search section filter. Omit to use the default `top` section.", "name": "section", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional minimum retweet count filter." }, "required": false, "description": "Optional minimum retweet count filter.", "name": "minRetweets", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional minimum like count filter." }, "required": false, "description": "Optional minimum like count filter.", "name": "minLikes", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "description": "Optional minimum reply count filter." }, "required": false, "description": "Optional minimum reply count filter.", "name": "minReplies", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Optional page size. Maximum supported value is 20." }, "required": false, "description": "Optional page size. Maximum supported value is 20.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional start date filter in YYYY-MM-DD format." }, "required": false, "description": "Optional start date filter in YYYY-MM-DD format.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional end date filter in YYYY-MM-DD format." }, "required": false, "description": "Optional end date filter in YYYY-MM-DD format.", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt", "ru", "zh", "ja", "ko", "ar", "bg", "hr", "cs", "da", "nl", "et", "fi", "el", "hu", "id", "ga", "lv", "lt", "no", "pl", "ro", "sk", "sl", "sv", "tr", "uk", "vi", "cy", "zu" ], "description": "Optional language filter." }, "required": false, "description": "Optional language filter.", "name": "language", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Opaque pagination cursor returned by a previous response." }, "required": false, "description": "Opaque pagination cursor returned by a previous response.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Search results for the requested query.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tweets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id." }, "url": { "type": "string", "nullable": true, "description": "Canonical public URL for the tweet when available." }, "text": { "type": "string", "description": "Full tweet text when available." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "createdAtLabel": { "type": "string", "nullable": true, "description": "Human-readable creation timestamp string when available." }, "language": { "type": "string", "nullable": true, "description": "Language code for the tweet when available." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author handle without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Display name shown for the author." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Profile image URL for the author when available." }, "profileUrl": { "type": "string", "nullable": true, "description": "Canonical public profile URL for the author when available." }, "verified": { "type": "boolean", "description": "Whether the author has legacy verification on X." }, "blueVerified": { "type": "boolean", "description": "Whether the author has paid blue verification on X." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "profileUrl", "verified", "blueVerified" ], "description": "Author metadata for the tweet when available." }, "metrics": { "type": "object", "properties": { "likes": { "type": "integer", "minimum": 0, "description": "Like count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Retweet count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote count." }, "views": { "type": "integer", "nullable": true, "minimum": 0, "description": "View count when available." } }, "required": [ "likes", "retweets", "replies", "quotes", "views" ], "description": "Engagement metrics for a Twitter search result." }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Direct media URL when available." }, "type": { "type": "string", "enum": ["photo"], "description": "Media type when Social Fetch can classify it confidently." } }, "required": ["url", "type"], "description": "Media attachment on a Twitter search result." }, "description": "Media attachments returned for the tweet." }, "expandedUrl": { "type": "string", "nullable": true, "description": "Expanded URL attached to the tweet when available." }, "isRetweet": { "type": "boolean", "description": "Whether the tweet is marked as a retweet." }, "source": { "type": "string", "nullable": true, "description": "Source label such as `Twitter Web App` when available." } }, "required": [ "id", "url", "text", "createdAt", "createdAtLabel", "language", "author", "metrics", "media", "expandedUrl", "isRetweet", "source" ], "description": "A normalized Twitter search result item." }, "description": "Tweets returned for the requested search query." }, "page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor to pass as `cursor` in the next request when another page exists." }, "hasMore": { "type": "boolean", "description": "Whether another page of search results can be requested." } }, "required": ["nextCursor", "hasMore"], "description": "Pagination information for the current response." } }, "required": ["tweets", "page"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "tweets": [ { "id": "1726127805249802561", "url": "https://x.com/hack_git/status/1726127805249802561", "text": "SqliSniper...", "createdAt": 1700375913, "createdAtLabel": "Sun Nov 19 06:38:33 +0000 2023", "language": "en", "author": { "handle": "hack_git", "displayName": "HackGit", "avatarUrl": "https://pbs.twimg.com/profile_images/1430451138277556224/yDiqSjga_normal.jpg", "profileUrl": "https://x.com/hack_git", "verified": false, "blueVerified": true, "platformUserId": "1430450807451828228" }, "metrics": { "likes": 148, "retweets": 33, "replies": 1, "quotes": 0, "views": 13392 }, "media": [ { "url": "https://pbs.twimg.com/media/F_RwCCTXsAADBL8.png", "type": "photo" } ], "expandedUrl": "https://twitter.com/hack_git/status/1726127805249802561/photo/1", "isRetweet": false, "source": "Twitter Web App" } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01twittersearch", "creditsCharged": 2, "version": "v1" } }, "examples": { "results": { "value": { "data": { "tweets": [ { "id": "1726127805249802561", "url": "https://x.com/hack_git/status/1726127805249802561", "text": "SqliSniper...", "createdAt": 1700375913, "createdAtLabel": "Sun Nov 19 06:38:33 +0000 2023", "language": "en", "author": { "handle": "hack_git", "displayName": "HackGit", "avatarUrl": "https://pbs.twimg.com/profile_images/1430451138277556224/yDiqSjga_normal.jpg", "profileUrl": "https://x.com/hack_git", "verified": false, "blueVerified": true, "platformUserId": "1430450807451828228" }, "metrics": { "likes": 148, "retweets": 33, "replies": 1, "quotes": 0, "views": 13392 }, "media": [ { "url": "https://pbs.twimg.com/media/F_RwCCTXsAADBL8.png", "type": "photo" } ], "expandedUrl": "https://twitter.com/hack_git/status/1726127805249802561/photo/1", "isRetweet": false, "source": "Twitter Web App" } ], "page": { "nextCursor": "opaque_cursor_token", "hasMore": true } }, "meta": { "requestId": "req_01twittersearch", "creditsCharged": 2, "version": "v1" } } }, "empty": { "value": { "data": { "tweets": [], "page": { "nextCursor": null, "hasMore": false } }, "meta": { "requestId": "req_01twittersearch_empty", "creditsCharged": 2, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/tweets": { "get": { "tags": ["Twitter"], "summary": "Get Twitter tweet", "description": "Returns public metadata and engagement for a single tweet on X, including author profile context and an expanded quoted tweet when present.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Tweet permalink or identifier." }, "required": true, "description": "Tweet permalink or identifier.", "name": "url", "in": "query" }, { "schema": { "type": "boolean", "description": "Optional: omit author profile and tweet `core` for a smaller response." }, "required": false, "description": "Optional: omit author profile and tweet `core` for a smaller response.", "name": "trim", "in": "query" } ], "responses": { "200": { "description": "Tweet details when available. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the tweet was found or unavailable." }, "author": { "type": "object", "nullable": true, "properties": { "profile": { "type": "object", "properties": { "platform": { "type": "string", "enum": ["twitter"], "description": "Social platform for this profile." }, "handle": { "type": "string", "description": "X screen name (handle) without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Display name shown on the profile." }, "bio": { "type": "string", "nullable": true, "description": "Profile biography text." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar image URL." }, "bannerUrl": { "type": "string", "nullable": true, "description": "Profile banner image URL when available." }, "verified": { "type": "boolean", "description": "Whether X marks the profile with legacy verification (not necessarily paid blue)." }, "blueVerified": { "type": "boolean", "description": "Whether the account has X blue (paid) verification." }, "profileUrl": { "type": "string", "minLength": 1, "description": "Canonical public profile URL on x.com." }, "privateAccount": { "type": "boolean", "description": "Whether the account is protected (private)." }, "platformUserId": { "type": "string", "description": "Numeric X user id (`rest_id`) as a string." }, "accountCreatedAt": { "type": "integer", "minimum": 0, "description": "Account creation time as Unix epoch seconds when derivable." }, "location": { "type": "string", "nullable": true, "description": "Location string from the profile when provided." }, "website": { "type": "string", "nullable": true, "description": "Primary outbound link (expanded URL) from the profile." }, "pinnedTweetId": { "type": "string", "description": "Pinned tweet id when X exposes one." }, "verificationInfo": { "type": "object", "properties": { "isIdentityVerified": { "type": "boolean", "description": "Whether X marks the account as identity-verified." }, "verifiedSinceMsec": { "type": "string", "description": "When verification became effective, as milliseconds since epoch (string from X)." }, "reason": { "type": "object", "properties": { "text": { "type": "string", "description": "Human-readable verification reason text from X." }, "entities": { "type": "array", "items": { "nullable": true }, "description": "Inline entity metadata for the reason text (vendor-defined)." } }, "description": "Verification reason payload when X provides it." } }, "required": ["isIdentityVerified"], "description": "Structured verification metadata from X." }, "tipJar": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "description": "Whether the X tip jar is enabled." }, "handles": { "type": "object", "properties": { "bandcamp": { "type": "string", "description": "Bandcamp handle from tip jar." }, "bitcoin": { "type": "string", "description": "Bitcoin address or handle." }, "cashApp": { "type": "string", "description": "Cash App handle." }, "ethereum": { "type": "string", "description": "Ethereum address or handle." }, "goFundMe": { "type": "string", "description": "GoFundMe handle." }, "patreon": { "type": "string", "description": "Patreon handle." }, "payPal": { "type": "string", "description": "PayPal handle." }, "venmo": { "type": "string", "description": "Venmo handle." } }, "description": "Per-service handles when any are present." } }, "required": ["isEnabled"], "description": "Tip jar configuration when present." }, "highlights": { "type": "object", "properties": { "canHighlightTweets": { "type": "boolean", "description": "Whether the account may highlight tweets on the profile." }, "highlightedTweetCount": { "type": "integer", "minimum": 0, "description": "Count of highlighted tweets when reported by X." } }, "required": [ "canHighlightTweets", "highlightedTweetCount" ], "description": "Tweet highlights metadata when present." }, "businessAccount": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Opaque business-account payload from X when non-empty (vendor-defined)." }, "creatorSubscriptionsCount": { "type": "integer", "minimum": 0, "description": "Creator subscriptions count when X reports it." }, "affiliateLabel": { "type": "object", "properties": { "description": { "type": "string", "description": "Affiliate or business label text shown on the profile." }, "badgeUrl": { "type": "string", "description": "Badge image URL when X provides one." }, "url": { "type": "string", "description": "Destination URL for the label link." } }, "required": ["description"], "description": "Affiliate or business label when X provides one." } }, "required": [ "platform", "handle", "displayName", "bio", "avatarUrl", "verified", "blueVerified", "profileUrl", "privateAccount" ], "description": "Profile fields for the tweet author." }, "metrics": { "type": "object", "properties": { "followers": { "type": "integer", "minimum": 0, "description": "Follower count from X." }, "following": { "type": "integer", "minimum": 0, "description": "Following (friends) count from X." }, "tweets": { "type": "integer", "minimum": 0, "description": "Total post (status) count from X." }, "favourites": { "type": "integer", "minimum": 0, "description": "Total favourites (likes) count from X." }, "listedCount": { "type": "integer", "minimum": 0, "description": "Listed count when X provides it." }, "mediaCount": { "type": "integer", "minimum": 0, "description": "Media item count when X provides it." }, "fastFollowersCount": { "type": "integer", "minimum": 0, "description": "Fast-followers count when X provides it." } }, "required": [ "followers", "following", "tweets", "favourites" ], "description": "Aggregate counts for the tweet author." } }, "required": ["profile", "metrics"], "description": "Author profile and metrics when not trimmed; null when `trim=true` or when not found." }, "tweet": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": ["contentType", "url"], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." }, "quotedTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": [ "contentType", "url" ], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Quoted tweet expanded one level (no further nesting on this field)." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Tweet body, metrics, and optional quoted tweet; null when not found." } }, "required": ["lookupStatus", "author", "tweet"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "author": { "profile": { "platform": "twitter", "handle": "elonmusk", "displayName": "Elon Musk", "bio": "https://t.co/dDtDyVssfm", "avatarUrl": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_400x400.jpg", "bannerUrl": "https://pbs.twimg.com/profile_banners/44196397/1774145451", "verified": false, "blueVerified": true, "profileUrl": "https://x.com/elonmusk", "privateAccount": false, "platformUserId": "44196397", "verificationInfo": { "isIdentityVerified": false }, "tipJar": { "isEnabled": false }, "highlights": { "canHighlightTweets": false, "highlightedTweetCount": 0 } }, "metrics": { "followers": 238150369, "following": 1312, "tweets": 101374, "favourites": 222983, "listedCount": 167711, "mediaCount": 4451, "fastFollowersCount": 0 } }, "tweet": { "id": "2044683867630833961", "url": "https://x.com/elonmusk/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1745784397, "language": "en", "text": "Look at the tiny cars in the foreground to get a sense of the vastness of the building", "isLongForm": false, "displayTextRange": [0, 86], "metrics": { "views": 12708412, "favorites": 30931, "retweets": 3097, "replies": 2215, "bookmarks": 945, "quotes": 71 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": true, "quotedTweetId": "2044505822533705783", "isRetweet": false, "possiblySensitive": false, "source": "Twitter for iPhone", "sourceUrl": "http://twitter.com/download/iphone" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "author": { "profile": { "platform": "twitter", "handle": "elonmusk", "displayName": "Elon Musk", "bio": "https://t.co/dDtDyVssfm", "avatarUrl": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_400x400.jpg", "bannerUrl": "https://pbs.twimg.com/profile_banners/44196397/1774145451", "verified": false, "blueVerified": true, "profileUrl": "https://x.com/elonmusk", "privateAccount": false, "platformUserId": "44196397", "verificationInfo": { "isIdentityVerified": false }, "tipJar": { "isEnabled": false }, "highlights": { "canHighlightTweets": false, "highlightedTweetCount": 0 } }, "metrics": { "followers": 238150369, "following": 1312, "tweets": 101374, "favourites": 222983, "listedCount": 167711, "mediaCount": 4451, "fastFollowersCount": 0 } }, "tweet": { "id": "2044683867630833961", "url": "https://x.com/elonmusk/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1745784397, "language": "en", "text": "Look at the tiny cars in the foreground to get a sense of the vastness of the building", "isLongForm": false, "displayTextRange": [0, 86], "metrics": { "views": 12708412, "favorites": 30931, "retweets": 3097, "replies": 2215, "bookmarks": 945, "quotes": 71 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": true, "quotedTweetId": "2044505822533705783", "isRetweet": false, "possiblySensitive": false, "source": "Twitter for iPhone", "sourceUrl": "http://twitter.com/download/iphone" } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_trimmed": { "value": { "data": { "lookupStatus": "found", "author": null, "tweet": { "id": "2044683867630833961", "url": "https://x.com/i/status/2044683867630833961", "conversationId": "2044683867630833961", "createdAt": 1745784397, "language": "en", "text": "Look at the tiny cars in the foreground to get a sense of the vastness of the building", "isLongForm": false, "displayTextRange": [0, 86], "metrics": { "views": 12708412, "favorites": 30931, "retweets": 3097, "replies": 2215, "bookmarks": 945, "quotes": 71 }, "media": [], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": true, "quotedTweetId": "2044505822533705783", "isRetweet": false, "possiblySensitive": false, "source": "Twitter for iPhone", "sourceUrl": "http://twitter.com/download/iphone" } }, "meta": { "requestId": "req_01example_trim", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "author": null, "tweet": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/communities": { "get": { "tags": ["Twitter"], "summary": "Get Twitter community", "description": "Returns metadata for a single X community by URL.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Community URL to look up." }, "required": true, "description": "Community URL to look up.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Community details when available. Check `data.lookupStatus` for `found` vs `not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether the community was found or not found." }, "community": { "type": "object", "nullable": true, "properties": { "platform": { "type": "string", "enum": ["twitter"], "description": "Social platform for this community." }, "id": { "type": "string", "minLength": 1, "description": "Numeric community identifier as a string." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public community URL on x.com." }, "name": { "type": "string", "minLength": 1, "description": "Community display name." }, "description": { "type": "string", "nullable": true, "description": "Short description text when available." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch milliseconds." }, "memberCount": { "type": "integer", "minimum": 0, "description": "Approximate member count." }, "isNsfw": { "type": "boolean", "description": "Whether the community is marked as sensitive." }, "joinPolicy": { "type": "string", "enum": ["open", "restricted"], "description": "Who can join this community." }, "primaryTopic": { "type": "string", "nullable": true, "description": "Primary topic label when available." }, "bannerImageUrl": { "type": "string", "nullable": true, "description": "Banner image URL when available." }, "creator": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Creator screen name without the leading @." }, "verified": { "type": "boolean", "description": "Whether X marks the creator with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the creator has X blue (paid) verification." } }, "required": [ "handle", "verified", "blueVerified" ], "description": "Creator handle and verification flags when available." }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable rule identifier." }, "name": { "type": "string", "minLength": 1, "description": "Short rule title." }, "description": { "type": "string", "nullable": true, "description": "Longer rule explanation when provided." } }, "required": ["id", "name", "description"], "description": "A published community rule." }, "description": "Published community rules." }, "memberFacepileAvatarUrls": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Recent member avatar image URLs shown in the community preview." }, "trendingHashtags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Trending hashtags associated with this community when available." } }, "required": [ "platform", "id", "url", "name", "description", "createdAt", "memberCount", "isNsfw", "joinPolicy", "primaryTopic", "bannerImageUrl", "creator", "rules", "memberFacepileAvatarUrls", "trendingHashtags" ], "description": "Community details when available." } }, "required": ["lookupStatus", "community"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "community": { "platform": "twitter", "id": "1493446837214187523", "url": "https://x.com/i/communities/1493446837214187523", "name": "Build in Public", "description": "Share what you're working on. Get feedback. Help each other move forward.", "createdAt": 1644900447551, "memberCount": 254959, "isNsfw": false, "joinPolicy": "open", "primaryTopic": "Entrepreneurship", "bannerImageUrl": "https://pbs.twimg.com/community_banner_img/example.png", "creator": { "handle": "marckohlbrugge", "verified": false, "blueVerified": true }, "rules": [ { "id": "1493447542045958144", "name": "Share what you're working on", "description": "Don't be scared to share unfinished work" } ], "memberFacepileAvatarUrls": [ "https://pbs.twimg.com/profile_images/example_normal.jpg" ], "trendingHashtags": ["#design", "#code"] } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "community": { "platform": "twitter", "id": "1493446837214187523", "url": "https://x.com/i/communities/1493446837214187523", "name": "Build in Public", "description": "Share what you're working on. Get feedback. Help each other move forward.", "createdAt": 1644900447551, "memberCount": 254959, "isNsfw": false, "joinPolicy": "open", "primaryTopic": "Entrepreneurship", "bannerImageUrl": "https://pbs.twimg.com/community_banner_img/example.png", "creator": { "handle": "marckohlbrugge", "verified": false, "blueVerified": true }, "rules": [ { "id": "1493447542045958144", "name": "Share what you're working on", "description": "Don't be scared to share unfinished work" } ], "memberFacepileAvatarUrls": [ "https://pbs.twimg.com/profile_images/example_normal.jpg" ], "trendingHashtags": ["#design", "#code"] } }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_restricted": { "value": { "data": { "lookupStatus": "found", "community": { "platform": "twitter", "id": "1453811010935001090", "url": "https://x.com/i/communities/1453811010935001090", "name": "The Entrepreneurship Community", "description": "A community for both aspiring and current entrepreneurs.", "createdAt": 1635450530170, "memberCount": 430, "isNsfw": false, "joinPolicy": "restricted", "primaryTopic": null, "bannerImageUrl": "https://pbs.twimg.com/list_banner_img/example.png", "creator": { "handle": "harleyf", "verified": false, "blueVerified": true }, "rules": [ { "id": "1453811497495248897", "name": "Be kind.", "description": "It's simple. No discrimination, no hate, no put-downs. Be kind." } ], "memberFacepileAvatarUrls": [ "https://pbs.twimg.com/profile_images/example2_normal.jpg" ], "trendingHashtags": [] } }, "meta": { "requestId": "req_01example_r", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "community": null }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } }, "/v1/twitter/communities/tweets": { "get": { "tags": ["Twitter"], "summary": "List Twitter community tweets", "description": "Returns tweets for a single X community by URL. Check `data.lookupStatus` for `found` vs `not_found`. A `found` result may still include an empty `data.tweets` array when the community resolves but no tweets are returned in this response.", "security": [ { "ApiKeyAuth": [] } ], "x-socialfetch-pricing": { "version": 1, "baseCredits": 1, "surcharges": [], "maxCredits": 1, "normalizationFailureCredits": 1 }, "x-socialfetch-credits-pricing": "1 credit base (up to 1 credits on success). See `meta.creditsCharged`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Community URL to look up." }, "required": true, "description": "Community URL to look up.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "Tweets for the requested community. Use `data.lookupStatus` to distinguish `found` vs `not_found`. A `found` result may still include an empty `data.tweets` array.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lookupStatus": { "type": "string", "enum": ["found", "not_found"], "description": "Whether tweet data was returned for this community." }, "tweets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": ["h", "w", "resize"], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": ["contentType", "url"], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." }, "quotedTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": [ "contentType", "url" ], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Expanded quoted tweet (one level deep)." }, "retweetedTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Tweet id (`rest_id`)." }, "url": { "type": "string", "minLength": 1, "description": "Canonical public URL for this tweet on x.com." }, "conversationId": { "type": "string", "minLength": 1, "description": "Conversation root tweet id." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as Unix epoch seconds." }, "language": { "type": "string", "minLength": 1, "description": "BCP 47 or X language code." }, "text": { "type": "string", "description": "Full tweet text (includes long-form when available)." }, "isLongForm": { "type": "boolean", "description": "True when text was taken from note_tweet metadata instead of legacy.full_text alone." }, "displayTextRange": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2, "description": "Start/end character indices for visible text." }, "author": { "type": "object", "nullable": true, "properties": { "handle": { "type": "string", "minLength": 1, "description": "Author screen name without the leading @." }, "displayName": { "type": "string", "nullable": true, "description": "Author display name." }, "avatarUrl": { "type": "string", "nullable": true, "description": "Best available square avatar URL for the author." }, "verified": { "type": "boolean", "description": "Whether X marks the author with legacy verification." }, "blueVerified": { "type": "boolean", "description": "Whether the author has X blue (paid) verification." }, "platformUserId": { "type": "string", "description": "Numeric X user id for the author as a string." } }, "required": [ "handle", "displayName", "avatarUrl", "verified", "blueVerified" ], "description": "Author snapshot; null when `trim=true` omits per-tweet author data." }, "metrics": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "description": "Impression count when reported by X." }, "favorites": { "type": "integer", "minimum": 0, "description": "Favorite (like) count." }, "retweets": { "type": "integer", "minimum": 0, "description": "Native repost count." }, "replies": { "type": "integer", "minimum": 0, "description": "Reply count." }, "bookmarks": { "type": "integer", "minimum": 0, "description": "Bookmark count." }, "quotes": { "type": "integer", "minimum": 0, "description": "Quote tweet count." } }, "required": [ "views", "favorites", "retweets", "replies", "bookmarks", "quotes" ], "description": "Engagement metrics for a tweet." }, "media": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["photo"] }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the media asset." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo" ], "description": "Photo attachment on a tweet." }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["video", "animated_gif"], "description": "Video or MP4-based animated GIF." }, "id": { "type": "string", "minLength": 1, "description": "Media id string." }, "url": { "type": "string", "minLength": 1, "description": "Short t.co URL for this media." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Display URL shown in the tweet." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Expanded destination URL." }, "mediaUrlHttps": { "type": "string", "minLength": 1, "description": "HTTPS URL for the poster or media." }, "sizes": { "type": "object", "properties": { "thumb": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Thumbnail size." }, "small": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Small variant." }, "medium": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Medium variant." }, "large": { "type": "object", "properties": { "h": { "type": "integer", "minimum": 0 }, "w": { "type": "integer", "minimum": 0 }, "resize": { "type": "string", "minLength": 1 } }, "required": [ "h", "w", "resize" ], "description": "Large variant." } }, "required": [ "thumb", "small", "medium", "large" ], "description": "Per-label media dimensions from X." }, "originalInfo": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 0 }, "height": { "type": "integer", "minimum": 0 } }, "required": ["width", "height"], "description": "Original pixel dimensions." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1, "description": "MIME type of the variant (for example video/mp4 or HLS playlist)." }, "url": { "type": "string", "minLength": 1, "description": "Direct URL for this variant." }, "bitrate": { "type": "integer", "minimum": 0, "description": "Bitrate in bits per second when present (omitted for HLS)." } }, "required": [ "contentType", "url" ], "description": "A downloadable or streamable media variant." }, "minItems": 1, "description": "Stream or download variants (mp4, HLS, etc.)." }, "durationMs": { "type": "integer", "minimum": 0, "description": "Duration in milliseconds when known." }, "aspectRatio": { "type": "array", "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "minItems": 2, "maxItems": 2, "description": "Width:height ratio tuple when provided by X." } }, "required": [ "type", "id", "url", "displayUrl", "expandedUrl", "mediaUrlHttps", "sizes", "originalInfo", "variants" ], "description": "Video or animated GIF attachment." } ] }, "description": "Photo, video, or GIF attachments." }, "entities": { "type": "object", "properties": { "hashtags": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Hashtag text without #." } }, "required": ["text"], "description": "A hashtag entity." }, "description": "Hashtag entities." }, "userMentions": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "description": "Mentioned screen name." }, "displayName": { "type": "string", "description": "Display name when available." }, "platformUserId": { "type": "string", "description": "Numeric user id for the mention when available." } }, "required": ["handle"], "description": "A user mention entity." }, "description": "User mention entities." }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Short URL as it appears in text." }, "displayUrl": { "type": "string", "minLength": 1, "description": "Human-readable display host/path." }, "expandedUrl": { "type": "string", "minLength": 1, "description": "Fully expanded destination URL." } }, "required": [ "url", "displayUrl", "expandedUrl" ], "description": "A URL entity." }, "description": "URL entities." }, "symbols": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Cashtag or symbol text." } }, "required": ["text"], "description": "A symbol/cashtag entity." }, "description": "Symbol entities." } }, "required": [ "hashtags", "userMentions", "urls", "symbols" ], "description": "Entities aligned with `text`." }, "isReply": { "type": "boolean", "description": "Whether this is a reply." }, "inReplyToTweetId": { "type": "string", "description": "Parent tweet id when replying." }, "inReplyToUserId": { "type": "string", "description": "Parent author user id when replying." }, "inReplyToScreenName": { "type": "string", "description": "Parent author handle when replying." }, "isQuote": { "type": "boolean", "description": "Whether this tweet quotes another." }, "quotedTweetId": { "type": "string", "description": "Quoted tweet id when present." }, "isRetweet": { "type": "boolean", "description": "Whether this is a native repost." }, "retweetedTweetId": { "type": "string", "description": "Original tweet id for a repost." }, "possiblySensitive": { "type": "boolean", "description": "Whether X marks the content sensitive." }, "editInfo": { "type": "object", "properties": { "editTweetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tweet ids in this edit chain." }, "editableUntilMsec": { "type": "string", "description": "Epoch milliseconds until edits are locked." }, "isEditEligible": { "type": "boolean", "description": "Whether the tweet can still be edited." }, "editsRemaining": { "type": "string", "description": "Remaining edits in the window, as reported by X." } }, "required": [ "editTweetIds", "editableUntilMsec", "isEditEligible", "editsRemaining" ], "description": "Edit metadata when applicable." }, "source": { "type": "string", "description": "Client label text (for example “Twitter for iPhone”)." }, "sourceUrl": { "type": "string", "description": "Link target from the source anchor when present." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ], "description": "Expanded reposted tweet (one level deep)." } }, "required": [ "id", "url", "conversationId", "createdAt", "language", "text", "isLongForm", "displayTextRange", "author", "metrics", "media", "entities", "isReply", "isQuote", "isRetweet", "possiblySensitive" ] }, "description": "Tweets returned for the requested community. This array may be empty when `lookupStatus` is `found` and no tweets are returned in this response, or when `lookupStatus` is `not_found`." } }, "required": ["lookupStatus", "tweets"], "description": "Endpoint-specific response payload." }, "meta": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "description": "Unique request identifier for tracing this API call." }, "creditsCharged": { "type": "integer", "minimum": 0, "description": "Credits charged for this request." }, "version": { "type": "string", "enum": ["v1"], "description": "Public API version that served the response." } }, "required": ["requestId", "creditsCharged", "version"], "description": "Metadata describing the request and billing outcome." } }, "required": ["data", "meta"], "description": "Standard success response envelope." }, "example": { "data": { "lookupStatus": "found", "tweets": [ { "id": "2044666255446057399", "url": "https://x.com/dev_olayinka/status/2044666255446057399", "conversationId": "2044666255446057399", "createdAt": 1776322598, "language": "en", "text": "As a developer, do you read documentation? https://t.co/RoYi39THKY", "isLongForm": false, "displayTextRange": [0, 42], "author": { "handle": "dev_olayinka", "displayName": "Olayinka", "avatarUrl": "https://pbs.twimg.com/profile_images/example_normal.jpg", "verified": false, "blueVerified": false, "platformUserId": "1800534842133647360" }, "metrics": { "views": 30202, "favorites": 94, "retweets": 8, "replies": 27, "bookmarks": 3, "quotes": 0 }, "media": [ { "type": "photo", "id": "2044666242594754560", "url": "https://t.co/RoYi39THKY", "displayUrl": "pic.x.com/RoYi39THKY", "expandedUrl": "https://x.com/dev_olayinka/status/2044666255446057399/photo/1", "mediaUrlHttps": "https://pbs.twimg.com/media/HGAdHVIX0AAq_0i.jpg", "sizes": { "thumb": { "h": 150, "w": 150, "resize": "crop" }, "small": { "h": 680, "w": 383, "resize": "fit" }, "medium": { "h": 1200, "w": 675, "resize": "fit" }, "large": { "h": 2048, "w": 1152, "resize": "fit" } }, "originalInfo": { "width": 1152, "height": 2048 } } ], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": false, "isRetweet": false, "possiblySensitive": false, "source": "Twitter for Android", "sourceUrl": "http://twitter.com/download/android" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } }, "examples": { "found": { "value": { "data": { "lookupStatus": "found", "tweets": [ { "id": "2044666255446057399", "url": "https://x.com/dev_olayinka/status/2044666255446057399", "conversationId": "2044666255446057399", "createdAt": 1776322598, "language": "en", "text": "As a developer, do you read documentation? https://t.co/RoYi39THKY", "isLongForm": false, "displayTextRange": [0, 42], "author": { "handle": "dev_olayinka", "displayName": "Olayinka", "avatarUrl": "https://pbs.twimg.com/profile_images/example_normal.jpg", "verified": false, "blueVerified": false, "platformUserId": "1800534842133647360" }, "metrics": { "views": 30202, "favorites": 94, "retweets": 8, "replies": 27, "bookmarks": 3, "quotes": 0 }, "media": [ { "type": "photo", "id": "2044666242594754560", "url": "https://t.co/RoYi39THKY", "displayUrl": "pic.x.com/RoYi39THKY", "expandedUrl": "https://x.com/dev_olayinka/status/2044666255446057399/photo/1", "mediaUrlHttps": "https://pbs.twimg.com/media/HGAdHVIX0AAq_0i.jpg", "sizes": { "thumb": { "h": 150, "w": 150, "resize": "crop" }, "small": { "h": 680, "w": 383, "resize": "fit" }, "medium": { "h": 1200, "w": 675, "resize": "fit" }, "large": { "h": 2048, "w": 1152, "resize": "fit" } }, "originalInfo": { "width": 1152, "height": 2048 } } ], "entities": { "hashtags": [], "userMentions": [], "urls": [], "symbols": [] }, "isReply": false, "isQuote": false, "isRetweet": false, "possiblySensitive": false, "source": "Twitter for Android", "sourceUrl": "http://twitter.com/download/android" } ] }, "meta": { "requestId": "req_01example", "creditsCharged": 1, "version": "v1" } } }, "found_empty": { "value": { "data": { "lookupStatus": "found", "tweets": [] }, "meta": { "requestId": "req_01example_empty", "creditsCharged": 1, "version": "v1" } } }, "not_found": { "value": { "data": { "lookupStatus": "not_found", "tweets": [] }, "meta": { "requestId": "req_01example_nf", "creditsCharged": 1, "version": "v1" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["bad_request"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "bad_request", "message": "Example message.", "requestId": "req_01example" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["unauthorized"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "unauthorized", "message": "Example message.", "requestId": "req_01example" } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["insufficient_credits"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "insufficient_credits", "message": "Example message.", "requestId": "req_01example" } } } } }, "500": { "description": "Unexpected or billing error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["internal_error"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "internal_error", "message": "Example message.", "requestId": "req_01example" } } } } }, "502": { "description": "Lookup could not be completed from the response (unexpected or invalid data).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["lookup_failed"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "lookup_failed", "message": "Example message.", "requestId": "req_01example" } } } } }, "503": { "description": "Service temporarily unavailable; safe to retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": ["temporarily_unavailable"], "description": "Machine-readable error code for the failed request." }, "message": { "type": "string", "description": "Human-readable error message." }, "requestId": { "type": "string", "description": "Unique request identifier for tracing the failed API call." } }, "required": ["code", "message", "requestId"], "description": "Error details for the failed request." } }, "required": ["error"], "description": "Standard error response envelope." }, "example": { "error": { "code": "temporarily_unavailable", "message": "Example message.", "requestId": "req_01example" } } } } } } } } } }