{"uid":"cap_rXw7c5jIq9m5rFMu8Cxou","slug":"www-surplusintelligence-ai-48f49ed1","name":"Surplus Intelligence X/Twitter User by Username Lookup","description":"X/Twitter API v2 via Surplus Intelligence: User by username (1 unit)","url":"https://www.surplusintelligence.ai/x402/api/twitter/v2/users/by/username/:username","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET","HEAD","DELETE"],"type":"string"},"pathParams":{"type":"object","required":["username"],"properties":{"username":{"type":"string","description":"X/Twitter username without @, e.g. x or elonmusk."}},"additionalProperties":false},"queryParams":{"type":"object","properties":{},"additionalProperties":false}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","properties":{"data":{},"meta":{"type":"object"},"errors":{"type":"array"}},"additionalProperties":true}}}}},"responseSchema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","name","username","withheld"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string"},"withheld":{"type":"object","required":["country_codes"],"properties":{"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"example":{"request":{"input":{"type":"http","method":"GET","pathParams":{"username":"twitter"},"queryParams":{}}},"response":{"data":{"id":"1683696495198089217","name":"Twitter","username":"twitter","withheld":{"country_codes":["JP"]}}}},"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.0128","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.0128/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.0128","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.0128","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_bEjKWBiYV1BKoLyB_4zQB","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.0128","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Fetches Twitter/X user profile data by a given username using the Twitter API v2, billed per call via x402 micropayment.","exampleAgentPrompt":"Can you look up the Twitter profile for the username 'elonmusk' and tell me their user ID and account details?","exampleUseCases":[{"title":"Verify brand account authenticity before outreach","prompt":"I need to verify that a Twitter handle I found actually belongs to the company we're trying to contact. Can you look up the profile for 'AcmeCorp' and confirm their user ID and account details?"},{"title":"Build contact database from social handles","prompt":"We have a list of influencer Twitter handles from our marketing research. Can you look up the profile for 'techinfluencer42' and get their user ID so we can add them to our contact tracking system?"},{"title":"Resolve mentions to user accounts for analysis","prompt":"Someone mentioned '@newschannel_xyz' in a discussion we're monitoring. Can you look up that Twitter username and pull their user ID and account metadata so we can check if they're verified and see their follower count?"}],"resultDescription":"Returns a Twitter API v2 user object including the user's unique ID, display name, username, and associated account metadata for the queried username. May also include errors array if the username is not found.","failureModes":["Username not found — returns errors array with 'Not Found Error'","Invalid or missing username path parameter — returns 400 or validation error","Payment failure or x402 micropayment not completed — request not processed","Rate limiting from underlying Twitter API v2 — may return 429 or error response","Private or suspended account — may return restricted data or error"],"whenToPreferThis":"Use this endpoint when you need to resolve a Twitter/X username (handle) to a structured user object including their numeric user ID, without needing tweet history or follower lists. Ideal for identity resolution, profile enrichment, or as a first step before calling other Twitter endpoints that require a user ID. Prefer this over the general user lookup endpoint when you have a username (not an ID) as your starting point.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:39:10.629Z","isFirstParty":false}