X (Twitter) Friendship API. Send a handle or profile link.
Does one account follow another, and back. We handle the proxies, blocks and platform changes.
X (Twitter) Friendship API at a glance
Returns whether one X (formerly Twitter) account follows another, from two usernames, links or user IDs: is_following, is_followed_by (both true when they follow each other), each account's user ID and current username, and whether X lets the first send the second a direct message. Unknown accounts return not_found, naming which one.
GET /v1/x/friendship
- 1 credit per request, $0.75–$1.97 per 1,000 requests
- 5 typed fields null when unknown
handleis all it needs, e.g.elonmusk- 100 credits free when you sign up, no card, so you can build before you spend
Send one request. Get 5 fields back.
Copy the request in your language, or hand it to your agent. Sign up for an API key and your first 100 credits are free.
$ npm install socialtaphandle = elonmuskconst params = new URLSearchParams({
handle: "elonmusk",
target: "SpaceX",
});
const res = await fetch(`https://socialtap.dev/v1/x/friendship?${params}`, {
headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, meta } = body;
console.log(data, meta.credits_charged);import os
import requests
res = requests.get(
"https://socialtap.dev/v1/x/friendship",
params={"handle": "elonmusk", "target": "SpaceX"},
headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, meta = body["data"], body["meta"]
print(data, meta["credits_charged"])require "json"
require "net/http"
uri = URI("https://socialtap.dev/v1/x/friendship")
uri.query = URI.encode_www_form('handle' => 'elonmusk', 'target' => 'SpaceX')
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = ENV.fetch("SOCIALTAP_API_KEY")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{body["error"]["code"]}: #{body["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
pp body["data"]
puts body["meta"]["credits_charged"]<?php
$query = http_build_query([
'handle' => 'elonmusk',
'target' => 'SpaceX',
]);
$ch = curl_init('https://socialtap.dev/v1/x/friendship?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('SOCIALTAP_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
throw new RuntimeException($body['error']['code'] . ': ' . $body['error']['message']);
}
print_r($body['data']);
echo $body['meta']['credits_charged'], PHP_EOL;package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
)
func main() {
q := url.Values{}
q.Set("handle", "elonmusk")
q.Set("target", "SpaceX")
req, err := http.NewRequest("GET", "https://socialtap.dev/v1/x/friendship?"+q.Encode(), nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body struct {
Data json.RawMessage `json:"data"`
Meta map[string]any `json:"meta"`
Error *struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error"`
}
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if body.Error != nil {
log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
}
fmt.Println(string(body.Data), body.Meta["credits_charged"])
}curl 'https://socialtap.dev/v1/x/friendship?handle=elonmusk&target=SpaceX' \
-H "x-api-key: $SOCIALTAP_API_KEY"{
"data": {
"is_followed_by": true,
"is_following": true,
"platform": "x",
"platform_specific": {
"x": {
"is_messageable": true
}
},
"source": {
"avatar_url": null,
"display_name": null,
"id": "44196397",
"is_verified": null,
"url": "https://x.com/elonmusk",
"username": "elonmusk"
},
"target": {
"avatar_url": null,
"display_name": null,
"id": "34743251",
"is_verified": null,
"url": "https://x.com/SpaceX",
"username": "SpaceX"
}
},
"meta": {
"request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
"platform": "x",
"source": "api",
"is_cached": false,
"credits_charged": 1,
"latency_ms": 1000,
"fetched_at": "2026-10-25T12:00:00Z",
"input": {
"kind": "profile",
"id": "44196397",
"url": "https://x.com/elonmusk"
},
"credits_remaining": 9999,
"client_request_id": null,
"warnings": []
}
}import { SocialTap } from "socialtap";
const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY
const res = await client.x.friendship.get({ handle: "elonmusk", target: "SpaceX" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class Main {
public static void main(String[] args) throws Exception {
String query = "handle=" + encode("elonmusk")
+ "&target=" + encode("SpaceX");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://socialtap.dev/v1/x/friendship?" + query))
.header("x-api-key", System.getenv("SOCIALTAP_API_KEY"))
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// An error is {"error": {"code", "message", ...}}; success is {data, meta}, meta.credits_charged its price.
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());
}
static String encode(String value) {
return URLEncoder.encode(value, StandardCharsets.UTF_8);
}
}using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("SOCIALTAP_API_KEY"));
var query = string.Join("&",
"handle=" + Uri.EscapeDataString("elonmusk"),
"target=" + Uri.EscapeDataString("SpaceX"));
var res = await http.GetAsync("https://socialtap.dev/v1/x/friendship?" + query);
using var body = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
if (!res.IsSuccessStatusCode)
{
var error = body.RootElement.GetProperty("error");
throw new Exception($"{error.GetProperty("code")}: {error.GetProperty("message")}");
}
Console.WriteLine(body.RootElement.GetProperty("data"));
Console.WriteLine(body.RootElement.GetProperty("meta").GetProperty("credits_charged"));// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use std::env;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let res = reqwest::blocking::Client::new()
.get("https://socialtap.dev/v1/x/friendship")
.query(&[("handle", "elonmusk"), ("target", "SpaceX")])
.header("x-api-key", env::var("SOCIALTAP_API_KEY")?)
.send()?;
let ok = res.status().is_success();
let body: serde_json::Value = res.json()?;
if !ok {
return Err(format!("{}: {}", body["error"]["code"], body["error"]["message"]).into());
}
println!("{} {}", body["data"], body["meta"]["credits_charged"]);
Ok(())
}200 OK · GET https://socialtap.dev/v1/x/friendshipDocs What you send and what comes back.
The response reference lists every field, its type and when it is null. See the full schema.
Null means unknown
A field X doesn't show is null, never zero or an empty string, so a real zero always means zero.
What it accepts
The account whose follow is checked (the source): a username with or without the @ (NASA, @NASA), a numeric user ID (11348282), or a profile link (x.com/NASA, twitter.com/NASA, x.com/i/user/11348282, an intent link with ?screen_name= or ?user_id=).
What comes back
Follow relationship between two accounts: whether the first follows the second, and whether it is followed back.
platformstring- Platform ID (x, …).
sourceobject- The account whose follow is checked (the handle param): is_following says whether it follows target. At least its id or username.
targetobject- The other account (the target param): is_followed_by says whether it follows source. At least its id or username.
is_followingboolean- True when source follows target, false when it does not; null when the platform did not say.
is_followed_byboolean- True when target follows source, false when it does not; null when the platform did not say. Both true: they follow each other.
Live data from 35 platforms.
What teams build with the X (Twitter) Friendship API.
Check whether a creator follows your brand back
Verify a follow for a giveaway entry
Map who follows whom among a set of accounts
Resolve two usernames to user IDs in one request
Good to know before you build.
- source and target in the answer carry each account's ID, username and profile link. Display names, pictures and checks are null: the X Profile API returns them.
- platform_specific.x.is_messageable is true when the target follows the source or accepts messages from anyone.
- A suspended account comes back with is_following and is_followed_by false: X doesn't flag the suspension here.
- The same account as both handle and target returns invalid_input in any two forms, such as a username and its user ID, and costs nothing.
1 credit per request. Failed requests are free.
Buy credits once and spend them on any endpoint, on any platform.
| Source | Price per successful request | Per 1,000 requests |
|---|---|---|
| Any source | 1 credit | $0.75–$1.97 |
- Cache hits are free.
- Credits from packs and top-ups never expire.
- A monthly plan's credits are spent first, and what is left of them ends at each renewal.
- Prices exclude tax: sales tax is added at checkout where it applies.
- Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID.
Questions about the X (Twitter) Friendship API.
More in the API reference.
Can I check if two Twitter accounts follow each other?
Does it work for protected accounts?
Can I use user IDs instead of usernames?
How much does the X (Twitter) Friendship API cost?
Try it on an account you know.
Paste its handle or link in the playground, or copy the request into your code.
- No credit card
- Failed requests are free
- Works on all 276 endpoints