# X (Twitter): Get a profile

`x/profiles/get` · version 1.0.0 · pilot · 1 credits a call

A profile on X (Twitter) by its handle: its name, bio, links, follower and tweet counts, verification, affiliation and images, read with your connected X account.

Categories: Social media, Lead generation

## When to use

You want who an account on X is and how big: pass its handle (nasa, @nasa) or its profile's address. One call, one profile. A protected profile is given as any other (`is_protected`): only its posts are kept from those who do not follow it. It needs one of your X accounts connected (POST /v2/accounts), and X counts each account's requests: about 150 profiles for 15 minutes. For what the account posts, use x/tweets/list with the same handle.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "x", "operation": "profiles/get", "options": {"profile": "nasa"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `profile` | string | yes |  | The profile: its handle, with or without the @ (nasa, @nasa), or its address on x.com (https://x.com/nasa). Not its display name. |
| `account` | string |  |  | The connected X account to read with (GET /v2/accounts). Left out, the platform takes the first of your X accounts with a free slot. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"profile"` |  |
| `id` | string | The account's id: it stays when the handle changes. |
| `handle` | string | null | Its @handle, without the @, in the case the account wrote it. |
| `name` | string | null | The display name. |
| `url` | string | null (uri) | The profile's page. |
| `description` | string | null | The bio, as X gives it: its links are t.co addresses. |
| `description_language` | string | null | The bio's language, as X detects it. |
| `description_urls` | array | The links of the bio |
| `location` | string | null | As the account wrote it. |
| `website_url` | string | null | The profile's link, in full. |
| `created_at` | string | null (date-time) | When the account joined X. |
| `follower_count` | integer | null |  |
| `following_count` | integer | null |  |
| `tweet_count` | integer | null | Its posts, reposts and replies. |
| `media_count` | integer | null | Its tweets with a photo or a video. |
| `like_count` | integer | null | The tweets the account liked. |
| `is_blue_verified` | boolean | null | The check mark next to the name, whatever its colour. |
| `is_verified` | boolean | null | X's earlier verification. |
| `verified_type` | string | null | business (gold check) or government (grey check), when X says so. |
| `is_protected` | boolean | null | Whether only its followers see its posts. |
| `is_possibly_sensitive` | boolean | null |  |
| `professional` | object | null | The professional profile the account declared; null when it declared none. |
| `professional.type` | string | null | business or creator. |
| `professional.categories` | array | As X names them (Media Personality). |
| `avatar_url` | string | null |  |
| `banner_url` | string | null |  |
| `avatar_shape` | string | null | circle, square (organizations), hexagon. |
| `pinned_tweet_ids` | array of string | The tweet pinned at the top of its posts. |
| `is_identity_verified` | boolean | null | Whether X checked an identity document. |
| `verified_since` | string | null (date-time) | Since when it is verified; null when it is not, or when X writes a date outside the calendar. |
| `verification_reason` | string | null | Why it is verified, in X's words, as the page writes it under the check mark. |
| `affiliation` | object | null | The organization whose badge the account carries next to its name; null without one. |
| `affiliation.name` | string | null | The organization's name on the badge. |
| `affiliation.url` | string | null | The organization's profile, as X links it. |
| `affiliation.badge_url` | string | null | The badge's image. |
| `affiliation.type` | string | null | business_label on every badge seen. |
| `affiliate_count` | integer | null | For an organization, the accounts affiliated to it; null for others. |
| `parody_label` | string | null | parody, commentary or fan, when the account carries that label. |
| `interstitial` | string | null | The warning X puts before the profile, when any. |
| `highlighted_tweet_count` | integer | null | The tweets of its Highlights tab. |
| `subscription_count` | integer | null | The creators the account subscribes to. |
| `has_hidden_subscriptions` | boolean | null | Whether it hides them on its profile. |
| `is_subscribable` | boolean | null | Whether the account sells subscriptions. |
| `birthdate` | object | null | The birth date the profile shows; null when it shows none. |
| `birthdate.day` | integer | null |  |
| `birthdate.month` | integer | null |  |
| `birthdate.year` | integer | null | Null when the profile hides the year. |
| `observed_at` | string (date-time) | When we read it. |

Example:

```json
{
  "object": "profile",
  "id": "11348282",
  "handle": "NASA",
  "name": "NASA",
  "url": "https://x.com/NASA",
  "description": "Making the seemingly impossible, possible. ✨",
  "description_language": "en",
  "description_urls": [],
  "location": "Pale Blue Dot",
  "website_url": "http://www.nasa.gov/",
  "created_at": "2007-12-19T20:20:32Z",
  "follower_count": 92233097,
  "following_count": 115,
  "tweet_count": 74544,
  "media_count": 28250,
  "like_count": 17111,
  "is_blue_verified": true,
  "is_verified": false,
  "verified_type": "government",
  "is_protected": false,
  "is_possibly_sensitive": false,
  "professional": null,
  "avatar_url": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
  "banner_url": "https://pbs.twimg.com/profile_banners/11348282/1788992290",
  "avatar_shape": "square",
  "pinned_tweet_ids": [],
  "affiliation": null,
  "is_identity_verified": false,
  "verified_since": "2009-08-07T19:53:50Z",
  "verification_reason": "This account is verified because it is a government or multilateral organization account.  Learn more",
  "affiliate_count": 85,
  "parody_label": null,
  "interstitial": null,
  "highlighted_tweet_count": 292,
  "subscription_count": 0,
  "has_hidden_subscriptions": false,
  "is_subscribable": false,
  "birthdate": {
    "day": 1,
    "month": 10,
    "year": 1958
  },
  "observed_at": "2026-11-17T15:00:00Z"
}
```

## Price

1 credit per call that returns the profile. A failed call (no such profile, a suspended one) and a busy account are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_profile` | 422 | no | Pass a profile's handle (nasa, @nasa) or its address (https://x.com/nasa). |
| `profile_not_found` | 404 | no | X has no profile with this handle (not charged). |
| `profile_unavailable` | 404 | no | X does not show this profile, suspended or withheld (not charged). |
| `account_required` | 422 | no | You have no connected X account. Connect one with POST /v2/accounts {"site": "x", "cookies": ...}: the cookies of a browser where you are logged in to x.com (https://docs.lobstr.io/accounts). |
| `account_rate_limited` | 429 | yes | This X account cannot read a profile right now: it pauses a couple of seconds between two profiles, and X counts each account's requests (about 150 profiles for 15 minutes). `retry_after` says when it can again, in seconds. Retrying before then gets this same answer: nothing is queued. |
| `account_unusable` | 409 | no | X logged this account out, or locked it. Open x.com in the browser the account comes from, then connect it again with POST /v2/accounts and fresh cookies (the same account keeps its id). |
| `site_unavailable` | 503 | yes | X did not answer properly; retry later (not charged). |
| `unexpected_answer` | 424 | no | X answered in a shape we do not read yet; we are told and fix it (not charged). |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **1.0.0** (2026-11-17): First version on the API v2, in place of the v1 Twitter Profile Scraper: a profile by its handle or its address, with its counts, verification, affiliation, professional profile and images, read with your own connected X account.

Schema: https://api.lobstr.io/v2/catalog/x/profiles/get · All operations: https://api.lobstr.io/v2/catalog.md
