X (Twitter)

View API reference · Tags X, Social media lookup

We built X (Twitter) coverage as a live GTM surface: who a prospect is on the network, what they post, who engages with it, and who follows whom. X is also the one social network where a handle converts directly into a LinkedIn URL, which makes it the shortest path from a public post to a contactable person.

This is similar to an X profile, an X search, or a TweetDeck column — tweets, replies, quotes, retweeters, and followers as structured fields.

Inputs and pagination

X list routes are the exception to the rest of the social API: they return nextCursor and you send it back as cursor — the two field names differ. Omit cursor on the first page. A null nextCursor means there are no more pages. Use a cursor promptly rather than storing it and reusing it later.

What you can call

Accounts

Search and conversations

Example — POST /v1/twitter/profile:

{
  "apiKey": "YOUR_API_KEY",
  "handle": "vp_growth_eng"
}

Finding someone's LinkedIn from their X handle

twitterHandleToLinkedinUrl (POST /v1/twitter-handle-to-linkedin/single) is synchronous — one HTTP call, answer in the response body. There is no batch version of it.

Request:

{
  "apiKey": "YOUR_API_KEY",
  "handle": "@vp_growth_eng",
  "context": "growth engineering lead at a Series B fintech"
}

handle takes a bare handle, an @handle, or a full X profile URL. context is optional and worth sending whenever the display name is common — it is what separates the right Jane Smith from the other four.

You get HTTP 200 on both a hit and a miss. On a miss, linkedInUrl is null and confidenceOutOf10 is 0. Treat a non-null linkedInUrl as the hit signal rather than checking xProfile, which can be null even on a successful match. Allow up to about 60 seconds for the call to return.

The lookup is charged for the attempt, so a miss still costs credits. Read chargeInfo rather than assuming a null result was free.

Once you have the LinkedIn URL, the person is an ordinary Fiber profile — Contact Reveal does not care how you found it.

Finding someone's X or Instagram from their name or LinkedIn

Going the other direction, person first and handle second, is a background job even for a single person. Ask for platforms: ["TWITTER"], ["INSTAGRAM"], or both; you are charged per platform you ask for.

Identify the person one of three ways:

• inputType: "linkedinUrl" — a LinkedIn URL, slug, or entity URN
• inputType: "linkedinUserId" — the numeric LinkedIn user ID
• inputType: "manual" — fullName plus optional company, job title, and work email

A LinkedIn URL on its own is enough — you do not have to supply a name alongside it. overallContext (up to 1,000 characters) applies to the whole request and helps with common names. customerProvidedId on each person is echoed back so you can join results to your own rows.

Trigger, then wait. The first poll is usually still running — status moves through pending and in_progress before completed or failed. Polling is free, but subscribing to the social_media_lookup.completed webhook beats a poll loop.

Each person carries their own outcome, and this is the field that tells you what actually happened:

Handle-first is the reliable direction. twitterHandleToLinkedinUrl starts from an identifier that is already unique, so it either matches or it does not. Person-first starts from a name and has to decide which of several plausible accounts is really them — treat it as best-effort, and send context to improve the odds rather than assuming a hit.

Using it effectively

Search for intent, then resolve it. The compounding play on X is twitterSearch for people describing your problem in public, then twitterHandleToLinkedinUrl on the handles worth pursuing, then Contact Reveal. Most tools stop at the post; this takes you to an email the same day.

Send context on every LinkedIn lookup. It costs nothing extra and it is the difference between a confident match and a null on any name that is not unique. You almost always know something — the company from their bio, the role from their tweets.

Conversations are tighter audiences than followers. The replies, quotes, and retweeters of one on-topic post are people who engaged with that idea. An account's full follower list is people who tapped follow at some point, many of them years ago. Start with twitterTweetReplies and twitterTweetRetweeters before you consider a graph walk.

Cap graph walks explicitly. Followers and following are billed per page, so a large account can consume a lot of credits with no natural stopping point. Put a hard page limit in the job rather than looping until nextCursor is null.

Mind the cursor field mismatch. Reading nextCursor and sending it as cursor is the single most common integration mistake on these routes. If your paging silently returns page one forever, this is why.

Use cases

Work fresh intent the same day. Run twitterSearch with the phrasing your buyers use when something breaks, filtered to recent results. Take the posters, call twitterHandleToLinkedinUrl on each with a short context, then Contact Reveal on the LinkedIn URLs that come back. The complaint is hours old when you reach out.

Turn a competitor's launch thread into a pipeline. Find the announcement tweet, call twitterTweetDetails for its tweetId, then page twitterTweetReplies and twitterTweetQuotes. Quote-tweeters are especially useful — people who quote a launch usually have an opinion about the category. Resolve the handles to LinkedIn and enrich.

Monitor your own and your competitors' mentions. Call twitterUserMentions on a schedule for the handles you care about and diff against the last run. New mentions from accounts you do not recognise are either prospects or problems, and both are worth knowing about early.

Build a seed audience from a niche account. For a small, highly specific account (a community, a newsletter, a well-known practitioner), page twitterUserFollowing rather than followers. Who someone deliberately follows is a much stronger signal than who happened to follow them.

Attach handles to a LinkedIn list you already have. Feed the LinkedIn URLs into socialMediaLookupBatchTrigger with platforms: ["TWITTER"] and take the webhook. You end up with a list you can research on X before you write to anyone.

Credits

X data calls cost 2 credits — per request on profile and tweet details, per page of results on timelines, search, followers, following, mentions, replies, quotes, and retweeters. Each route allows 300 requests per minute; back off on HTTP 429 rather than fanning out.

Identity lookups are priced separately: twitterHandleToLinkedinUrl is 3 credits per lookup, charged whether or not it finds a match. Person → X or Instagram is 3 credits per platform searched per person, also charged when the search comes back empty. Polling is free. chargeInfo on the response is authoritative — see Billing.

Related: Social media APIs · GitHub → LinkedIn · Contact Reveal · Webhooks