{ "openapi": "3.1.0", "info": { "title": "Twitter API", "version": "1.0.0", "description": "Twitter/X scraping endpoints exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/twitter" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search": { "post": { "operationId": "search", "tags": [ "Search" ], "summary": "Search X/Twitter by keyword", "description": "Run a Twitter search using the selected product view such as Top, Latest, People, Media, or Lists. Results include tweet text, author info, engagement counts, and media metadata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query." }, "product": { "type": "string", "description": "Twitter product tab.", "example": "Top" }, "count": { "type": "number", "description": "Number of results (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor for next page." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "openai", "product": "Latest", "count": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique tweet identifier." }, "text": { "type": "string", "description": "Full tweet text with URLs t.co-unwrapped." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "description": "Author handle without @." }, "displayName": { "type": "string", "description": "Author display name." }, "isVerified": { "type": "boolean", "description": "Whether the author is verified." } }, "additionalProperties": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "likeCount": { "type": "number", "description": "Number of likes." }, "replyCount": { "type": "number", "description": "Number of replies." }, "retweetCount": { "type": "number", "description": "Number of retweets/reposts." }, "viewCount": { "type": "number", "description": "Impression count (when available)." }, "url": { "type": "string", "description": "Canonical tweet URL." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor for the next page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "results": [ { "id": "1942939879222220800", "text": "Just tried the new GPT-4o vision features on the OpenAI playground — it correctly described a screenshot of our dashboard in one prompt. Incredible.", "author": { "handle": "devuser", "displayName": "Dev User", "isVerified": false }, "createdAt": "2026-07-01T18:42:00.000Z", "likeCount": 142, "replyCount": 23, "retweetCount": 31, "viewCount": 8200, "url": "https://x.com/devuser/status/1942939879222220800" }, { "id": "1942939879222220801", "text": "OpenAI just dropped a new fine-tuning API endpoint. Docs are live at platform.openai.com", "author": { "handle": "aibuilder", "displayName": "AI Builder", "isVerified": true }, "createdAt": "2026-07-01T18:30:00.000Z", "likeCount": 891, "replyCount": 156, "retweetCount": 210, "viewCount": 51000, "url": "https://x.com/aibuilder/status/1942939879222220801" } ], "cursor": "DAABCgABF8zK9v__-V8" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/tweet-detail": { "post": { "operationId": "tweet-detail", "tags": [ "Content" ], "summary": "Fetch a tweet by ID", "description": "Retrieve detailed metadata for a specific tweet by ID including full text, media, engagement stats, and thread context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tweetId": { "type": "string", "description": "Tweet ID." }, "screenName": { "type": "string", "description": "Optional screen name context for URL construction." } }, "additionalProperties": false, "required": [ "tweetId" ] }, "examples": { "default": { "value": { "tweetId": "1942939879222220800" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique tweet identifier." }, "text": { "type": "string", "description": "Full tweet text." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "description": "Author handle." }, "displayName": { "type": "string", "description": "Author display name." }, "isVerified": { "type": "boolean", "description": "Verified status." }, "followersCount": { "type": "number", "description": "Author follower count." } }, "additionalProperties": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "likeCount": { "type": "number", "description": "Like count." }, "retweetCount": { "type": "number", "description": "Retweet/repost count." }, "replyCount": { "type": "number", "description": "Reply count." }, "quoteCount": { "type": "number", "description": "Quote tweet count." }, "viewCount": { "type": "number", "description": "Impression count." }, "url": { "type": "string", "description": "Canonical tweet URL." }, "lang": { "type": "string", "description": "BCP 47 language code." }, "media": { "type": "array", "description": "Attached media (photos, videos, cards).", "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "id": "1942939879222220800", "text": "Just tried the new GPT-4o vision features on the OpenAI playground — it correctly described a screenshot of our dashboard in one prompt. Incredible.", "author": { "handle": "devuser", "displayName": "Dev User", "isVerified": false, "followersCount": 3200 }, "createdAt": "2026-07-01T18:42:00.000Z", "likeCount": 142, "retweetCount": 31, "replyCount": 23, "quoteCount": 4, "viewCount": 8200, "url": "https://x.com/devuser/status/1942939879222220800", "lang": "en", "media": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/tweet-replies": { "post": { "operationId": "tweet-replies", "tags": [ "Content" ], "summary": "Fetch replies for a tweet", "description": "Retrieve reply tweets and continuation cursors for a specific tweet. Each reply includes the same fields as a tweet result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tweetId": { "type": "string", "description": "Tweet ID." }, "screenName": { "type": "string", "description": "Optional screen name context." }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false, "required": [ "tweetId" ] }, "examples": { "default": { "value": { "tweetId": "1942939879222220800" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Reply tweet ID." }, "text": { "type": "string", "description": "Reply text." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "description": "Author handle." }, "displayName": { "type": "string", "description": "Author display name." } }, "additionalProperties": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "likeCount": { "type": "number", "description": "Like count." }, "retweetCount": { "type": "number", "description": "Retweet count." }, "replyCount": { "type": "number", "description": "Nested reply count." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor for next page." } }, "additionalProperties": false }, "examples": { "default": { "value": { "replies": [ { "id": "1942941234567890000", "text": "Absolutely. I used it to analyze a full Next.js project structure and it caught a race condition I missed.", "author": { "handle": "reactdev", "displayName": "React Dev", "isVerified": false }, "createdAt": "2026-07-01T19:05:00.000Z", "likeCount": 28, "retweetCount": 2, "replyCount": 5 }, { "id": "1942942345678900000", "text": "How does it compare to Claude Computer Use for those kinds of tasks?", "author": { "handle": "ai_researcher", "displayName": "AI Researcher", "isVerified": false }, "createdAt": "2026-07-01T19:12:00.000Z", "likeCount": 12, "retweetCount": 0, "replyCount": 8 } ], "cursor": "DAABCgABF8zK9v__-W9" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-profile-details": { "post": { "operationId": "user-profile-details", "tags": [ "Profile" ], "summary": "Fetch a user profile by handle", "description": "Retrieve a Twitter user profile and top-level account metadata by handle. Includes bio, follower/following counts, join date, and verification status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "openai" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle." }, "displayName": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Bio text." }, "isVerified": { "type": "boolean", "description": "Verification status." }, "followersCount": { "type": "number", "description": "Follower count." }, "followingCount": { "type": "number", "description": "Following count." }, "tweetsCount": { "type": "number", "description": "Total tweet count." }, "joinedAt": { "type": "string", "description": "Account creation timestamp (ISO 8601)." }, "location": { "type": "string", "description": "Profile location (optional)." }, "website": { "type": "string", "description": "Profile website URL (optional)." }, "avatarUrl": { "type": "string", "description": "Profile image URL." }, "bannerUrl": { "type": "string", "description": "Header banner URL (optional)." } }, "additionalProperties": false }, "examples": { "default": { "value": { "handle": "OpenAI", "displayName": "OpenAI", "description": "AI research and deployment company. Creators of ChatGPT, GPT-4, DALL·E, and Sora.", "isVerified": true, "followersCount": 4300000, "followingCount": 82, "tweetsCount": 3400, "joinedAt": "2015-12-11T00:00:00.000Z", "location": "San Francisco, CA", "website": "https://openai.com", "avatarUrl": "https://pbs.twimg.com/profile_images/openai_normal.jpg", "bannerUrl": "https://pbs.twimg.com/profile_banners/openai_header.jpg" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/about-profile": { "post": { "operationId": "about-profile", "tags": [ "Profile" ], "summary": "Fetch “about this profile” metadata", "description": "Retrieve extended profile context for a Twitter account including professional category, and any linked entities.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "openai" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle." }, "category": { "type": "string", "description": "Professional category label." }, "isBusiness": { "type": "boolean", "description": "Whether the account is marked as a business." }, "isGovernment": { "type": "boolean", "description": "Whether the account is marked as a government entity." }, "affiliates": { "type": "array", "description": "Affiliated accounts or entities.", "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "handle": "OpenAI", "category": "Technology", "isBusiness": true, "isGovernment": false, "affiliates": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-tweets": { "post": { "operationId": "user-tweets", "tags": [ "Content" ], "summary": "Fetch tweets for a user", "description": "Retrieve timeline tweets for a user handle with full engagement data and pagination support.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." }, "count": { "type": "number", "description": "Number of tweets (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor for next page." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "openai", "count": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tweets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Tweet ID." }, "text": { "type": "string", "description": "Full tweet text." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "likeCount": { "type": "number", "description": "Like count." }, "replyCount": { "type": "number", "description": "Reply count." }, "retweetCount": { "type": "number", "description": "Retweet count." }, "viewCount": { "type": "number", "description": "Impression count." }, "url": { "type": "string", "description": "Canonical tweet URL." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false }, "examples": { "default": { "value": { "tweets": [ { "id": "1942900000000000000", "text": "Introducing GPT-4.1 — our most capable model yet, with improved reasoning, coding, and instruction following. Rolling out to API users starting today.", "createdAt": "2026-07-01T14:00:00.000Z", "likeCount": 12500, "replyCount": 2100, "retweetCount": 3400, "viewCount": 1200000, "url": "https://x.com/OpenAI/status/1942900000000000000" }, { "id": "1942800000000000000", "text": "Sora is now available to all ChatGPT Plus and Pro subscribers. Create realistic and imaginative videos from text instructions.", "createdAt": "2026-06-30T16:00:00.000Z", "likeCount": 9800, "replyCount": 1600, "retweetCount": 2800, "viewCount": 950000, "url": "https://x.com/OpenAI/status/1942800000000000000" } ], "cursor": "DAABCgABF8zK9v__-X0" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/user-replies": { "post": { "operationId": "user-replies", "tags": [ "Content" ], "summary": "Fetch replies by a user", "description": "Retrieve recent replies authored by a user handle across different tweet threads.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." }, "count": { "type": "number", "description": "Number of replies (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "sama", "count": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "replies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Reply tweet ID." }, "text": { "type": "string", "description": "Reply text." }, "inReplyToId": { "type": "string", "description": "Tweet ID being replied to." }, "author": { "type": "object", "properties": { "handle": { "type": "string", "description": "Author handle." } }, "additionalProperties": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp." }, "likeCount": { "type": "number", "description": "Like count." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false }, "examples": { "default": { "value": { "replies": [ { "id": "1942950000000000000", "text": "We think this is the most important capability for agents. More to share soon.", "inReplyToId": "1942900000000000000", "author": { "handle": "sama", "displayName": "Sam Altman" }, "createdAt": "2026-07-01T15:30:00.000Z", "likeCount": 4200 } ], "cursor": "DAABCgABF8zK9v__-Y1" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/following": { "post": { "operationId": "following", "tags": [ "Network" ], "summary": "Fetch following list", "description": "Retrieve accounts followed by a user with basic profile metadata per account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." }, "count": { "type": "number", "description": "Number of accounts (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "sama", "count": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "description": "User handle." }, "displayName": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Bio text." }, "isVerified": { "type": "boolean", "description": "Verification status." }, "followersCount": { "type": "number", "description": "Follower count." }, "avatarUrl": { "type": "string", "description": "Profile image URL." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false }, "examples": { "default": { "value": { "users": [ { "handle": "gdb", "displayName": "Greg Brockman", "description": "President & Co-Founder @OpenAI.", "isVerified": true, "followersCount": 1200000, "avatarUrl": "https://pbs.twimg.com/profile_images/gdb_normal.jpg" }, { "handle": "miramurati", "displayName": "Mira Murati", "description": "CTO @OpenAI.", "isVerified": true, "followersCount": 450000, "avatarUrl": "https://pbs.twimg.com/profile_images/mira_normal.jpg" } ], "cursor": "DAABCgABF8zK9v__-Z2" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/followers": { "post": { "operationId": "followers", "tags": [ "Network" ], "summary": "Fetch followers list", "description": "Retrieve follower accounts for a user with the same profile metadata shape as the following endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." }, "count": { "type": "number", "description": "Number of accounts (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "sama", "count": 2 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "description": "User handle." }, "displayName": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Bio text." }, "isVerified": { "type": "boolean", "description": "Verification status." }, "followersCount": { "type": "number", "description": "Follower count." }, "avatarUrl": { "type": "string", "description": "Profile image URL." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false }, "examples": { "default": { "value": { "users": [ { "handle": "karpathy", "displayName": "Andrej Karpathy", "description": "Building @EurekaLabsAI. Previously: Director of AI @Tesla, founding team @OpenAI, CS PhD @Stanford.", "isVerified": true, "followersCount": 1100000, "avatarUrl": "https://pbs.twimg.com/profile_images/karpathy_normal.jpg" }, { "handle": "ylecun", "displayName": "Yann LeCun", "description": "Professor at NYU. Chief AI Scientist at Meta. Turing Award. Researcher in AI, Machine Learning, Robotics, etc.", "isVerified": true, "followersCount": 850000, "avatarUrl": "https://pbs.twimg.com/profile_images/ylecun_normal.jpg" } ], "cursor": "DAABCgABF8zK9v__-Z3" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/verified-followers": { "post": { "operationId": "verified-followers", "tags": [ "Network" ], "summary": "Fetch blue-verified followers", "description": "Retrieve blue-verified followers for a user — useful for filtering high-signal accounts from large follower lists. Returns the same profile shape as the followers endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "description": "Twitter handle without @." }, "count": { "type": "number", "description": "Number of accounts (max 100).", "example": "25" }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false, "required": [ "handle" ] }, "examples": { "default": { "value": { "handle": "openai", "count": 2 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string", "description": "User handle." }, "displayName": { "type": "string", "description": "Display name." }, "description": { "type": "string", "description": "Bio text." }, "isVerified": { "type": "boolean", "description": "Always true for this endpoint." }, "followersCount": { "type": "number", "description": "Follower count." }, "avatarUrl": { "type": "string", "description": "Profile image URL." } }, "additionalProperties": false } }, "cursor": { "type": "string", "description": "Pagination cursor." } }, "additionalProperties": false }, "examples": { "default": { "value": { "users": [ { "handle": "satyanadella", "displayName": "Satya Nadella", "description": "Chairman and CEO at Microsoft.", "isVerified": true, "followersCount": 3200000, "avatarUrl": "https://pbs.twimg.com/profile_images/satya_normal.jpg" }, { "handle": "elonmusk", "displayName": "Elon Musk", "description": "Mars & Cars, Chips & Dips", "isVerified": true, "followersCount": 180000000, "avatarUrl": "https://pbs.twimg.com/profile_images/elon_normal.jpg" } ], "cursor": "DAABCgABF8zK9v__-Z4" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }