# 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.

[Get API key](https://socialtap.dev/signup/?next=%2Fplayground%2F%3Fendpoint%3Dx.friendship)

[In your agent: **X (Twitter) MCP server** →](https://socialtap.dev/mcp/x/index.md)

## 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`

[Read the API reference](https://socialtap.dev/docs/reference/x/friendship/index.md)

- **1 credit** per request, $0.75–$1.97 per 1,000 requests
- **5 typed fields** null when unknown
- **`handle`** is 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 socialtap`

`handle = elonmusk`

[Open in playground](https://socialtap.dev/playground/?endpoint=x.friendship)

cURL:

```shell
curl 'https://socialtap.dev/v1/x/friendship?handle=elonmusk&target=SpaceX' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

TypeScript SDK:

```typescript
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);
```

Node.js (fetch):

```javascript
const 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);
```

Python (requests):

```python
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"])
```

Go (net/http):

```go
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"])
}
```

200 OK:

```json
{
  "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": []
  }
}
```

## What you send and what comes back.

The [response reference](https://socialtap.dev/docs/reference/x/friendship/index.md#response) lists every field, its type and when it is `null`. [See the full schema](https://socialtap.dev/resources/relationship/index.md).

- ### 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.

- **`platform`string**: Platform ID (x, …).
- **`source`object**: The account whose follow is checked (the handle param): is_following says whether it follows target. At least its id or username.
- **`target`object**: The other account (the target param): is_followed_by says whether it follows source. At least its id or username.
- **`is_following`boolean**: True when source follows target, false when it does not; null when the platform did not say.
- **`is_followed_by`boolean**: 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.

[TikTok](https://socialtap.dev/apis/tiktok/index.md) · [Instagram](https://socialtap.dev/apis/instagram/index.md) · [Facebook](https://socialtap.dev/apis/facebook/index.md) · [YouTube](https://socialtap.dev/apis/youtube/index.md) · [Reddit](https://socialtap.dev/apis/reddit/index.md) · [Threads](https://socialtap.dev/apis/threads/index.md) · [GitHub](https://socialtap.dev/apis/github/index.md) · [LinkedIn](https://socialtap.dev/apis/linkedin/index.md) · [X](https://socialtap.dev/apis/x/index.md) · [Spotify](https://socialtap.dev/apis/spotify/index.md) · [Hacker News](https://socialtap.dev/apis/hackernews/index.md) · [Amazon](https://socialtap.dev/apis/amazon/index.md) · [Apple Music](https://socialtap.dev/apis/applemusic/index.md) · [Pinterest](https://socialtap.dev/apis/pinterest/index.md) · [Rumble](https://socialtap.dev/apis/rumble/index.md) · [Bluesky](https://socialtap.dev/apis/bluesky/index.md) · [Twitch](https://socialtap.dev/apis/twitch/index.md) · [Telegram](https://socialtap.dev/apis/telegram/index.md) · [TikTok Shop](https://socialtap.dev/apis/tiktokshop/index.md) · [Kwai](https://socialtap.dev/apis/kwai/index.md) · [Snapchat](https://socialtap.dev/apis/snapchat/index.md) · [SoundCloud](https://socialtap.dev/apis/soundcloud/index.md) · [Truth Social](https://socialtap.dev/apis/truthsocial/index.md) · [Kick](https://socialtap.dev/apis/kick/index.md) · [Komi](https://socialtap.dev/apis/komi/page/index.md) · [Lnk.Bio](https://socialtap.dev/apis/linkbio/profile/index.md) · [Linkme](https://socialtap.dev/apis/linkme/profile/index.md) · [Linktree](https://socialtap.dev/apis/linktree/profile/index.md) · [Pillar](https://socialtap.dev/apis/pillar/page/index.md) · [TikTok Ad Library](https://socialtap.dev/apis/tiktok-ad-library/index.md) · [Facebook Ad Library](https://socialtap.dev/apis/facebook-ad-library/index.md) · [Facebook Events](https://socialtap.dev/apis/facebook-events/index.md) · [Facebook Marketplace](https://socialtap.dev/apis/facebook-marketplace/index.md) · [Google Ads Transparency Center](https://socialtap.dev/apis/google-ads-transparency/index.md) · [LinkedIn Ad Library](https://socialtap.dev/apis/linkedin-ad-library/index.md)

## 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.

[Plans and packs](https://socialtap.dev/pricing/index.md) · [How this endpoint is priced](https://socialtap.dev/docs/reference/x/friendship/index.md#pricing) · [How credits work](https://socialtap.dev/docs/credits/index.md)

| 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](https://socialtap.dev/docs/reference/x/friendship/index.md).

**Can I check if two Twitter accounts follow each other?**

Yes. One request answers both directions: is_following says whether the first follows the second, is_followed_by whether the second follows back.

**Does it work for protected accounts?**

Yes. X answers the relationship of a protected account too, though its follower and following lists stay hidden.

**Can I use user IDs instead of usernames?**

Yes. Send a numeric user ID, a username or a profile link for either account, in any mix.

**How much does the X (Twitter) Friendship API cost?**

A request costs 1 credit. SocialTap credits cost $0.75–$1.97 per 1,000, depending on the plan or pack.

More X

## X API. 17 endpoints, one key.

- [X (Twitter) Post API](https://socialtap.dev/apis/x/post/index.md) (1 credit · `GET /v1/x/post`)
- [X (Twitter) Mentions API](https://socialtap.dev/apis/x/profile-mentions/index.md) (1 credit / page · `GET /v1/x/profile_mentions`)
- [X (Twitter) User Posts API](https://socialtap.dev/apis/x/posts/index.md) (1 credit / page · `GET /v1/x/posts`)
- [X (Twitter) Community Posts API](https://socialtap.dev/apis/x/community-posts/index.md) (1 credit / page · `GET /v1/x/community_posts`)
- [X (Twitter) Profile API](https://socialtap.dev/apis/x/profile/index.md) (1 credit · `GET /v1/x/profile`)
- [X (Twitter) List Followers API](https://socialtap.dev/apis/x/list-followers/index.md) (1 credit / page · `GET /v1/x/list_followers`)
- [X (Twitter) Comments API](https://socialtap.dev/apis/x/comments/index.md) (1 credit / page · `GET /v1/x/comments`)
- [X (Twitter) Video Transcript API](https://socialtap.dev/apis/x/transcript/index.md) (From 1 credit · `GET /v1/x/transcript`)
- [X (Twitter) Post Search API](https://socialtap.dev/apis/x/search-posts/index.md) (From 1 credit / page · `GET /v1/x/search_posts`)
- [X (Twitter) User Search API](https://socialtap.dev/apis/x/search-profiles/index.md) (From 1 credit / page · `GET /v1/x/search_profiles`)
- [X (Twitter) Hashtag Search API](https://socialtap.dev/apis/x/search-hashtags/index.md) (1 credit / page · `GET /v1/x/search_hashtags`)
- [X (Twitter) Community Search API](https://socialtap.dev/apis/x/search-communities/index.md) (From 1 credit / page · `GET /v1/x/search_communities`)
- [X (Twitter) List API](https://socialtap.dev/apis/x/list/index.md) (1 credit · `GET /v1/x/list`)
- [X (Twitter) Engagement API](https://socialtap.dev/apis/x/engagement/index.md) (1 credit · `GET /v1/x/engagement`)
- [X (Twitter) Community API](https://socialtap.dev/apis/x/community/index.md) (1 credit · `GET /v1/x/community`)
- [X (Twitter) Spaces API](https://socialtap.dev/apis/x/space/index.md) (1 credit · `GET /v1/x/space`)

## Try it on an account you know.

Paste its handle or link in the playground, or copy the request into your code.

100free credits

- No credit card
- Failed requests are free
- Works on all 276 endpoints

[Start for free](https://socialtap.dev/signup/) [Read the docs](https://socialtap.dev/docs/index.md)

---

[HTML version](https://socialtap.dev/apis/x/friendship/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
