# X Profile Info (twitter)

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/x/profile/info` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/x-profile-info |

## Description

X Profile Info API: fetch public X/Twitter profile data (bio, followers, verification, avatars) from a username or URL via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/x/profile/info' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Profile @elonmusk on x.com

```json
{
  "url": "https://x.com/elonmusk",
  "name": "Elon Musk",
  "user_id": "44196397",
  "location": null,
  "username": "elonmusk",
  "verified": true,
  "created_at": "2009-06-02T20:12:29.000Z",
  "description": "Starmind",
  "tweet_count": 104989,
  "followers_count": 240609640,
  "following_count": 1366,
  "profile_image_url": "https://pbs.twimg.com/profile_images/2053244804520427520/m8mdWZCG_400x400.jpg",
  "profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
  "profile_image_url_normal": "https://pbs.twimg.com/profile_images/2053244804520427520/m8mdWZCG_normal.jpg"
}
```

## Documentation

## Overview
The **X Profile Info API** returns public profile data from [x.com](https://x.com) (formerly Twitter). Pass a **username**, **@handle**, or **profile URL** and receive structured JSON with bio, follower counts, verification status, and avatar URLs.

X profile pages require **browser rendering** to load JSON-LD profile data and timeline markup.

**X Search is not supported**: search results are not rendered as parseable HTML.

## Quickstart
```
GET https://api.piloterr.com/v2/x/profile/info?query=elonmusk
```

Or with a profile URL:
```
GET https://api.piloterr.com/v2/x/profile/info?query=https://x.com/elonmusk
```

Via POST:
```
POST https://api.piloterr.com/v2/x/profile/info
Content-Type: application/json

{"query": "@elonmusk", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Username, `@handle`, or profile URL on `x.com` / `twitter.com` |
| `return_page_source` | boolean | no | Return raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Username | `elonmusk` |
| Handle | `@elonmusk` |
| Profile URL | `https://x.com/elonmusk` |
| Legacy domain | `https://twitter.com/elonmusk` |

**Rejected (400):** search URLs, status URLs, invalid handles.

## Response fields
| Field | Type | Always present | Description |
|---|---|---|---|
| `user_id` | string | yes | Numeric X user ID |
| `username` | string | yes | Handle without `@` |
| `name` | string | yes | Display name |
| `description` | string \| null | no | Bio text |
| `url` | string | yes | Canonical profile URL |
| `created_at` | string \| null | no | Account creation date (ISO 8601) |
| `location` | string \| null | no | Location label |
| `verified` | boolean | yes | Verified badge |
| `followers_count` | integer \| null | no | Follower count |
| `following_count` | integer \| null | no | Following count |
| `tweet_count` | integer \| null | no | Post count |
| `profile_image_url` | string \| null | no | Avatar URL (400×400) |
| `profile_image_url_normal` | string \| null | no | Avatar URL (normal size) |
| `profile_banner_url` | string \| null | no | Profile banner URL |

Parsed from JSON-LD `ProfilePage` and banner preload tags in the rendered HTML.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | X error page, unrendered content, or profile not found |
| `500` | Rendering or parsing error |

## Notes
- Accepted domains: `x.com`, `twitter.com`.
- Costs **2 credits** per call (browser rendering, ~8s wait).
- Use **X Post Info** to fetch individual tweet data from a status URL.

## Main use cases
- **Social listening**: monitor follower counts and profile metadata
- **Lead enrichment**: resolve X handles to user IDs and bios
- **Influencer research**: collect verification status and audience size
- **Account verification**: confirm a handle exists and is active